Servidor MCP
Conecte ferramentas de IA ao Flowtly através do Model Context Protocol em mcp.flowtly.eu.
Conectar
claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp
Nesta página
Acordos
Ferramentas
| agreements_get | Obtém um acordo de emprego por id — type, variant, a janela dateFrom/dateTo, hoursPerWeek, e os campos derivados `calculable`, `active` e `status`. agreements_list fornece o id. Requer ROLE_AGREEMENTS_MANAGER ou ROLE_MEETING_MANAGER. Apenas leitura. |
| agreements_list | Lista acordos de emprego — filtra por employee (IRI), isActive, type ou variant. A FORMA de responder a "porque é que people_list diz que esta pessoa está inativa": cada linha traz `calculable` e `active`, e uma pessoa está ativa exatamente quando possui um acordo que seja ambos. Também é o local para ler os códigos `type` de acordo que esta organização realmente usa antes de chamar agreements_create, já que uma organização pode adicionar os seus próprios. Requer ROLE_AGREEMENTS_MANAGER ou ROLE_MEETING_MANAGER. Apenas leitura. |
| agreements_create | Cria um acordo de emprego para uma pessoa. ESTE É O PASSO QUE TORNA ALGUÉM ATIVO: people_create apenas cria o registo, e uma pessoa sem acordo reporta isActive false para sempre — uma importação em massa fica, por isso, 100% inativa até isto ser executado para cada uma delas. DUAS CONDIÇÕES TÊM DE SER VERDADEIRAS, ou permanecem inativas sem qualquer erro: o `type` tem de ser CALCULABLE (os tipos incorporados "agreement", "annex", "termination" são-no; "list-of-intent" e "work-experience" não são), e a janela dateFrom/dateTo tem de cobrir a data de hoje (passe dateTo como null para um contrato em curso, em vez de uma data distante no futuro). `employee` é um IRI — /people/<id> de people_list. Os types são extensíveis por organização, pelo que se deve correr agreements_list sobre alguém já ativo para ver os códigos que esta organização realmente utiliza. Requer ROLE_AGREEMENTS_MANAGER. Escrita. |
| agreements_update | Altera um acordo de emprego existente — a forma como um acordo é TERMINADO, porque o backend não expõe nenhuma operação de eliminação neste recurso: defina `dateTo` como o último dia que cobre e a pessoa deixa de estar ativa a partir daí, com o registo e o seu histórico intactos. Este é o procedimento correto para uma linha próxima da folha de pagamentos; não há forma de a fazer desaparecer, e não deveria haver. É também a forma de corrigir um `type`, `variant` ou `positionName` errados no próprio lugar, em vez de empilhar um segundo acordo sobre a pessoa — DOIS acordos não se anulam mutuamente, o calculável mantém-na ativa, pelo que "adicionar um correto ao lado" deixa silenciosamente o errado em vigor. `amount`, `amountType` e `billingType` são aceites, mas a API nunca os devolve, pelo que não é possível reler o que foi escrito. Requer ROLE_AGREEMENTS_MANAGER. Escrita. |
Tipos de Acordo
Ferramentas
| agreementTypes_get | Obtém um tipo de contrato por id — o seu name ou translationKey, `calculable`, `isActive`, `position` e `builtIn`. O id É o código, portanto isto lê de volta um tipo pela mesma string que um acordo guarda em `type`. Use-o para confirmar que um tipo persistiu depois de agreementTypes_create, e para verificar `calculable` antes de atribuir alguém a ele. Requer ROLE_USER. Apenas leitura. |
| agreementTypes_list | Lista os tipos de contrato que ESTA organização pode atribuir a um acordo — os valores por trás de `Ludzie > <person> > Umowy > Edytuj umowę`. Leia isto antes de agreements_create ou agreements_import, porque a lista é por tenant: são fornecidos cinco tipos incorporados ("agreement", "annex", "termination", "list-of-intent", "work-experience") e uma organização pode adicionar os seus próprios, pelo que um `type` válido numa organização dá 422 noutra. O ID É O CÓDIGO — o `id` de cada linha é exatamente a string que `agreements_create` espera em `type`, não uma chave numérica a consultar. `calculable` é o campo que decide se ter este tipo torna alguém ATIVO e o conta na resourcing bench, na acumulação de férias e na base de custos; um tipo não calculável deixa-o inativo sem qualquer erro, o que é intencional para um tipo como "list-of-intent" e um bug silencioso se foi escolhido por engano. As linhas `builtIn` trazem um translationKey e um name nulo; as linhas personalizadas trazem um name renderizado tal como escrito e um translationKey nulo. Requer ROLE_USER. Apenas leitura. |
| agreementTypes_create | Adiciona um tipo de contrato à lista DESTA organização, para que um acordo possa ser registado contra algo que os cinco tipos incorporados não cobrem — "Umowa zlecenie", "Kontrakt B2B", "Użytkownik funkcyjny". Isto é configuração, não uma alteração de código: a lista é uma tabela por tenant, e um tipo personalizado não necessita de nenhuma entrada de tradução, porque o seu `name` é apresentado tal como escrito em todos os sete locales. NÃO ENVIE `id`: o código é gerado a partir do name no servidor (slug), com os diacríticos removidos ("Użytkownik funkcyjny" torna-se "uzytkownik-funkcyjny"), e passar um id é recusado com 422 "Update is not allowed for this operation". Envie o name e leia o código atribuído a partir da resposta. `calculable` TEM POR OMISSÃO O VALOR FALSE E É SILENCIOSO: decide quem conta como empregado — a resourcing bench, a acumulação de férias, a base de custos e de orçamento — pelo que um tipo destinado a pessoas que NÃO devem acumular férias ou ocupar um FTE está correto com false, e um tipo destinado a emprego real TEM de o definir como true, ou todos os que o tiverem reportam inativo sem qualquer erro. Nada indicará qual dos dois se obteve. `position` ordena o dropdown; `isActive` tem por omissão true. Não existe update nem delete via MCP, de propósito — `agreement.type` guarda o id desta linha como uma string simples, sem nenhuma chave estrangeira, pelo que renomear ou remover um tipo deixa órfão todo o acordo que aponte para ele. Requer ROLE_AGREEMENTS_MANAGER. Escrita. |
Alocações
Ferramentas
| allocations_get | Uma alocação por id — a reserva de uma pessoa num projeto, com as suas datas e percentagem. allocations_list encontra o id; este devolve o registo completo. Uma alocação sem funcionário é um cargo EM ABERTO (procura não preenchida), não uma reserva. Requer o módulo de recursos. Apenas leitura. |
| allocations_list | Lista alocações de recursos — atribuições com intervalo de datas de uma posição num projeto a um funcionário (ou ainda a ninguém, um cargo em aberto). Sem filtros; pagine com cursor. Cada item traz employeeId/employeeName e projectId/projectName já resolvidos (employeeId nulo significa um cargo em aberto); positionId é simples — resolva o seu nome via positions_list. source distingue linhas importadas de folha das criadas diretamente no Flowtly. Use isto para reconciliar uma importação de folha de recursos: verifique o que ficou registado e compare com o que foi submetido. |
Reservas de Ativos
Ferramentas
| assetBookings_get | Obtém uma reserva de ativo por id — o ativo, o seu titular, as datas, e se foi cancelada. Apenas leitura. |
| assetBookings_list | Lista reservas de ativos — quem ou o que atualmente detém cada ativo; é a atribuição que o ecrã Assets mostra, e o único local onde a ligação ativo-pessoa realmente existe. Cada linha contém o ativo, o titular (`relationName` employee | project mais `relationId`), datas de início/fim e, uma vez libertada, `cancelReason` e `cancelledAt`. Filtre por `property` para ver o histórico de um ativo, ou por `employee` para ver tudo o que uma pessoa detém — esta segunda opção é a que se deve correr antes de alguém sair. Note que `employee`, aqui, é o id NUMÉRICO, e não o IRI /people que assetBookings_create espera. Adicione `exists.cancelledAt: false` para ver apenas o que ainda está atribuído; sem isso, a lista inclui também reservas já libertadas. Apenas leitura. |
| assetBookings_create | Atribui um ativo a uma pessoa ou a um projeto. `property` é o IRI do ativo (/assets/{id}) e é obrigatório. Identifique o titular de UMA de três formas: `relation` com um único IRI (/people/{id} para uma pessoa, /projects/{id} para um projeto), ou `relationName` (employee | project) mais `relationId`, ou diretamente o campo IRI `employee` / `project`. Exatamente um titular tem de se resolver — não indicar nenhum é recusado com "Employee or Project must be set." e indicar ambos com "Employee and Project cannot be set at the same time." DUAS COISAS QUE NÃO ESTÃO NO ESQUEMA E QUE VÃO DAR-LHE 422: o ativo já tem de ser reservável (`bookingAllowed: true` — defina-o com assets_update), uma regra de negócio imposta a TODOS os que chamam a API, incluindo um manager, recusada com "This asset is not reservable."; e o próprio `bookingType` do ativo (minutes | days | single-days | permanently) é o que dá sentido a `duration` / `endDate` — um espaço dedicado indefinidamente a uma pessoa é `permanently` com um `startDate` e sem fim. Reservas concorrentes sobre o mesmo ativo são serializadas no servidor, pelo que uma sobreposição é recusada em vez de gerar uma reserva dupla. Requer ROLE_PROPERTY_BOOKINGS_MANAGER para reservar em nome de outra pessoa. Escrita. |
| assetBookings_update | Atualiza uma reserva de ativo existente — as suas datas, duração, valor/moeda de faturação, ou a quota de consumo medido. `relationName` e `relationId` são exigidos pelo payload, pelo que se deve enviar o titular que a reserva já tem, a menos que se esteja deliberadamente a movê-la. Para terminar uma atribuição, use assetBookings_cancel, não um endDate no passado. Requer ROLE_PROPERTY_BOOKINGS_MANAGER. Escrita. |
| assetBookings_cancel | Liberta um ativo — a forma como uma atribuição termina, e o que mais se aproxima de uma eliminação para este recurso (não existe operação de eliminação). Recebe o id da reserva e um `cancelReason` de 3 a 255 caracteres; a reserva é mantida e marcada com `cancelledAt`, para que o histórico sobreviva, e o ativo fica livre para o próximo titular. Esta é a chamada a fazer quando um funcionário sai: assetBookings_list filtrado por `employee` encontra o que detém, e esta liberta cada um deles. Requer ROLE_PROPERTY_BOOKINGS_MANAGER. Escrita. |
Leituras de Contadores de Ativos
Ferramentas
| assetMeterReadings_get | Obtém uma leitura de contador por id — o contador, a data e o valor. Apenas leitura. |
| assetMeterReadings_list | Lista leituras de contadores — os valores datados registados num asset meter, os dados em bruto que a divisão de faturação por consumo (metered-billing) lê. Cada linha contém o contador, a data e o valor. Use-a para ler o histórico de um contador: um valor que nunca muda entre períodos (um contador encravado ou partilhado) fatura zero, e um contador sem linhas recentes é um que ninguém está a ler. Apenas leitura. |
Medidores de Ativos
Ferramentas
| assetMeters_get | Obtém um contador de ativo (asset meter) por id — o ativo a que pertence, o tipo de utilidade, a unidade e o identificador externo/QR, juntamente com as suas leituras. Apenas leitura. |
| assetMeters_list | Lista os contadores de ativos da organização — os contadores de utilidades/media associados a ativos (eletricidade, água, gás, aquecimento). Cada um traz o ativo a que pertence, o seu tipo de utilidade e unidade, e as suas leituras. Filtre por `property` (o ativo a que pertence) e `utilityType`. Use-a para resolver o id de contador que as leituras exigem, e para identificar contadores que leem zero, estão encravados num único valor, ou pertencem a um contador partilhado/coletivo. Apenas leitura. |
| assetMeters_update | Atualiza um contador de ativo — o seu label, tipo de utilidade, unidade, ou estado ativo. Use-a para retirar um contador da monitorização (por exemplo, uma utilidade agora faturada diretamente pela fatura) sem eliminar o seu histórico de leituras. Requer ROLE_PROPERTIES_MANAGER. Escrita. |
Ativos
Ferramentas
| assets_get | Obtém um ativo por id — name, status, categoria (attributeSet), parent, assetCode, número de série, datas de compra e garantia, localização e definições de reserva. Apenas leitura. |
| assets_list | Lista os ativos da organização — o registo de coisas físicas que possui ou vende, desde portáteis e secretárias a apartamentos, lugares de estacionamento e arrecadações. Filtre por status (in-stock | damaged | sold), attributeSet (a categoria pela qual a lista de Assets agrupa), bookingAllowed, ou por um name ou serialNumber parcial; ordene por name, status, serialNumber, boughtAt ou warrantyTo. NÃO É PAGINADO — o conjunto inteiro é devolvido numa única resposta, pelo que um registo grande é um payload único e não uma primeira página. Use-a para resolver o id de ativo que as reservas de ativos e os documentos de ativos exigem. Apenas leitura. |
| assets_import | Carrega MUITOS ativos numa só chamada, indexados por `assetCode` — a ferramenta para trazer um inventário de outro sistema, onde assets_create seria uma ida e volta por registo. As linhas são reconciliadas com a organização: um assetCode desconhecido cria, um conhecido atualiza no próprio lugar, uma linha coincidente é ignorada, pelo que reexecutar não altera nada e uma execução a meio é segura de repetir. `parentAssetCode` aninha uma linha sob outra PELO SEU CODE, resolvido contra a organização e contra linhas anteriores do mesmo lote; um parent que nunca se resolve falha nessa linha, em vez de a deixar silenciosamente órfã. TRÊS CAMPOS TORNAM O REGISTO LEGÍVEL, em vez de um mero nome: `attributeSetName` é a categoria que a interface mostra como Typ zasobu e pela qual a lista agrupa, `locationName` é onde a coisa está fisicamente, e `attributes` é um mapa {name: value} para área, piso, preço e tudo o resto que a origem traga. Os três são resolvidos PELO NOME — a categoria, a localização, as definições de atributos e as suas associações são encontradas ou criadas automaticamente, pelo que quem chama a API nunca lida com nenhum desses IRIs, e os nomes são comparados sem distinção entre maiúsculas/minúsculas, para que "Mieszkanie" e "mieszkanie " não possam dividir a lista em duas. `attributes` precisa de uma categoria à qual se associar, e um valor que seja interpretado como número cria um atributo numérico, decidido na primeira vez que o nome aparece. Um atributo que não consiga ser escrito NÃO faz falhar o seu ativo. PASSE dryRun:true PRIMEIRO num carregamento real de inventário — reporta would-create / would-update / would-skip por linha e não cria absolutamente nada, incluindo categorias e localizações. Máximo de 1000 linhas. Requer ROLE_PROPERTIES_MANAGER. Escrita. |
| assets_create | Cria um ativo (name + status + bookingType obrigatórios; status = in-stock | damaged | sold, bookingType = minutes | days | single-days | permanently). bookingType é obrigatório mesmo quando o ativo nunca é reservado — passe "permanently" para algo que não é emprestado, e deixe bookingAllowed a false. Dois campos transportam a estrutura: `parent` aninha um ativo sob outro (uma unidade sob um edifício, um monitor sob uma secretária), e `attributeSet` define a categoria pela qual a lista de Assets agrupa, que é também onde vivem atributos personalizados como área ou piso. `assetCode` é um identificador único entre sistemas — use-o para guardar o id que este ativo tem no sistema de origem de onde foi importado, para que uma reimportação atualize em vez de duplicar. Requer ROLE_PROPERTIES_MANAGER. Escrita. |
| assets_update | Atualiza um ativo por id — name, status, categoria, parent, assetCode, número de série, datas, localização ou definições de reserva. É assim que um ativo passa de in-stock para sold. Note que o vocabulário de status é in-stock | damaged | sold e NÃO tem estado reserved, pelo que uma reserva pendente tem de ser modelada de outra forma. Requer ROLE_PROPERTIES_MANAGER. Escrita. |
Valores de Atributos de Entidade
Ferramentas
| attributeEntityValues_list | Lista VALORES de atributos — o que um ativo, projeto, orçamento ou cliente específico efetivamente contém para um atributo vinculado. Cada linha traz o atributo, o valor, e `relationId` a identificar a entidade a que pertence. Apenas leitura. |
| attributeEntityValues_create | Define um valor de atributo numa entidade (attribute + value obrigatórios). `relation` É UM IRI — "/properties/7", não a palavra "property": o backend resolve-o e deriva o relation name a partir da classe do recurso, pelo que passar um nome simples provoca um erro. (`relationId` aceita um id simples e ainda funciona, mas está descontinuado a favor do IRI.) O atributo já tem de estar ASSOCIADO à categoria dessa entidade, ou o valor é guardado e nunca é apresentado. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
| attributeEntityValues_update | Altera um valor de atributo no próprio lugar, pelo seu id. Use isto em vez de criar um segundo valor para o mesmo par (entidade, atributo) — nada impõe unicidade, pelo que um duplicado é aceite e a interface mostra apenas um deles. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
| attributeEntityValues_delete | Remove um valor de atributo de uma entidade. A definição e a associação sobrevivem; apenas o valor desta entidade desaparece. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
Atributos
Ferramentas
| attributes_get | Obtém uma definição de atributo por id — name, type, se é required ou multiple, valor por omissão e padrão de formato. Apenas leitura. |
| attributes_list | Lista DEFINIÇÕES de atributos — os campos nomeados (área, piso, preço) que as categorias vinculam e para os quais os ativos guardam valores. Cada um tem um type: number | string | date | state | period. Apenas leitura. |
| attributes_create | Cria uma definição de atributo (name + type obrigatórios; type é number | string | date | state | period). O TYPE É A DECISÃO: é partilhado por todas as entidades que têm este atributo, pelo que um campo criado como `string` não pode mais tarde ser somado ou ordenado como número sem que todos os valores existentes sejam reescritos. Decida-o com base nos valores que realmente tem, não no primeiro que vir. Uma definição, por si só, não faz nada — associe-a a uma categoria com attributeSetAttributes_create, ou nunca aparecerá em lado nenhum. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
| attributes_update | Atualiza uma definição de atributo — name, type, required, multiple, default ou format. Alterar `type` numa definição que já tem valores é a operação arriscada: os valores existentes não são convertidos. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
Atributos de Conjuntos de Atributos
Ferramentas
| attributeSetAttributes_list | Lista as associações entre categorias e definições de atributos — quais os campos que aparecem em cada categoria. Apenas leitura. |
| attributeSetAttributes_create | Associa uma definição de atributo a uma categoria (attributeSet + attribute, ambos IRIs). É ISTO QUE FAZ UM ATRIBUTO APARECER: sem a associação, um valor pode ser escrito com sucesso numa entidade e nunca aparecerá na interface — uma falha sem sintoma. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
| attributeSetAttributes_delete | Desassocia um atributo de uma categoria. A definição e quaisquer valores sobrevivem; simplesmente deixam de ser mostrados para essa categoria, o que faz isto parecer perda de dados quando não é. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
Conjuntos de Atributos
Ferramentas
| attributeSets_get | Obtém um attribute set por id — o seu name, relationName, icon, e os atributos a ele vinculados. Apenas leitura. |
| attributeSets_list | Lista os attribute sets da organização — as CATEGORIAS sob as quais um ativo, projeto, orçamento ou cliente é arquivado. Filtre por relationName: "property" para categorias de ativos (o que a interface chama Typ zasobu e pelo qual a lista de Assets agrupa), além de "project", "budget" e "client". Recorra a isto antes de criar uma: uma categoria duplicada por erro de ortografia ou capitalização divide silenciosamente a lista que agrupa, e nada na interface explica porquê. Apenas leitura. |
| attributeSets_create | Cria uma categoria (name + relationName obrigatórios; relationName é um de property | project | budget | client, e para uma categoria de ativo é a string simples "property" — NÃO um IRI). icon opcional, de uma lista fixa (room, parking, building, office, local, desk, monitor, entre outros) que a interface mostra ao lado da categoria. LISTE PRIMEIRO: os names não são únicos, pelo que um segundo "Mieszkanie" é aceite e divide silenciosamente a lista de Assets em duas. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
| attributeSets_update | Renomeia uma categoria, altera o seu icon, ou move-a para outro relationName. É assim que uma categoria criada com um erro de escrita é corrigida em vez de duplicada. Requer ROLE_ATTRIBUTES_MANAGER. Escrita. |
Contas Bancárias
Ferramentas
| bankAccounts_get | Obtenha uma conta bancária pelo id — nome, moeda, banco e o formato em que os extratos são importados. |
| bankAccounts_list | Lista as contas bancárias da organização. Filtre por banco, ou defina hidden para incluir as arquivadas. Use-a para resolver o id de bankAccount que transactions_list filtra. |
| bankAccounts_create | Crie uma conta bancária (type, name, currency, defaultImportFormat obrigatórios). Escrita. |
| bankAccounts_update | Atualize uma conta bancária pelo id. Escrita. |
Bancos
Ferramentas
| banks_get | Obtém um banco por id — a instituição, não uma conta nela detida. Use bankAccounts_get para a conta. |
| banks_list | Lista os bancos onde as contas da organização estão domiciliadas. Os bancos ocultos são INCLUÍDOS por omissão — passe hidden=false para a vista usada nos seletores, ou hidden=true para encontrar os retirados. Use-a para resolver o id de banco pelo qual bankAccounts_list filtra e que bankAccounts_create necessita. |
| banks_create | Cria um banco — a instituição a que uma conta bancária pertence, não a própria conta (essa é bankAccounts_create). Escrita. |
| banks_update | Atualiza um banco por id. É também assim que um banco é ocultado e desocultado: defina `hidden` como true para o retirar dos seletores sem o eliminar, false para o trazer de volta. Não existe uma ferramenta de arquivo separada, porque a API não tem nenhuma ação de arquivo para um banco — a flag é o mecanismo. Escrita. |
Orçamentos
Ferramentas
| budgets_employeePnl | P&L por funcionário para um orçamento — o que o tempo de cada pessoa gerou face ao que custou. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
| budgets_get | Obtém um orçamento por id — o seu período, âmbito e definições. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
| budgets_list | Lista os orçamentos da organização — os períodos face aos quais a receita e o custo são planeados e comparados. Use-a para resolver o id de orçamento que todas as ferramentas de pnl exigem. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
| budgets_pnlByTags | P&L de um orçamento, decomposto POR TAG — income, costsByTag, costsByProject e netByTag ao longo dos períodos do orçamento. O eixo de tags é o que torna isto legível para um negócio cujos custos não são naturalmente por projeto: marque os documentos com tags, e a divisão segue-se. Inclui displayPricePerSqm quando a organização ativou o price-per-sqm e nomeou um atributo de área, o que transforma isto numa vista por metro quadrado para um promotor imobiliário. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
| budgets_pnlByTagsDrilldown | Os documentos por trás de uma célula de budgets_pnlByTags. Recorra a isto quando um total por tag parecer errado — identifica as transações que compõem o número, em vez de o deixar a adivinhar. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
Clientes
Ferramentas
| clients_get | Obtenha um cliente pelo id — nome, país, moeda, número de contribuinte e estado. |
| clients_list | Lista clientes (os clientes da organização). Filtre por status, ou por externalPaymentCustomerId para encontrar o cliente por trás de um id de fornecedor de pagamento. Use-a para resolver o id de cliente que invoices_list, deals_list, projects_list e contracts_list filtram. |
| clients_import | Carrega MUITOS clientes numa só chamada, indexados por `externalRef` — a ferramenta para trazer uma lista de clientes ou compradores de outro sistema, onde clients_create seria uma ida e volta por pessoa. As linhas são reconciliadas com a organização: um externalRef desconhecido cria, um conhecido atualiza no próprio lugar, uma linha coincidente é ignorada, pelo que reexecutar não altera nada. A referência é guardada como `externalPaymentCustomerId`, a única coluna de referência externa que um cliente tem, e `clients_list` filtra por ela. NÃO faça correspondência de clientes por nome — uma lista de compradores está cheia de apelidos partilhados e compras conjuntas. Cada resultado traz `counterpartyId`, que é o que contracts_import e contracts_create necessitam. Duas armadilhas que o esquema não consegue expressar: um `tin` é REJEITADO sem um `tinCountry`, e uma linha de contacto necessita de um e-mail, pelo que um número de telefone sozinho não pode criar uma. PASSE dryRun:true PRIMEIRO num carregamento real de onboarding. Máximo de 500 linhas. Requer ROLE_CLIENTS_MANAGER. Escrita. |
| clients_create | Crie um novo registo de cliente (name, country, currency, status, tinType obrigatórios). Escrita. |
| clients_update | Atualize um registo de cliente pelo id. Escrita. |
Chaves de Configuração
Ferramentas
| configKeys_catalog | Lista todas as chaves de configuração da organização reconhecidas pelo backend, com o seu tipo e valores permitidos. Este é o catálogo do que é configurável — leia-o antes de configs_get ou configs_update em vez de adivinhar o nome de uma chave. A permissão é aplicada por chave pelo backend, pelo que uma chave aparecer aqui não garante que o utilizador ligado possa escrevê-la. |
Configurações
Ferramentas
| configs_get | Lê um valor de configuração da organização por id, onde o id é uma chave do configKeys_catalog (por exemplo, organization-logo-url, organization-icon-url). |
| configs_update | Atualize um valor de configuração da organização pelo id (type + name obrigatórios; a permissão é aplicada por chave de configuração pelo backend). Escrita. |
Contratos
Ferramentas
| contracts_get | Obtenha um contrato pelo id — partes, direção, valor, termos cíclicos e datas. |
| contracts_list | Lista contratos. Filtre por direction — os valores guardados são "out" (vendemos / emitimos) e "in" (compramos / recebemos), mais "unknown" — um estado real e filtrável, não um erro. Um contrato criado por upload de um documento começa como "unknown" e assim permanece até ser extraído ou até uma pessoa o resolver, pelo que se deve omitir o filtro para obter os três: "in" e "out" pesquisados em separado NÃO somam o conjunto total (flowtly-mcp#130). NÃO use "outgoing"/"incoming": estes não correspondem a nada e devolvem uma lista vazia em vez de um erro. Também filtra por counterparty, project, cyclic, name ou tags. Use-a para resolver o id de contrato que contracts_paymentScheduleLines lê e ao qual deals_win pode ligar um negócio ganho. |
| contracts_paymentScheduleLines | Lista o plano de pagamentos de um contrato — as prestações em que se espera que seja faturado ou pago. Passe contractId de contracts_list. Isto é o plano, não os valores reais: compare-o com transactions_list para ver o que foi efetivamente pago. O valor de cada linha está em UNIDADES MENORES — grosze, não złote: "530000" corresponde a 5 300,00, pelo que se deve dividir por 100 antes de reportar um valor a alguém. |
| contracts_import | Carrega MUITOS contratos numa só chamada, indexados por `name` — o número do acordo. Ao contrário de um cliente ou de um ativo, um contrato NÃO tem coluna de referência externa, pelo que o name É a chave de idempotência; um lote que contenha o mesmo name duas vezes é RECUSADO POR INTEIRO, em vez de atualizar um contrato duas vezes, porque um número duplicado significa que a origem está errada. `counterpartyExternalRef` resolve o comprador através da mesma referência que foi dada a clients_import, pelo que os dois se compõem: importe os clientes, depois os contratos, sem nunca lidar com um counterparty id numérico — uma referência que não corresponda a nenhum cliente falha nessa linha, em vez de criar um contrato sem parte associada. `direction` é "out" (vendemos) ou "in" (compramos); a coluna não tem nenhuma restrição no servidor, pelo que uma palavra errada é guardada e o contrato deixa de corresponder a qualquer filtro. PASSE dryRun:true PRIMEIRO. Máximo de 500 linhas. Requer ROLE_CONTRACTS_MANAGER. Escrita. |
| contracts_create | Crie um contrato. Escrita. |
| contracts_update | Atualize um contrato pelo id. Escrita. |
| contracts_delete | Elimine um contrato pelo id. Escrita. |
Grupos de Custos
Ferramentas
| costGroups_list | Lista grupos de custos / centros de custo — os grupos sob os quais custos, fornecedores e faturas recebidas são arquivados. Use-a para resolver o id de costGroup que suppliers_create requer e que as sugestões de faturas recebidas propõem. |
| costGroups_create | Crie um grupo de custos / centro de custo (name + type obrigatórios). Escrita. |
| costGroups_update | Atualize o nome ou o tipo de um grupo de custos / centro de custo pelo id. Escrita. |
Contrapartes
Ferramentas
| counterparties_get | Obtenha uma contraparte pelo id. |
| counterparties_list | Liste as contrapartes — todas as entidades com quem a organização transaciona. As flags supplier e client indicam que papel(is) uma contraparte desempenha, e um registo pode ser ambos. É esta a entidade numa transação bancária, pelo que é contra ela que as faturas recebidas e as transações são cruzadas. Filtre por type, supplier, client, cyclic ou budgetNeutral. |
Notas de CRM
Ferramentas
| crmNotes_get | Obtenha uma nota de CRM pelo id. |
| crmNotes_list | Liste as notas escritas em leads e negócios. Filtre por lead ou deal para ler o histórico de comentários de um registo. |
| crmNotes_create | Adicione uma nota a um lead ou a um negócio (body + exatamente um de lead/deal). O autor é o utilizador ligado. Escrita. |
| crmNotes_update | Atualize o corpo de uma nota de CRM pelo id. Escrita. |
| crmNotes_delete | Elimine uma nota de CRM pelo id. Escrita. |
Motivos de Perda de Negócios
Ferramentas
| dealLostReasons_get | Obtenha um motivo de perda de negócio pelo id. |
| dealLostReasons_list | Lista, por ordem, as razões pelas quais um negócio pode ser marcado como perdido. deals_lose requer um lostReasonId daqui. |
Negócios
Ferramentas
| deals_get | Obtenha um negócio pelo id — título, cliente, fase, valor, responsável, contacto, e datas de fecho previstas e reais. |
| deals_list | Liste os negócios/oportunidades — o pipeline de vendas. Filtre por status (open / won / lost), stage, owner, client, lead, ou por intervalos de expectedCloseDate / closedAt. Os valores são em unidades menores com uma moeda explícita; não assuma a moeda predefinida da organização. |
| deals_create | Cria um deal/oportunidade. Obrigatório: title, stage (de stages_list), e uma ÂNCORA — pelo menos um de client ou lead. Um deal sem nenhum dos dois é recusado com 422 "A deal must reference a client or a lead.", pelo que se deve ancorar um prospect sem registo de cliente ao seu lead (`/leads/<id>` de leads_list), em vez de inventar um cliente; passe client (`/clients/<id>` de clients_list) assim que exista um. Definir ambos é permitido. Opcional: amountMinor, currency, expectedCloseDate, owner, contact. Criar diretamente num stage ganho exige adicionalmente client — um deal apenas com lead não pode ser ganho. Escrita. |
| deals_update | Atualiza um deal por id (title, stage, amountMinor, currency, expectedCloseDate, owner, contact, client, lead). Mover o stage é registado automaticamente. A regra de âncora de deals_create continua a aplicar-se ao resultado, pelo que não é possível limpar o único client ou lead que um deal tem — troque um primeiro. Mover um deal para um stage ganho exige client: associe o cliente aqui (ou corra leads_convert) antes de ganhar um deal apenas com lead. Escrita. |
| deals_delete | Elimine um negócio pelo id (eliminação reversível). Escrita. |
| deals_win | Marca um deal como ganho — move-o para um stage ganho e regista-o como fechado; contractId opcional associa um contrato existente. PREENCHIMENTO RETROATIVO DE UM GANHO HISTÓRICO: passe closedAt opcional (ISO-8601, por exemplo "2026-05-07" ou um timestamp completo) para registar a data em que REALMENTE fechou. Se for omitido, o servidor regista agora, o que coloca um deal antigo no valor de "ganho este mês" do mês atual — pelo que se deve definir sempre que se está a introduzir um deal fechado antes de hoje. Não pode estar no futuro (422), e PODE ser anterior ao próprio createdAt do deal: um deal criado hoje e fechado em maio é a forma normal de um preenchimento retroativo correto, não um erro. O deal já TEM de referenciar um client: ganhar um deal apenas com lead é recusado com 422 "Attach a customer before marking this deal Won.", porque não há cliente a faturar. Converta o lead num com leads_convert, ou defina client com deals_update, e depois ganhe. Escrita. |
| deals_lose | Marca um deal como perdido — requer lostReasonId (de dealLostReasons_list); lostReasonNote opcional. PREENCHIMENTO RETROATIVO DE UMA PERDA HISTÓRICA: passe closedAt opcional (ISO-8601) para registar a data em que REALMENTE fechou, exatamente como deals_win. Se for omitido, o servidor regista agora. Não pode estar no futuro (422), e pode ser anterior ao createdAt do deal. Escrita. |
| deals_reopen | Reabra um negócio ganho/perdido, devolvendo-o ao estado aberto. Escrita. |
Históricos de Fases de Negócios
Ferramentas
| dealStageHistories_get | Obtenha um registo de mudança de fase de negócio pelo id. |
| dealStageHistories_list | Lista as transições de fase de um negócio, das mais recentes para as mais antigas. Filtre por negócio. Todo deals_update que move a fase é registado aqui automaticamente, pelo que é assim que se reconstrói quanto tempo um negócio esteve em cada fase — o próprio negócio guarda apenas a fase atual. |
Departamentos
Ferramentas
| departments_list | Os departamentos da organização, com o id numérico pelo qual cada um é referenciado. LEIA ISTO ANTES de people_create ou people_update: ambos aceitam um IRI `department` e não há outra forma de descobrir um válido. A coleção não é paginada e está ordenada por name, pelo que uma única chamada devolve todos os departamentos que a organização tem. Filtre por `name` (correspondência parcial) ou `code` (exata). As linhas trazem id, name e code; `manager` é uma relação e não está incluída nas linhas da lista — leia-a a partir de people_list, pelo outro lado, se precisar dela. Requer ROLE_EMPLOYEES_VIEWER. Apenas leitura. |
| departments_create | Adiciona um departamento, para que pessoas possam ser arquivadas sob ele. `name` é obrigatório (até 128 caracteres) e é ÚNICO em toda a organização; `code` é opcional (até 64) e é TAMBÉM único — a forma abreviada que uma organização já usa nas suas próprias folhas de cálculo (CEO, TECH, PROC). `manager` é um IRI de employee opcional, de people_list. LISTE PRIMEIRO E ESPERE COLISÕES: como tanto name como code são únicos, reenviar um departamento que já existe FALHA em vez de ser idempotente, pelo que uma importação que assuma criar-linha-a-linha vai bloquear na primeira vez que encontrar um departamento que a organização já tem — tipicamente um resto de um período experimental (trial). Reconcilie essa linha com departments_update, em vez de a contornar criando outra. NÃO EXISTE DELETE: o backend não expõe nenhuma eliminação num departamento, pelo que um name ou code errado é corrigido no próprio lugar com departments_update, e nunca removido. Requer ROLE_EMPLOYEES_MANAGER. Escrita. |
| departments_update | Renomeia um departamento, atribui-lhe um code, ou define o seu manager. Esta é a ferramenta que torna uma importação de departamentos possível, e não apenas conveniente: `name` e `code` são ambos únicos, pelo que um departamento que a organização já tem — a única linha "HR" que uma prova de conceito costuma deixar para trás — não pode ser criado novamente, e a lista real é alcançada CORRIGINDO essa linha, em vez de colidir com ela. Só os campos enviados são alterados, pelo que passar apenas `code` deixa o name intacto. `id` é o id numérico de departments_list; `manager` é um IRI de employee de people_list. NÃO EXISTE DELETE, o que torna isto toda a história de reparação: um departamento criado com um erro de escrita é corrigido aqui, e um que não devesse existir só pode ser renomeado, não removido. Requer ROLE_EMPLOYEES_MANAGER. Escrita. |
Limites de Dias de Férias
Ferramentas
| holidayDaysLimits_get | Uma linha de entitlement por id — o amount, o type, a variant do contrato e a data em que entra em vigor. holidayDaysLimits_list encontra o id. Os valores estão em SEGUNDOS (#3763). Apenas leitura. |
| holidayDaysLimits_list | Quanto direito a férias/ausências cada pessoa TEM, por type — não quanto já tirou, o que é holidays_list. Filtre por employee. Uma pessoa pode ter várias linhas para o mesmo type ao longo do tempo, porque um saldo é reforçado ou corrigido: a linha EM VIGOR é a de dateFrom mais recente que já chegou, e as linhas datadas no futuro são deliberadamente ignoradas até lá. Os valores estão em SEGUNDOS (#3763) — um dia de ausência de 8h corresponde a 28800. Requer ROLE_HOLIDAYS_MANAGER. Apenas leitura. |
| holidayDaysLimits_create | Atribui a uma pessoa uma dotação de um tipo de ausência, com efeitos a partir de uma data. `seconds`, NÃO days (#3763): um dia de 8h corresponde a 28800, pelo que 21 dias são 604800, e um saldo de horas extra de 2h30 é 9000 — um valor que não tinha para onde ir enquanto isto era guardado em dias inteiros. `employee` e `holidayType` são IRIs (fornecidos por people_list e holidayTypes_list); `variant` é o tipo de contrato a que a dotação pertence (uop, b2b, uz, uod). Para CORRIGIR um saldo existente, adicione uma linha com um dateFrom posterior, em vez de editar a antiga — a linha em vigor é a mais recente cujo dateFrom já chegou, pelo que o histórico se mantém intacto e uma correção pode ser introduzida antes de entrar em vigor. (employee, holidayType, variant, dateFrom) é único, pelo que reenviar o mesmo dia não substitui nada e falha. Requer ROLE_HOLIDAYS_MANAGER. Escrita. |
| holidayDaysLimits_update | Corrige uma linha que foi introduzida incorretamente — um erro de escrita no amount, a variant errada. Os valores estão em SEGUNDOS (#3763). Esta NÃO é a forma de registar um saldo a MUDAR ao longo do tempo: para isso, use holidayDaysLimits_create para criar uma nova linha com um dateFrom posterior, o que preserva qual era o saldo anterior e quando. Editar no próprio lugar reescreve o histórico e torna o valor antigo irrecuperável. holidayDaysLimits_list encontra o id. Requer ROLE_HOLIDAYS_MANAGER. Escrita. |
Pedidos de Férias
Ferramentas
| holidayRequests_list | PEDIDOS de ausência e o seu estado — pendente, aprovado, rejeitado. Distinto de holidays_list, que são ausências já registadas: um pedido ainda por decidir não é ainda uma ausência, por isso planeie com base em holidays_list e use este para ver o que está pendente de decisão. Fornece o holidayRequestId que holidays_approve e holidays_bulkApprove utilizam. Apenas leitura. |
| holidayRequests_cancel | Cancela um pedido de ausência — use-o para limpar um pedido que nunca deveria ser processado, como uma linha deixada por um período experimental, um teste, ou alguém que já saiu. DUAS COISAS QUE SURPREENDEM AS PESSOAS. (1) NÃO ELIMINA A LINHA: o backend define o status como `canceled`, em vez de remover a linha. MAS UM PEDIDO CANCELADO DESAPARECE DE holidayRequests_list — verificado em produção: depois disso, nem a lista sem filtro nem status=canceled o devolvem. Portanto, não é possível reler o que foi cancelado, e não há undo através do MCP; tenha a certeza do id antes de chamar. (2) NÃO É O MESMO QUE REJEITAR. Rejeitar regista uma decisão — escreve uma entrada no registo de aprovações identificando-o(a) e ENVIA UM E-MAIL AO FUNCIONÁRIO a dizer que a sua ausência foi recusada — ao passo que cancelar notifica apenas o RH, e só quando `notify-hr-managers-of-leave-activity` está ativado para a organização. Para uma linha que nunca foi uma candidatura genuína, cancelar é a opção mais honesta e discreta. SÓ FUNCIONA NUM PEDIDO PENDENTE (`requested`) quando não se é o seu dono: um pedido aceite já produziu uma Holiday que isto não remove, pelo que cancelar um deixaria uma ausência reservada por trás de um pedido a ler `canceled`. Requer ROLE_HOLIDAYS_MANAGER para o pedido de outra pessoa; o requerente pode sempre cancelar o seu próprio pedido. holidayRequests_list fornece o id. Escrita. |
Feriados
Ferramentas
| holidays_active | Quem está de folga AGORA MESMO — todas as ausências atualmente em curso, em toda a organização, para todos. Esta é a ferramenta para 'quem está fora hoje', e a que deve ser cruzada antes de tratar o freePercent de resourcingBench_get como disponibilidade, porque o banco de recursos não subtrai as ausências. Ao contrário de holidays_list, não aplica âmbito de projeto e não requer permissão além de estar autenticado, pelo que a sua resposta cobre toda a organização. Devolve cada ausência com o seu tipo e datas. Apenas leitura. |
| holidays_get | Um registo de ausência por id, com o seu tipo, datas e duração. Obtenha o id de holidays_list ou holidays_active. Apenas leitura. |
| holidays_list | Ausências registadas num período — a vista de planeamento, enquanto holidays_active responde apenas sobre hoje. Filtre por funcionário, por intervalo de datas ou por projeto. O QUE VÊ DEPENDE DAS SUAS PERMISSÕES, e uma lista curta não é prova de que ninguém está ausente: um gestor de ausências ou um utilizador de contabilidade vê toda a organização, enquanto um líder de projeto ou visualizador TEM de indicar um filtro de projeto (ou perguntar sobre si próprio) e é recusado sem um — essa recusa é um limite de permissão, não um calendário vazio. Apenas leitura. |
| holidays_create | Regista uma ausência que uma pessoa está efetivamente a tirar — a própria ausência reservada, não o direito (holidayDaysLimits_create) e não uma candidatura pendente (pedidos de ausência, que ainda necessitam de aprovação). O que isto escreve é tempo livre já acordado, pelo que aparece imediatamente em holidays_list e não necessita de nenhum passo de aprovação. `employee` é um IRI de people_list; `type` é um id de holidayTypes_list. `dateFrom`/`dateTo` inclusivos, e uma só chamada cobre um intervalo inteiro em vez de uma linha por dia. Duas coisas a ter em atenção: um type cujo `descriptionRequired` seja true (leia primeiro holidayTypes_list — `vacations` costuma sê-lo) REJEITA uma criação sem `description`; e `pick-up-day` é tempo já devido, pelo que NÃO consome a dotação anual da forma como `vacations` consome — registar um dia devolvido por um feriado ao sábado como `vacations` consome silenciosamente um dia do direito de alguém. Verifique holidays_list para a mesma pessoa e datas antes de criar, porque uma sobreposição é RECUSADA, não duplicada: o backend levanta `validation_holiday_dates_overlap` como um 422 em `dateTo` quando o intervalo toca em qualquer dia já coberto por outra ausência dessa pessoa. A única exceção é restrita — duas ausências parciais de UM SÓ DIA na mesma data, de tipos DIFERENTES, ambas `vacations` ou `pick-up-day`, cujas horas somadas cabem no dia de trabalho. Qualquer outra sobreposição falha. EXISTE um holidays_update, pelo que mudar o tipo de uma ausência já não requer eliminar e depois criar. TODA A CRIAÇÃO ENVIA UM E-MAIL AO FUNCIONÁRIO, para o seu próprio endereço da empresa, a dizer que a ausência foi adicionada — pelo que carregar um ano de histórico que alguém já viveu chega à sua caixa de entrada linha a linha, e para pessoal que ainda não foram convidados é a primeira vez que ouvem falar do Flowtly. A CARREGAR UM ANO DE HISTÓRICO? Existe uma forma em lote — holidays_import reconcilia até 500 ausências numa só chamada, ignora as que já estão registadas, pelo que é seguro reexecutá-la, e tem o e-mail DESATIVADO por omissão — mas NÃO ESTÁ DISPONÍVEL NESTA LIGAÇÃO: só é servida ao âmbito interno, pelo que não a pode chamar aqui e procurá-la não a encontrará. Chame esta ferramenta em ciclo, ou peça ao seu operador Flowtly que execute o carregamento em lote. Passe `notify: false` para um BACKFILL de ausências que já aconteceram; não o altere ao registar algo novo, porque aí o e-mail é precisamente o objetivo. Suprime apenas a mensagem — a linha, o seu `createdAt` e o seu registo para processamento salarial são escritos em qualquer caso. Requer ROLE_HOLIDAYS_MANAGER. Escrita. |
| holidays_delete | Remove definitivamente uma ausência reservada — a linha é eliminada, ao contrário de holidayRequests_cancel, que apenas altera o status de um pedido. Use-a para limpar ausências que nunca deveriam ter contado: linhas de demonstração ou de teste deixadas por um período experimental, ou órfãs porque o seu funcionário foi eliminado (people_delete desassocia as ausências em vez de as remover, pelo que sobrevivem com um nome de funcionário vazio). ISTO ALTERA NÚMEROS REAIS: uma ausência reservada é `payrollEligible` e consome o direito da pessoa, pelo que eliminar uma altera o seu saldo de férias/ausências — o objetivo quando se está a limpar dados de teste, e um bug de perda de dados quando a linha era genuína. Sem undo, sem notificação. Leia primeiro holidays_list e tenha a certeza de que a linha não é histórico real: uma descrição no próprio idioma da organização, ou datas que correspondam a uma ausência real, normalmente indicam que é. Requer ROLE_HOLIDAYS_MANAGER. Escrita. |
Tipos de Férias
Ferramentas
| holidayTypes_list | Os tipos de ausência que esta organização utiliza, com o id pelo qual cada um é referenciado. Leia isto antes de holidayDaysLimits_create/update, que necessitam de um IRI holidayType e que, sem isto, teriam de ser adivinhados. O tipo que não é uma "holiday" no sentido habitual é `pick-up-day` — folga devida por horas extra já trabalhadas (em polaco, *odbior nadgodzin*), que é um saldo CONCEDIDO em vez de um direito anual. Apenas leitura. |
| holidayTypes_create | Adiciona um tipo de ausência que a organização ainda não oferece — um sabático, licença de acompanhamento familiar não remunerada, um dia de formação — para que ausências possam ser reservadas contra ele com holidays_create e uma dotação concedida com holidayDaysLimits_create. `name` (3–64 caracteres) é o que as pessoas escolhem ao reservar; `color` e `icon` são a forma como aparece no calendário; `reducesWorkingTime` a false marca tempo livre que NÃO reduz as horas esperadas do mês; e `descriptionRequired` a true faz com que o tipo exija um motivo, que holidays_create depois impõe — ver essa ferramenta para o que rejeita. `status` tem por omissão `active`, pelo que um type criado sem pensar nisso é oferecido a todos imediatamente. LEIA holidayTypes_list PRIMEIRO: os types são de âmbito organizacional, e NÃO EXISTE DELETE — um name duplicado ou mal escrito só pode ser ocultado de novo definindo status como inactive com holidayTypes_update, e mantém entretanto todas as ausências reservadas contra ele. Requer ROLE_HOLIDAYS_MANAGER. Escrita. |
| holidayTypes_update | Altera um tipo de ausência, e acima de tudo REATIVA um. `status` alterna entre `active` e `inactive`, e um type inactive é recusado por holidays_create — pelo que registar ausências históricas contra um type que a organização entretanto retirou começa aqui, e é isto que desbloqueia uma importação de histórico de ausências, em vez de enviar alguém para a interface da aplicação. DESATIVAR NÃO É ELIMINAR, e não existe delete: as ausências já reservadas mantêm um type inactive e continuam a ser lidas com ele em holidays_list, pelo que inactive significa apenas "não oferecido para novas reservas". A ARMADILHA QUE DAÍ RESULTA: reativar `vacations` para carregar as ausências do ano passado, esquecer de o voltar a colocar como `inactive`, e não se terá apenas concluído uma importação — ter-se-á alterado o que a organização oferece hoje, porque todos os funcionários que reservem ausências voltam a ver esse type na lista. Reponha-o na mesma sessão em que importou. `descriptionRequired` também afeta holidays_create, que recusa uma reserva sem descrição assim que está ativo; ativá-lo não toca nas ausências já registadas. `id` é o id em string de holidayTypes_list (`vacations`, `not-paid`), e só os campos enviados são alterados. Requer ROLE_HOLIDAYS_MANAGER. Escrita. |
Faturas Recebidas
Ferramentas
| incomingInvoices_get | Obtenha uma fatura recebida (de fornecedor) ou documento de suporte pelo id, com os respetivos campos extraídos por OCR e o estado de correspondência atual. |
| incomingInvoices_list | Lista faturas recebidas (de fornecedores) e documentos de suporte — a caixa de entrada de contabilidade. Uma fatura recebida É um documento anexado a uma transação bancária, pelo que exists.transaction=false é a forma de encontrar documentos ainda não associados a um pagamento. Filtre também por status, relatedMonth, contraparte, projeto, etiquetas ou hasDetectedProblems. Cada documento é identificado por externalId 'upload_sha256:<sha256 dos bytes>' — calcule o hash de um ficheiro e procure esse externalId aqui ANTES de incomingInvoices_create, ou vai arquivar um duplicado. |
| incomingInvoices_matchCandidates | Liste as transações bancárias que podem ser o pagamento desta fatura recebida, ordenadas pelo próprio motor de correspondência do backend. Recorra a isto quando um documento não tiver transação associada e for preciso escolher uma; prefira estes candidatos a adivinhar pelos valores por conta própria. |
| incomingInvoices_suggestions | Lê as próprias propostas do Flowtly para uma fatura recebida — correspondência de fornecedor, grupo de custos, transação bancária correspondente, aviso de duplicado. São exatamente as propostas que um humano vê na aplicação. Leia-as primeiro e depois aplique uma por id com incomingInvoices_applySuggestion, ou aceite todas com acceptAllSuggestions. Passe refresh para recalcular em vez de servir o conjunto em cache. |
| incomingInvoices_suggestionsDebug | Explica PORQUE é que as sugestões de uma fatura recebida saíram como saíram — a pontuação do motor de correspondência, para diagnosticar uma sugestão em falta ou errada. Apenas para diagnóstico; use incomingInvoices_suggestions no trabalho normal. |
| incomingInvoices_create | Arquiva uma fatura recebida (de fornecedor) ou documento de suporte na contabilidade — passe os bytes em base64 com um fileName e receivedAt. O Flowtly aplica OCR e sugere um fornecedor e uma transação bancária correspondente. O ficheiro é identificado por externalId 'upload_sha256:<sha256 dos bytes>': para evitar um duplicado, calcule o hash dos bytes e verifique incomingInvoices_list quanto a esse externalId ANTES de carregar. Escrita. |
| incomingInvoices_applySuggestion | Aceita uma das próprias sugestões do Flowtly numa fatura recebida — as mesmas propostas que um humano vê na aplicação (correspondência de fornecedor, grupo de custos, transação bancária correspondente, aviso de duplicado). Leia-as primeiro com incomingInvoices_suggestions, e depois aplique uma pelo seu id. Prefira isto a adivinhar: é o motor de correspondência do Flowtly, não o agente, que decide o que é plausível. Escrita. |
| incomingInvoices_acceptAllSuggestions | Aceite todas as sugestões pendentes de uma fatura recebida numa única chamada — o que um humano faz com o botão "aceitar tudo" da aplicação. O servidor aplica, reconstrói, e aplica novamente até não surgir nada de novo: a correspondência de transação NÃO existe até o fornecedor e o valor serem aplicados, pelo que uma única passagem deixaria o documento por associar. Devolve um relatório (o que foi aplicado, o que foi recusado e porquê, e a transação contra a qual acabou por ser arquivado). Passe dryRun para pré-visualizar sem escrever. Nunca aceita supplier_create nem um aviso de duplicado. Escrita. |
| incomingInvoices_checkEInvoices | Obtém quaisquer novas e-faturas do KSeF para a organização — o que faz o botão "Sprawdź e-faktury" da aplicação. Chame isto antes de concluir que falta a fatura de um fornecedor: sem isto não é possível distinguir "o fornecedor nunca a enviou" de "a nossa sincronização ainda não correu". Devolve assim que a obtenção é colocada em fila; releia incomingInvoices_list depois para ver o que chegou. Escrita. |
Itens de Orçamento Inicial
Ferramentas
| initialBudgetItems_list | Lista as linhas de um orçamento inicial — os valores planeados, por tag, contra os quais contractComparison é comparado. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
Orçamentos Iniciais
Ferramentas
| initialBudgets_contractComparison | PLANEADO versus CONTRATADO, por tag — os valores planeados do orçamento inicial face à soma dos valores de contratos efetivamente assinados para esse projeto. Esta é a pergunta "comprometemo-nos com mais do que orçamentámos, e onde", e é lida diretamente a partir dos contratos já existentes na organização, pelo que importar contratos torna isto respondível sem qualquer trabalho adicional. Os valores estão em grosze; um projeto com moedas mistas produz um aviso em vez de um total silenciosamente errado. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
| initialBudgets_get | Obtém um orçamento inicial por id, com os seus items. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
| initialBudgets_list | Lista orçamentos iniciais — o plano ORIGINAL de um projeto ou investimento, em oposição ao orçamento em vigor face ao qual é medido. Requer ROLE_BUDGETS_VIEWER. Apenas leitura. |
Faturas
Ferramentas
| invoices_get | Obtenha uma fatura emitida (de venda) pelo id — cliente, linhas, totais, datas de venda e emissão, estado. |
| invoices_list | Lista faturas emitidas (de venda). Filtre por cliente, etiquetas, pesquisa ou um intervalo de saleDate. Note que saleDate — não a data de emissão nem a data de criação — é o campo que invoices_export filtra, por isso use o mesmo campo aqui ao reconciliar uma exportação. |
| invoices_export | Inicia uma exportação zip de faturas EMITIDAS para um período (from/to, ambos em YYYY-MM-DD, inclusive) filtrado por DATA DE VENDA — não data de emissão nem de criação. Apenas faturas EMITIDAS são incluídas; rascunhos e faturas não enviadas ficam excluídos, mas as retificações SÃO incluídas. O parâmetro opcional client restringe a um cliente (id ou IRI de clients_list). Máximo de 200 faturas por exportação — se o período tiver mais, reduza-o (por exemplo, exporte um mês de cada vez); um período com 0 faturas emitidas também é recusado. Esta chamada apenas enfileira a tarefa (a renderização de um mês pode demorar minutos) — NÃO devolve uma ligação de transferência. Consulte invoices_exportStatus com o exportId devolvido até reportar "ready". Escrita. |
| invoices_exportStatus | Consulta o estado de uma exportação zip iniciada por invoices_export, pelo exportId. Assim que o status for "ready", a resposta inclui downloadUrl (uma ligação assinada de curta duração — expira em 1 hora, ver expiresAt), filename e byteSize; os bytes do ficheiro nunca são devolvidos por esta ferramenta. Se o status for "failed", failureReason explica o motivo. |
| invoices_import | Regista no sistema uma fatura de saída (de venda) JÁ EMITIDA — para trazer o histórico de faturação durante o onboarding. O número de fatura externo que se passa é preservado tal como está, o comprador é resolvido pelo número de identificação fiscal (criado se não existir), e a fatura entra como emitida SEM gerar um PDF, enviar e-mail ao cliente, ou submeter ao KSeF. Importar um número que já existe é uma operação sem efeito que reporta a fatura existente, pelo que uma importação em massa é segura de reexecutar — mas essa garantia só é válida para chamadas sequenciais; duas importações genuinamente concorrentes do mesmo número podem ambas ser registadas. Passe expectedGrossTotal (o valor bruto impresso no documento de origem), e a importação é recusada se este não corresponder ao total calculado a partir das linhas. buyer.tin é obrigatório — o comprador nunca é comparado pelo nome. Use invoices_create, não esta, para emitir uma fatura genuinamente nova. Escrita. Passe dryRun:true para PRÉ-VISUALIZAR sem escrever — reporta would-create / would-skip e não cria nenhuma fatura nem cliente; execute primeiro um preenchimento retroativo histórico em modo dry e verifique as contagens antes de o executar a sério. |
| invoices_create | Emite uma NOVA fatura de saída (de venda) — a ferramenta para faturar um cliente pela primeira vez. Não a confunda com as suas duas vizinhas: invoices_import regista retroativamente uma fatura JÁ emitida noutro lugar (histórico de onboarding), e incomingInvoices_create regista o documento de CUSTO de um fornecedor. A fatura entra POR ENVIAR: o status é derivado das linhas de registo da fatura, e uma fatura recém-criada não tem nenhuma, pelo que nada é gerado, enviado por e-mail, ou submetido ao KSeF por esta chamada — trate o resultado como um rascunho a rever antes de emitir. `name` é o número da fatura e é escolhido por si (máximo 32 carateres) — leia primeiro invoices_list e siga a série já existente da organização, em vez de inventar uma, porque nada aqui atribui o próximo número por si. Obrigatório: name, type ("invoice"), tinType, issueDate, saleDate, dueDate. Passe `client` (IRI de clients_list) e, para uma faturação que reconcilia mais tarde, `contract` (IRI de contracts_list), para que a fatura apareça sob esse contrato. As linhas de artigo vão em `invoiceRows` — preço unitário líquido, quantidade e uma taxa de imposto por linha; os totais são calculados a partir das linhas, não passados diretamente. A TAXA DE UMA LINHA TRANSFRONTEIRIÇA É UMA BASE LEGAL, NÃO UM NÚMERO: além das taxas numéricas, `vatRate` aceita `np I`, `np II` e `zw`, é uma string livre de 5 carateres, e nada valida qual delas envia. `np I` e `np II` são bases legais DIFERENTES e vão para campos diferentes da fatura KSeF: `np II` é P_13_9, serviços ao abrigo do art. 100 ust. 1 pkt 4 da lei polaca do IVA (os que também são declarados na declaração recapitulativa VAT-UE); `np I` é P_13_8, qualquer outro fornecimento fora da Polónia. Qual dos dois é um dado fornecimento é uma decisão fiscal: obtenha-a do contabilista da organização ou da prática confirmada da organização para esse tipo de cliente, e NÃO COPIE A TAXA DE UMA FATURA `np` QUE A ORGANIZAÇÃO JÁ TENHA — um precedente pode ele próprio estar errado. O número fiscal do comprador tem de estar já guardado SEM o prefixo do país (clients_create explica porquê) — este documento imprime tinCountry junto a tin, pelo que um cliente guardado como "RO40424862" é impresso aqui como RORO40424862. `bankAccount` (de bankAccounts_list) escolhe a conta impressa no documento, e `currency` assume por omissão a da organização. Escrita. |
| invoices_update | Corrige uma fatura de saída (de venda) por id, antes ou depois de emitida. O uso do dia a dia é corrigir um rascunho criado por invoices_create — uma data errada, uma linha errada, uma ligação a contrato em falta — em vez de a eliminar e reemitir, o que consumiria um número de fatura. Leia primeiro invoices_get: isto é um PATCH sobre um documento cujos totais são derivados das suas linhas, pelo que substituir `invoiceRows` substitui o conjunto inteiro, e uma fatura já enviada não se "desenvia" por ter sido editada. Escrita. |
Atividades do Lead
Ferramentas
| leadActivities_get | Obtém uma atividade de lead (contacto de prospeção) por id. |
| leadActivities_list | Lista os contactos de prospeção de um lead — a sua linha temporal de atividade (convite enviado, respostas, chamadas, acompanhamentos). Filtre por lead para ler o histórico de um prospeto. Este é o equivalente estruturado de crmNotes_list: as atividades são o registo de contacto tipificado e datado; as notas são comentário livre. |
| leadActivities_create | Regista UM contacto de prospeção num lead — um convite enviado, um convite aceite, uma mensagem, uma resposta, uma chamada, um acompanhamento (lead + type + occurredAt obrigatórios; channel, contact, body opcionais). É AQUI que pertence o histórico de contacto de um prospeto: uma crmNote é comentário livre, uma atividade é o registo de contacto estruturado e filtrável que a linha temporal da fila de prospeção apresenta. NÃO narre contactos numa nota. type: invite_sent | invite_accepted | message_sent | reply_received | call | meeting | follow_up | …; channel: linkedin | email | phone | …. Escrita. |
| leadActivities_update | Atualiza uma atividade de contacto registada por id (type, channel, occurredAt, body). Escrita. |
| leadActivities_delete | Elimina uma atividade de contacto registada por id. Escrita. |
| leadActivities_byList | Toda a atividade de leads numa CAMPANHA (uma lista de leads), numa só chamada — passe o id, o IRI, ou o nome exato da lista. leadActivities_list filtra por um único lead, pelo que o relatório ao nível de campanha custaria de outra forma uma chamada por membro (302 para uma lista como a PZFD); isto resolve os membros da lista e lê as suas atividades em lotes limitados. Combine com type e occurredAt.after/.before para obter as contagens que as pessoas realmente pedem: taxa de resposta (type=reply_received), taxa de bounce (type=bounced), cobertura de envio (type=message_sent). Devolve listId, listName, leadCount, e as atividades combinadas, ordenadas por occurredAt. Uma lista desconhecida é um ERRO, não um resultado vazio — pelo que um nome mal escrito não pode ser lido como "esta campanha não teve atividade". Os ids vêm de leadLists_list. Apenas leitura. |
| leadActivities_bulkImport | Regista uma vaga outbound inteira — cada mensagem realmente enviada — numa ÚNICA chamada, em vez de um leadActivities_create por mensagem. Passe um array; cada linha identifica o seu lead (leadCompanyName, comparado com um lead JÁ EXISTENTE, ou um IRI de lead) mais type e occurredAt. Dê a cada linha um externalId — o id estável por mensagem, por exemplo o id de mensagem do Gmail — e a importação torna-se idempotente: reexecutá-la, ou reexecutar uma vaga que só foi parcialmente importada, reporta duplicados em vez de os criar. As linhas sem externalId são deduplicadas por (lead, type, occurredAt, contact), a mesma chave natural que leads_bulkImport usa, pelo que uma vaga que primeiro entrou através dessa ferramenta não é duplicada aqui. Cada linha recebe o seu próprio resultado (created | duplicate | error), pelo que uma linha malformada não descarta o resto do lote. NÃO cria leads — use leads_bulkImport para isso. ≤ 1000 linhas/chamada. Escrita. |
Contactos de Leads
Ferramentas
| leadContacts_get | Obtenha um contacto de lead pelo id. |
| leadContacts_list | Liste as pessoas de contacto associadas a leads. Filtre por lead para ler os contactos de um prospect, ou por email para descobrir de que lead veio uma mensagem. |
| leadContacts_create | Adiciona uma pessoa de contacto a um lead (lead + name obrigatórios; email, phone, role, linkedinUrl, isPrimary opcionais). O URL do LinkedIn de um contacto pertence a linkedinUrl, NÃO a uma crmNote. Escrita. |
| leadContacts_update | Atualiza um contacto de lead por id — por exemplo, define linkedinUrl / email / phone assim que os encontrar. Escrita. |
| leadContacts_delete | Elimine um contacto de lead pelo id. Escrita. |
Associações a Listas de Leads
Ferramentas
| leadListMemberships_get | Obtém uma associação lead-lista por id. O seu status e lastContactedAt são um snapshot escrito por quem chamou a API, não um estado em tempo real — ver leadListMemberships_list. |
| leadListMemberships_list | Lista quais os leads que estão em quais listas de prospeção outbound. Filtre por list, lead ou status. ATENÇÃO: status e lastContactedAt são um SNAPSHOT escrito por quem quer que tenha importado ou atualizado a associação pela última vez. Não são derivados, e nada os atualiza quando uma atividade é registada — registar uma vaga de 529 follow-ups não altera nenhum dos dois campos — pelo que podem estar arbitrariamente desatualizados. Para responder a "quando é que contactámos este prospect pela última vez", leia antes o registo de atividades: leadActivities_list para um lead, leadActivities_byList para uma campanha inteira. leadListMemberships_syncFromActivities reporta a discrepância e pode corrigi-la. |
| leadListMemberships_create | Adiciona um lead a uma lista outbound (list + lead obrigatórios; status opcional). Qualquer lastContactedAt que se passe é um snapshot que nada fará avançar depois — registe também o contacto como uma atividade de lead, ou fica impossível de consultar. Escrita. |
| leadListMemberships_update | Atualiza a associação de um lead a uma lista — por exemplo, define o status de outreach (contacted/replied/bounced). status e lastContactedAt são mantidos por quem chama a API: o que se escreve mantém-se até alguém escrever de novo, e registar atividades de lead NÃO os atualiza. Escrita. |
| leadListMemberships_delete | Remova um lead de uma lista outbound. Escrita. |
Listas de Leads
Ferramentas
| leadLists_get | Obtenha uma lista de prospeção outbound pelo id. |
| leadLists_list | Lista listas de prospeção de saída. Use-a para resolver o id de lista que leadListMemberships_create utiliza. |
| leadLists_create | Crie uma lista de prospeção outbound (name obrigatório). Escrita. |
| leadLists_update | Atualize uma lista outbound pelo id. Escrita. |
| leadLists_delete | Elimine uma lista outbound pelo id. Escrita. |
Motivos de Perda de Leads
Ferramentas
| leadLostReasons_get | Obtenha um motivo de perda de lead pelo id. |
| leadLostReasons_list | Liste os motivos pelos quais um lead pode ser marcado como perdido, por ordem. |
Leads
Ferramentas
| leads_dedupeCheck | Verifica se um prospeto já existe no CRM, usando os mesmos filtros de leads_list (companyName, source, owner, …). Chame isto ANTES de leads_create: um lead duplicado divide o histórico de contacto entre dois registos, e nada a jusante os fundirá por si. |
| leads_get | Obtenha um lead pelo id — empresa, website, origem, estado, responsável e o cliente para o qual foi convertido, se aplicável. |
| leads_list | Lista leads — alvos de prospeção, antes da qualificação. Filtre por status, source, owner, client, companyName, ou intervalos de createdAt/closedAt. Um lead qualificado torna-se um Cliente mais um Negócio em aberto via leads_convert; até lá vive apenas aqui, não em clients_list. |
| leads_create | Cria um lead (alvo de prospeção outbound/inbound; companyName, source, owner, cliente associado, opcionais). Um novo lead tem sempre status=open — o status não é definível aqui, e só muda através de leads_convert, leads_lose e leads_reopen. Escrita. |
| leads_update | Atualiza um lead por id (company, website, source, owner, cliente associado, stage, doNotContact). NÃO status nem lostReason: estes são recusados pela entidade e silenciosamente ignorados por este endpoint, pelo que fechar um lead necessita de leads_lose (com um lostReasonId), e reverter isso necessita de leads_reopen. Mover `stage` avança no funil; não fecha o lead. Escrita. |
| leads_delete | Elimine um lead pelo id (eliminação reversível). Escrita. |
| leads_convert | Converta um lead qualificado num Cliente + um contacto por cada lead-contact + um Negócio aberto. Exige um cliente existente (o cliente do lead ou um clientId no corpo do pedido). Escrita. |
| leads_lose | Fecha um lead como PERDIDO — define status=lost e regista closedAt. REQUER lostReasonId, o `id` de uma entrada de leadLostReasons (corra primeiro leadLostReasons_list; é uma lista de seleção fixa, pelo que texto livre é recusado com 422). Esta é a ÚNICA forma de registar um lead como perdido: leads_update ignora status, e doNotContact significa "nunca mais contactar", o que é uma afirmação diferente e muito mais forte do que "não ganhámos este". NÃO move o stage do lead — LeadStage não tem nenhuma flag terminal, pelo que o lead mantém a sua posição no funil e leads_reopen pode restaurá-la exatamente. Escrita. |
| leads_reopen | Reverte leads_lose — repõe status como open e limpa closedAt e o motivo de perda. O stage não é tocado, pelo que o lead retoma exatamente de onde estava. Recorra a isto quando um lead foi fechado contra o registo errado ou o prospect voltou. Escrita. |
| leads_bulkImport | Importa muitos leads numa ÚNICA chamada, cada um com os seus contactos, associação a listas e atividades de contacto aninhados — o servidor cria o lead e depois enfia o seu id nos filhos, pelo que nunca tem de gerir IRIs intermédios. Idempotente por chaves naturais (companyName / email / (list,lead) / (type,occurredAt,contact)): seguro de executar de novo e de dividir em partes (≤100 leads/chamada). Este é o caminho em massa que uma importação de campanha deve usar em vez de N chamadas a leads_create. Escrita. |
Fases de Leads
Ferramentas
| leadStages_get | Obtenha uma fase de lead pelo id. |
| leadStages_list | Lista, por ordem, as fases pelas quais um lead passa. Os leads têm o seu próprio conjunto de fases — os negócios usam stages_list, que é uma coisa diferente. |
Localizações
Ferramentas
| locations_get | Obtém uma localização por id — o seu name e horário de funcionamento. Apenas leitura. |
| locations_list | Lista as localizações da organização — os locais físicos onde os ativos se encontram, mostrados na interface como Lokalizacja. Requer ROLE_LOCATIONS_MANAGER, que, de forma pouco habitual, condiciona também a LEITURA, além da escrita. Apenas leitura. |
| locations_create | Cria uma localização (name obrigatório; officeOpenHour/officeCloseHour opcionais, em segundos após a meia-noite). Use a morada real em vez de um nome de projeto ou de investimento — é isto que alguém em frente ao ativo precisa, e o nome do projeto já é transportado noutro lugar. Requer ROLE_LOCATIONS_MANAGER. Escrita. |
| locations_update | Renomeia uma localização ou altera o seu horário de funcionamento. Requer ROLE_LOCATIONS_MANAGER. Escrita. |
Moradas da Organização
Ferramentas
| organizationAddresses_get | Obtém um registo de morada de subscrição por id — name, street, city, postCode, country, e os campos fiscais. `street` inclui o número do edifício quando foi introduzido manualmente, mas não quando veio da consulta NIP/GUS. Apenas leitura. |
| organizationAddresses_list | Lista os registos de morada de subscrição da organização — a morada associada à subscrição Flowtly, e a fonte a partir da qual o rodapé de e-mail {{organizationAddress}} é gerado. Normalmente exatamente uma linha. Esta NÃO é a morada de vendedor da fatura, que reside nas chaves de configuração organization-billing-* (configs_get) e é o que as faturas e o KSeF leem; as duas são mantidas separadamente e divergem com regularidade. Leia ambas antes de concluir qual delas o cliente realmente editou. Apenas leitura. |
| organizationAddresses_update | Atualiza o registo de morada de SUBSCRIÇÃO da organização (id obrigatório; envie apenas os campos que está a alterar). ESTE É O REGISTO A PARTIR DO QUAL O RODAPÉ DE E-MAIL É GERADO: o {{organizationAddress}} do rodapé é composto como "street, postCode city" a partir daqui, NÃO das chaves de configuração organization-billing-* que as faturas e o KSeF usam como morada do vendedor. Os dois armazenamentos divergem, e o rodapé ler este é um defeito conhecido — pelo que, quando uma assinatura mostra uma morada que o cliente jura ter corrigido, ele corrigiu as chaves de faturação, e este é o registo que ainda guarda o valor antigo. `street` é uma única coluna de texto livre que também tem de conter o número do edifício: a consulta NIP/GUS preenche apenas o nome da rua e descarta silenciosamente o número do edifício e da fração, razão pela qual as moradas aqui aparecem como "ul. Example" sem número. Escreva a forma completa "ul. Example 8/12" para corrigir. LEIA PRIMEIRO com organizationAddresses_list e compare com configs_get em organization-billing-street antes de escrever, para copiar o valor que o próprio cliente mantém, em vez de inventar um. Requer ROLE_BILLINGS_MANAGER. Escrita. |
Organizações
Ferramentas
| organizations_get | Obtém uma organização por id. AVISO — isto NÃO indica a que organização está ligado. Uma ligação OAuth está fixada exatamente a uma organização (associada ao token), mas este endpoint devolve qualquer organização de que o UTILIZADOR ligado seja membro, pelo que uma leitura bem-sucedida aqui pode parecer confirmação de que está a trabalhar nessa organização, quando pode não estar. Para verificar o inquilino em que está realmente a operar, leia dados delimitados ao inquilino — people_list ou clients_list — e nunca inicie uma escrita em massa apenas com base nesta chamada. |
Pessoas
Ferramentas
| people_get | Obtenha um registo de pessoa/colaborador pelo id — nomes, emails, telefone, gestor, e se está ativo. |
| people_list | Liste as pessoas/colaboradores. Filtre por isActive, reportsTo (o id de um gestor), projectMembers.project, ou search; pagine com cursor. Pessoas e colaboradores partilham o mesmo id, pelo que é assim que resolve o id de colaborador esperado pelas ferramentas de horas de trabalho, responsabilidades, membros de projeto e permissões. |
| people_create | Crie um registo de pessoa/colaborador (firstname + lastname obrigatórios; companyEmail, contactEmail, contactPhone opcionais). Escrita. |
| people_update | Atualize um registo de pessoa/colaborador pelo id (name, companyEmail, contactEmail, contactPhone, etc.). Escrita. |
| people_delete | Elimine um registo de colaborador/pessoa pelo id (por exemplo, para remover um colaborador fictício/placeholder). Exige ROLE_EMPLOYEES_MANAGER; o backend executa um processador de eliminação que também desassocia registos relacionados. Alto impacto, irreversível. Escrita. |
| people_invite | Dá a uma pessoa já existente um LOGIN: cria um convite de organização pendente e envia-o por e-mail, no idioma de interface configurado pela organização. Este é o passo que people_create e people_setPermissionGroups NÃO fazem — uma pessoa com grupos de permissões ainda não consegue iniciar sessão até ser convidada e aceitar. Requer o e-mail da pessoa; falha se já tiver um login. Ordem de onboarding: people_create (registo) -> people_invite (login) -> people_setPermissionGroups (direitos). Escrita. |
| people_setPermissionGroups | Define (substitui) TODO o conjunto de grupos de permissões de uma pessoa por ids numéricos de grupo (ver permissionGroups_list — por exemplo, o grupo "Business Owner" concede ROLE_ADMIN): passe todos os grupos com que deve ficar, e [] remove-os todos. Concede acesso; NÃO cria um login nem envia e-mail à pessoa — isso é people_invite. A ARMADILHA: dar a alguém o seu PRIMEIRO grupo move-a para o modelo computado, onde os roles vêm de grupos e de overrides por pessoa, e um role concedido manualmente fora desse modelo desaparece nessa mesma chamada — um ROLE_ADMIN atribuído manualmente a uma pessoa é exatamente do tipo que isto remove. Também funciona ao contrário: limpar o seu último grupo devolve-a a esse estado e faz reaparecer esses roles mais antigos. As listas overridesAdded/overridesRemoved nada dizem sobre isto; descrevem overrides e mantêm-se vazias enquanto o acesso efetivo muda. Por isso, a resposta reporta a diferença entre os roles que a pessoa tinha antes desta chamada e depois dela, como rolesLost e rolesGained — este é o par a ler assim que a chamada retorna. rolesLost null (não []) significa que o snapshot tirado antes da escrita não pôde ser lido e a diferença é DESCONHECIDA, com o motivo em roleDeltaUnavailable: o grupo foi alterado na mesma, pelo que um null não é um atestado de boa saúde — volte a verificar com people_getPermissions. Para devolver um role que deveria ter sobrevivido, conceda-o com people_setRoleOverrides. Requer ROLE_ROLES_MANAGER. Escrita. |
| people_setRoleOverrides | Define (substitui) os roles que UMA pessoa recebe além — ou dos quais é privada — em relação aos seus grupos de permissões. Recorra primeiro a um grupo (people_setPermissionGroups): os grupos são a abstração pretendida e escalam para mais do que uma pessoa, pelo que um override só deve ser usado quando um indivíduo específico realmente difere de todos os grupos. SUBSTITUI ambas as listas na íntegra, pelo que se deve ler primeiro people_getPermissions e reenviar todos os overrides que devam manter-se; omitir uma lista limpa-a. Os roles são constantes ROLE_ — permissionGroups_list mostra as que esta organização já utiliza. Um role presente tanto em added como em removed é recusado, em vez de ser adivinhado. Devolve o mesmo snapshot resolvido que people_getPermissions, pelo que se pode confirmar o resultado sem uma segunda chamada. NÃO cria um login — ver people_invite. Requer ROLE_ROLES_MANAGER. Escrita. |
| people_getPermissions | O que uma pessoa pode efetivamente fazer, resolvido: os seus grupos de permissões (cada um com os roles que concede), os seus overrides pessoais, e os effectiveRoles em que os dois se combinam. A forma de verificar se uma alteração de acesso surtiu efeito — people_list mostra um campo roles, mas este é o que explica PORQUE detém esses roles e qual a alavanca a acionar para os alterar. Recorra a isto antes de cada chamada a people_setRoleOverrides, porque essa ferramenta substitui as listas de overrides na íntegra, e é aqui que se leem as atuais. staleOverrides são overrides removidos que já não correspondem a nenhum role concedido por grupo, pelo que atualmente não fazem nada. people_list fornece o id. Requer ROLE_ROLES_MANAGER para ver qualquer pessoa além de si próprio. Apenas leitura. |
Grupos de Permissões
Ferramentas
| permissionGroups_get | Obtenha um grupo de permissões pelo id, incluindo as strings ROLE_* que concede. |
| permissionGroups_list | Lista os grupos de permissões da organização e os papéis que cada um concede — por exemplo, o grupo "Business Owner" concede ROLE_ADMIN. Leia isto antes de people_setPermissionGroups: os papéis na resposta são a autoridade sobre o que um grupo realmente permite, pelo que nunca precisa de adivinhar pelo nome. |
| permissionGroups_create | Crie um grupo de permissões (name obrigatório; roles = lista de strings ROLE_* que concede). Escrita. |
| permissionGroups_update | Atualize o nome, a descrição ou os papéis concedidos de um grupo de permissões pelo id. Escrita. |
Pipelines
Ferramentas
| pipelines_get | Obtenha um pipeline de vendas pelo id. |
| pipelines_list | Lista pipelines de vendas. Um pipeline é dono de um conjunto ordenado de fases — leia-as com stages_list filtrado por pipeline. |
Posições
Ferramentas
| positions_list | Lista posições — os papéis nomeados (por exemplo, "Backend Engineer") que uma alocação de projeto preenche. Sem filtros; Position tem a paginação desativada, pelo que isto devolve sempre o catálogo completo de papéis da organização numa única chamada. Cada item é {id, name, roles}. Use-a para resolver o nome da posição por trás do positionId de uma linha de allocations_list, e para encontrar o id de posição com que uma importação de recursos deve corresponder. |
Membros do Projeto
Ferramentas
| projectMembers_get | Obtém uma associação a projeto (project membership) por id — o seu employee, project e position. Os ids vêm de projectMembers_list ou do array projectMembers em projects_get. |
| projectMembers_list | Lista associações a projetos — QUEM PODE VER QUAL PROJETO. Filtre por project (`/projects/{id}`) para ler a lista de membros de um projeto, ou por employee para ler todos os projetos a que uma pessoa tem acesso; cada linha traz o seu próprio id, o employee, o project e a position (employee|tech-lead|account-manager|viewer). Recorra a isto em primeiro lugar quando alguém reportar que um projeto está a faltar na sua lista de Projects ou que não consegue registar tempo nele: uma lista de membros vazia, ou uma que não o inclua, É a explicação — a visibilidade é a associação (membership). É também a fonte de id para projectMembers_update e projectMembers_delete. Note que a mesma pessoa pode aparecer várias vezes no mesmo projeto, uma vez por position. |
| projectMembers_create | Coloca uma pessoa NUM projeto (employee + project IRIs obrigatórios, por exemplo "/people/204" e "/projects/243"; position opcional = employee|tech-lead|account-manager|viewer, por omissão employee). ISTO É O CONTROLO DE ACESSO, não uma etiqueta: uma pessoa que não seja membro não vê o projeto de todo — falta na sua lista de Projects e não pode registar tempo nele — pelo que esta é a ferramenta que restaura alguém excluído de um projeto. A POSITION NÃO É COSMÉTICA: um utilizador com um role de âmbito de projeto só vê os projetos onde a sua position de associação corresponde — ROLE_PROJECTS_LEAD corresponde a tech-lead, ROLE_PROJECTS_VIEWER corresponde a viewer — pelo que dar a um responsável de projeto uma linha `employee` deixa-o tão às cegas como não ter nenhuma linha. A associação NÃO é herdada em cascata: colocar alguém numa pasta-mãe não lhe dá nada nos projetos por baixo dela, pelo que uma árvore de pastas necessita de uma chamada por projeto. A chave única é (employee, project, position), o que significa que as positions se acumulam em vez de se substituírem — uma pessoa pode ter employee E tech-lead no mesmo projeto, como duas linhas separadas, e adicionar tech-lead a alguém que já é employee aí não remove nem eleva a linha employee (use projectMembers_update para alterar uma position no próprio lugar). Leia primeiro as linhas atuais com projectMembers_list?project=/projects/{id}, ou projects_get, cujo array projectMembers contém o id de cada linha. A CARREGAR UMA LISTA COMPLETA DE MEMBROS? Existe uma forma em lote — projectMembers_import reconcilia até 500 associações numa só chamada, ignora as que já estão registadas, pelo que é seguro reexecutá-la, e tem a notificação DESATIVADA por omissão — mas NÃO ESTÁ DISPONÍVEL NESTA LIGAÇÃO: só é servida ao âmbito interno, pelo que não a pode chamar aqui e procurá-la não a encontrará. Chame esta ferramenta em ciclo, ou peça ao seu operador Flowtly que execute o carregamento em lote. NÃO É SILENCIOSO: adicionar uma pessoa que ainda não está no projeto envia-lhe uma notificação de atribuição ao projeto, pelo que um backfill de 17 projetos envia 17 notificações. Requer ROLE_PROJECTS_MANAGER. Escrita. |
| projectMembers_update | Altera a position de uma associação existente, por id (employee|tech-lead|account-manager|viewer) — obtenha o id de projectMembers_list ou do array projectMembers em projects_get. Use isto para promover ou despromover NO PRÓPRIO LUGAR; use projectMembers_create para adicionar uma segunda position, adicional à já detida. Alterar uma position pode REVOGAR a visibilidade do projeto para alguém cujo role seja de âmbito de projeto (um ROLE_PROJECTS_LEAD despromovido de tech-lead para employee deixa de o ver). Não é possível mover uma associação para outra pessoa ou projeto — para isso, elimine e recrie. Requer ROLE_PROJECTS_MANAGER. Escrita. |
| projectMembers_delete | Remove uma pessoa DE um projeto, por id de associação — encontre-o com projectMembers_list ou no array projectMembers de projects_get. Isto REVOGA O ACESSO: assim que a última linha de associação dessa pessoa a esse projeto desaparece, o projeto desaparece da sua vista e deixa de poder registar tempo nele, que é exatamente como um projeto desaparece silenciosamente para alguém. As horas já registadas NÃO são eliminadas e permanecem no projeto; a pessoa simplesmente deixa de as poder ver ou adicionar a elas. Eliminar uma position deixa intacta qualquer outra position que a mesma pessoa detenha no mesmo projeto. Requer ROLE_PROJECTS_MANAGER. Irreversível (recriar cria uma nova linha e volta a notificar), de alto impacto. Escrita. |
Projetos
Ferramentas
| projects_costAllocations | Como os custos foram distribuídos PARA este projeto — quais as transações e linhas de fatura que lhe foram atribuídas, e em que proporção. Use-a para explicar um valor de rentabilidade, em vez de apenas o citar: é aqui que um resultado inesperado é rastreado até ao documento que o causou. Requer ROLE_TRANSACTIONS_MANAGER. Apenas leitura. |
| projects_folderCounts | Quantos projetos estão em cada PASTA de projetos, no formato folderId + total + active. O folderId é um id de tagDefinition — resolva os nomes com tagDefinitions_list e descubra quais grupos são grupos de pastas com tagGroups_list (allowedRelations contém "project"). Um folderId nulo é o balde dos não categorizados. Conta apenas os projetos raiz, pois as pastas agrupam raízes e as fases seguem o seu projeto pai. Somente leitura. |
| projects_get | Obtenha um projeto pelo id — nome, tipo, cliente, datas, descrição e preço. |
| projects_list | Liste os projetos. Filtre por type (fixed-price | time-and-material | non-billable | internal), client.name, employee, name, ou intervalos de dateFrom/dateTo. Use-o para resolver o id de projeto exigido por tarefas, registo de horas de trabalho, orçamentos e contratos. |
| projects_profitability | O RESULTADO POR PROJETO — o que um projeto gerou face ao que custou. Este é o número que um negócio de serviços ou desenvolvimento normalmente procura ver, e aquele que todas as outras ferramentas de projeto alimentam. Passe o id de projeto de projects_list. Requer ROLE_ACCOUNT_MANAGER. Apenas leitura. |
| projects_create | Crie um projeto (name + type obrigatórios; type = fixed-price|time-and-material|non-billable|internal; dateFrom/dateTo, client, publicDescription, notes, priceNet opcionais). Escrita. |
| projects_update | Atualize um projeto pelo id (name, type, dates, description, etc.). Escrita. |
| projects_archive | Arquiva um projeto por id — a forma de retirar um projeto que não pode ser eliminado porque tem tempo registado, faturas ou orçamentos associados. Reversível com projects_unarchive. Preferível a antedatar dateTo, que apenas faz o projeto parecer concluído. Escrita. |
| projects_unarchive | Restaura um projeto arquivado por id, desfazendo projects_archive. Escrita. |
Modelos de Projeto
Ferramentas
| projectTemplates_get | Obtém um modelo de projeto (project template) por id, incluindo o seu documento structure completo. projectTemplates_list encontra o id. Leia isto antes de projectTemplates_update — a structure é escrita na ÍNTEGRA, pelo que uma atualização deve enviar o documento completo, não um fragmento. Apenas leitura. |
| projectTemplates_list | Lista os modelos de projeto (project templates) da organização — plantas reutilizáveis de um projeto, as suas fases, listas de tarefas e tarefas. Recorra a isto ANTES de projects_create quando o mesmo tipo de projeto é configurado repetidamente (um tipo de contrato de serviço, uma auditoria, um onboarding): instanciar um template constrói a árvore inteira numa só chamada, ao passo que projects_create cria um projeto vazio que depois é preciso preencher manualmente. A linha assinalada com isDefault é o template incorporado da organização, aplicado a um projeto criado sem nenhum template escolhido. Apenas leitura. |
| projectTemplates_create | Cria um modelo de projeto reutilizável a partir de um documento structure (version, project, phases, e as suas lists/tasks). Os desvios dentro dele são RELATIVOS — startOffsetDays e durationDays são contados em dias a partir do startDate indicado no momento da instanciação, pelo que um único template serve qualquer início futuro. O project.name na structure é um marcador de posição (placeholder); substitua-o por cliente ao instanciar. A structure é validada no servidor contra o esquema da sua versão declarada, e uma violação identifica o JSON pointer em causa. Escrita. |
| projectTemplates_update | Atualiza um modelo de projeto por id. A coluna structure é guardada e substituída na ÍNTEGRA, nunca combinada — envie o documento completo, ou as partes omitidas desaparecem. Leia primeiro a atual com projectTemplates_get. Alterar um template NÃO afeta os projetos já instanciados a partir dele; não há propagação retroativa. Escrita. |
| projectTemplates_delete | Elimina um modelo de projeto por id. Eliminação suave (soft delete), e NÃO afeta os projetos já criados a partir do template — esses são projetos normais e continuam a existir. Escrita. |
| projectTemplates_instantiate | Constrói um projeto real a partir de um template — o projeto, as suas fases, as suas task lists e todas as tarefas, numa ÚNICA chamada atómica. startDate é obrigatório e é a âncora a partir da qual todos os startOffsetDays do template são resolvidos. Passe name para substituir o nome de projeto marcador de posição do template, e client para associar o novo projeto a um cliente: instanciar duas vezes contra o MESMO cliente é como um cliente acaba por ter vários contratos de serviço, cada um o seu próprio projeto. Devolve o projeto criado. Escrita. |
Candidatos dos Pedidos de Recurso
Ferramentas
| resourceRequestCandidates_get | Um candidato de recrutamento por id. O id vem de resourceRequestCandidates_list. Requer ROLE_HR_MANAGER. Apenas leitura. |
| resourceRequestCandidates_list | Os candidatos apresentados para pedidos de contratação — pessoas num pipeline de recrutamento, não funcionários disponíveis para alocação. Filtre pelo id do pedido de resourceRequests_list. Requer ROLE_HR_MANAGER. Apenas leitura. |
Solicitações de Recurso
Ferramentas
| resourceRequests_get | Um pedido de contratação por id, com a sua posição e estado. Obtenha o id de resourceRequests_list. RH/recrutamento, não alocação de recursos. Requer ROLE_HR_MANAGER. Apenas leitura. |
| resourceRequests_list | Pedidos de contratação em aberto — um pedido para recrutar para uma posição, no domínio de RH. Apesar do nome, isto NÃO é procura de alocação de recursos: é recrutamento. Devolve a coleção; resourceRequests_get lê um, e resourceRequestCandidates_list dá as pessoas apresentadas para ele. Requer ROLE_HR_MANAGER. Apenas leitura. |
Pedidos de Recursos
Ferramentas
| resourcingRequests_list | Pedidos de recursos em aberto — alguém a pedir que uma pessoa seja alocada a um projeto, o que constitui o lado da procura em recursos. Este é o fluxo que a vista de Pedidos da interface de Recursos apresenta. NÃO confunda com resourceRequests_list: esse é RECRUTAMENTO de RH (contratação para uma posição). Combine-o com resourcingRequestsHistory_list para o que já foi decidido, e resourcingBench_get para quem poderia satisfazer um pedido. Requer o módulo de recursos e ROLE_RESOURCING_MANAGER. Apenas leitura. |
Histórico de Pedidos de Recursos
Ferramentas
| resourcingRequestsHistory_list | O que já aconteceu aos pedidos de recursos — o rasto de decisões (confirmado, recusado, alterado) por trás dos pedidos em aberto em resourcingRequests_list. Recorra a isto para responder 'isto já foi pedido e recusado?' antes de propor de novo a mesma alocação. Requer o módulo de recursos e ROLE_RESOURCING_MANAGER. Apenas leitura. |
Responsabilidades
Ferramentas
| responsibilities_get | Obtenha uma responsabilidade pelo id. |
| responsibilities_list | Liste as responsabilidades dentro de um grupo RACI. Filtre por responsibilityGroup. As responsabilidades podem aninhar-se através de parent; as pessoas são atribuídas a elas através de responsibilityEmployees, não diretamente. |
| responsibilities_create | Cria uma responsabilidade dentro de um grupo (responsibilityGroup = id ou IRI do grupo, + name, obrigatórios; description opcional; parent opcional = outro IRI de responsabilidade para aninhamento). Atribua pessoas a ela via responsibilityEmployees_create. Escrita. |
| responsibilities_update | Atualize uma responsabilidade pelo id (name, description, parent, responsibilityGroup = id de grupo ou IRI). Escrita. |
Colaboradores por Responsabilidade
Ferramentas
| responsibilityEmployees_get | Obtenha uma atribuição de responsabilidade pelo id. |
| responsibilityEmployees_list | Liste quem está atribuído a que responsabilidade, e em que percentagem. Filtre por employee para ler toda a carga RACI de uma pessoa em todos os grupos. |
| responsibilityEmployees_create | Atribua um colaborador a uma responsabilidade (responsibility = id de responsabilidade ou IRI, employee = id de colaborador ou IRI, percentage 0-100, todos obrigatórios; targets e description opcionais). Escrita. |
| responsibilityEmployees_update | Atualize uma atribuição de responsabilidade pelo id (percentage, targets, description). Escrita. |
| responsibilityEmployees_delete | Remova a atribuição de um colaborador a uma responsabilidade pelo id. Escrita. |
Grupos de Responsabilidades
Ferramentas
| responsibilityGroups_get | Obtenha um grupo de responsabilidades pelo id. |
| responsibilityGroups_list | Liste os grupos de responsabilidades / áreas RACI — os itens de topo "Odpowiedzialności", cada um com uma pessoa responsável. As responsabilidades individuais ficam abaixo deles. |
| responsibilityGroups_create | Cria um grupo de responsabilidade / área RACI (name obrigatório; description e responsibleEmployee opcionais = a pessoa responsável, indicada como um id de funcionário simples, como 6 (de people_list), ou o IRI /people/6). Este é o item de topo 'Odpowiedzialności'. Adicione responsabilidades individuais sob ele via responsibilities_create. Escrita. |
| responsibilityGroups_update | Atualize um grupo de responsabilidades pelo id (name, description, responsibleEmployee = id de colaborador ou IRI). Escrita. |
Colaboradores do Horário
Ferramentas
| scheduleEmployees_get | Uma atribuição de cronograma a funcionário por id. O id vem de scheduleEmployees_list. Requer ROLE_SCHEDULES_MANAGER. Apenas leitura. |
| scheduleEmployees_list | Que funcionários estão atribuídos a que cronogramas de horário de trabalho. Use-a para ir de um cronograma (schedules_list) até às suas pessoas, ou para encontrar o cronograma que um dado funcionário segue. Requer ROLE_SCHEDULES_MANAGER. Apenas leitura. |
Plano do Horário
Ferramentas
| schedulePlan_list | Os cronogramas em vigor numa ÚNICA data — passe a data no caminho. Recorra a isto para responder 'quem está a trabalhar hoje / nesta data' sem ter de ler todos os cronogramas e resolver os seus intervalos por conta própria. Ao contrário das outras leituras de cronogramas, esta requer apenas ROLE_USER, sendo por isso a que está disponível a um funcionário comum. Apenas leitura. |
Intervalos de Horário
Ferramentas
| scheduleRanges_get | Um intervalo de tempo de cronograma por id. O id vem de scheduleRanges_list. Requer ROLE_SCHEDULES_MANAGER. Apenas leitura. |
| scheduleRanges_list | Os intervalos de tempo que compõem os cronogramas de horário de trabalho — as horas efetivas que um cronograma cobre. Leia primeiro o registo principal com schedules_get; este expande os seus intervalos. Requer ROLE_SCHEDULES_MANAGER. Apenas leitura. |
Escalas
Ferramentas
| schedules_get | Um cronograma de horário de trabalho por id, com os seus intervalos e funcionários atribuídos. O id vem de schedules_list; scheduleRanges_list e scheduleEmployees_list leem as suas partes. Requer ROLE_SCHEDULES_MANAGER. Apenas leitura. |
| schedules_list | Cronogramas de horário de trabalho — os padrões de turnos/trabalho que uma organização define, NÃO alocação de projeto. Use resourcingSchedule_get para saber quem está reservado em quê; use este para os próprios padrões de trabalho. schedules_get lê um por id. Requer ROLE_SCHEDULES_MANAGER. Apenas leitura. |
Fases
Ferramentas
| stages_get | Obtenha uma fase de negócio pelo id. |
| stages_list | Lista fases de negócio, por ordem. Filtre por pipeline. deals_create requer um id de fase daqui, e mover um negócio entre fases é o que dealStageHistories regista. |
Fornecedores
Ferramentas
| suppliers_list | Liste os fornecedores/contratados — servidos a partir de /contractors, pelo que "supplier" e "contractor" são o mesmo registo. Filtre por cyclic para fornecedores recorrentes. Use-o para resolver o fornecedor contra o qual um custo, um contrato ou uma fatura recebida é arquivado. |
| suppliers_create | Crie um novo registo de fornecedor/contratado (name, tinType, costGroup obrigatórios). Escrita. |
| suppliers_update | Atualize os dados de um fornecedor/contratado (nome, número de contribuinte, condições de pagamento, etc.) pelo id. Escrita. |
Definições de Etiquetas
Ferramentas
| tagDefinitions_list | Lista definições de etiquetas — as etiquetas que podem ser associadas a registos, cada uma dentro de um grupo de etiquetas. tags_create utiliza um id de tagDefinition daqui, mais o registo a que se associa. |
| tagDefinitions_create | Cria uma definição de etiqueta (name, level, tagGroup obrigatórios) dentro de um grupo de etiquetas. Quando o allowedRelations do grupo contém "project", cada definição aqui É uma pasta de projetos — esta é a ferramenta que a cria. Escrita. |
Grupos de Etiquetas
Ferramentas
| tagGroups_list | Liste os grupos de etiquetas — os contentores que organizam as definições de etiquetas. |
| tagGroups_create | Cria um grupo de etiquetas (nome obrigatório) para organizar definições de etiquetas relacionadas. É também assim que se cria um contentor de PASTA DE PROJETOS: passe allowedRelations: ["project"] e as definições do grupo tornam-se pastas na lista de projetos. Um grupo com allowedRelations vazio é universal e NÃO é tratado como pasta. Escrita. |
Comentários de Tarefas
Ferramentas
| taskComments_list | Liste os comentários em tarefas de projeto, dos mais antigos para os mais recentes. Filtre por task para ler a discussão de uma tarefa. |
| taskComments_create | Adicione um comentário a uma tarefa de projeto (id da task + content). Escrita. |
Listas de Tarefas
Ferramentas
| taskLists_list | Lista listas de tarefas — as colunas/secções do quadro onde as tarefas são arquivadas. Filtre por projeto. tasks_create utiliza um id de lista daqui. |
Tarefas
Ferramentas
| tasks_get | Obtenha uma tarefa de projeto pelo id — título, projeto, estado, lista, responsáveis, datas e recorrência. |
| tasks_list | Lista tarefas de projeto. Filtre por projeto, lista, status, responsáveis, isTemplate, ou intervalos de startAt/dueAt. As tarefas recorrentes expõem recurrenceParent e recurrenceRule, pelo que uma ocorrência gerada pode ser reconduzida à regra que a produziu. Para decidir se uma tarefa está CONCLUÍDA, compare o seu status com taskStatuses_list (isClosed) em vez de comparar pelo nome do status. |
| tasks_create | Crie uma tarefa de projeto (title + project obrigatórios; status, list, assignees, dueAt, priority opcionais). Escrita. |
| tasks_update | Atualiza uma tarefa de projeto por id — altera status (incluindo marcar como concluída), assignees, dueAt, title, etc., ou MOVE a tarefa para outro projeto passando `project` (reatribuição de parent; a task list é limpa a menos que também se indique um `list` no projeto de destino, porque uma list pertence a um único projeto). Escrita. |
Estados de Tarefas
Ferramentas
| taskStatuses_list | Liste os estados de tarefa de projeto, pela ordem do quadro. isClosed assinala os estados de concluído e isDefault o estado atribuído a uma nova tarefa. Consulte isto antes de interpretar o estado de uma tarefa — os nomes são configuráveis pela organização, pelo que "Done" não é uma string fiável para comparar. |
Grupos Fiscais
Ferramentas
| taxGroups_list | Lista grupos fiscais. Use-a para resolver o id de taxGroup que taxRules_list filtra e que as linhas de fatura transportam. |
| taxGroups_create | Crie um grupo fiscal (name + type obrigatórios). Escrita. |
| taxGroups_update | Atualize o nome ou o tipo de um grupo fiscal pelo id. Escrita. |
Regras Fiscais
Ferramentas
| taxRules_list | Liste as regras fiscais — as taxas e os períodos a que se aplicam. Filtre por taxGroup. |
| taxRules_create | Crie uma regra fiscal. Escrita. |
| taxRules_update | Atualize uma regra fiscal pelo id. Escrita. |
Transações
Ferramentas
| transactions_list | Liste as transações bancárias — o feed bancário contra o qual as faturas recebidas são cruzadas. Filtre por bankAccount, counterpartyRole, cost, ignored, hasDetectedProblems, um intervalo de orderDate/execDate, ou amount.between. Note que orderDate e execDate são diferentes: um pagamento pode ser ordenado num mês e executado no seguinte. |
| transactions_suggestions | Lê as propostas do Flowtly para uma transação bancária — a que contraparte, grupo de custos ou documento deve ser arquivada. A imagem espelhada de incomingInvoices_suggestions, do lado do dinheiro. |
| transactions_importStatement | Importa um ficheiro de extrato bancário (por exemplo, um ficheiro .sta MT940) — passe o conteúdo de texto em bruto de cada ficheiro tal e qual (NÃO em base64) com um filename. NÃO HÁ PARÂMETRO bankAccount: o backend encaminha um ficheiro removendo todos os carateres não numéricos dos números das suas contas bancárias e dos bytes do ficheiro, importando para todas as contas cujos dígitos apareçam em qualquer parte do ficheiro — pelo que um ficheiro pode ser registado em várias contas, e um extrato para uma conta que não esteja configurada no Flowtly (ou cujo número esteja registado de forma diferente da que o banco escreve) não é importado para nenhuma delas, falhando com um erro que explica exatamente porquê — leia essa mensagem, é o único diagnóstico que este endpoint fornece. Em caso de sucesso, a resposta é `{ imported, matching }`: `matching: "in_progress"` significa que a correspondência de fornecedor/anexo para as novas linhas ainda está em execução depois de esta chamada retornar, pelo que um transactions_list imediato pode mostrar linhas ainda não correspondidas — releia um pouco mais tarde para o estado final. Reimportar o mesmo extrato não cria linhas duplicadas; o importador reconhece transações já vistas. Assim que um extrato estiver importado, associe um pagamento existente sem linha bancária a uma das suas linhas com invoiceTransactions_update. Escrita. |
| transactions_delete | Elimina uma transação bancária por id — encontre-a com transactions_list. Recorra a isto APENAS para desfazer um erro contabilístico que não possa ser corrigido de outra forma: um extrato importado para a conta bancária errada, ou linhas introduzidas à mão antes de chegar o extrato real e agora por ele duplicadas. Uma transação é o registo do que o banco fez, por isso eliminar uma numa conta importada faz o razão deixar de bater certo com o banco; o backend só o permite a ROLE_ADMIN (um gestor de transações só pode eliminar em contas de caixa e manuais). ANTES de eliminar um suposto duplicado, prove o par: faça corresponder a linha importada pelo valor E número de fatura E contraparte, não apenas pelo valor — um recebimento que chegou depois da data final do extrato não tem contrapartida, e eliminá-lo destrói o único registo dessa receita. O backend DESLIGA em vez de eliminar o que depende dela: os pagamentos de faturas sobrevivem com a linha bancária limpa (reaponte-os com invoiceTransactions_update), os anexos e os imóveis são desassociados, enquanto as linhas de transação de projeto e de colaborador são removidas com ela. Irreversível, de grande impacto. Escrita. |
Horas de Trabalho
Ferramentas
| workTimes_get | Obtenha uma única entrada de horas de trabalho pelo id — data, minutos, projeto, notas e o colaborador a que pertence. |
| workTimes_list | Liste as entradas de horas de trabalho (horas registadas). Filtre por intervalo de datas (date.after / date.before, YYYY-MM-DD) e, opcionalmente, por employee ou project; pagine com cursor. Cada linha transporta employeeId/employeeName e projectId/projectName, pelo que é assim que exporta todas as horas registadas de um período. IMPORTANTE: resultados ao nível da organização exigem ROLE_WORKING_HOURS_VIEWER. Sem essa permissão, o backend NÃO devolve erro — devolve silenciosamente apenas as entradas do próprio utilizador ligado, pelo que uma exportação de "horas de todos" pode voltar a conter apenas uma pessoa e parecer perfeitamente normal. Se todas as linhas pertencerem a um único colaborador e não tiver filtrado por employee, a resposta transporta um scopeWarning a avisar disso — mostre-o ao utilizador em vez de apresentar o resultado como sendo ao nível da organização. |
| workTimes_log | Regista uma entrada de tempo de trabalho para o utilizador Flowtly ligado (date, durationMinutes, project, notes). A NOTE TEM DE PASSAR A VERIFICAÇÃO DE DESCRIÇÃO CURTA DO SERVIDOR, que uma importação retroativa em lote encontra repetidamente: necessita de PELO MENOS cerca de 32 caracteres (o limite exato é uma definição por organização, e uma organização pode defini-lo como 0 para desligar a verificação), OU uma referência de ticket "#", OU uma ligação http(s) — qualquer uma delas é suficiente. "Flowtly – Scallier" é recusado; "Flowtly – Scallier #FLOW-123" não é. O erro 422 identifica o propertyPath `description`, que é o nome que o servidor dá ao campo que esta ferramenta chama `notes`. Escrita. |
| workTimes_update | Corrige uma entrada de tempo de trabalho registada, por id — a sua date, minutes, project ou description. É assim que uma entrada mal atribuída é MOVIDA entre projetos: workTimes_log só cria, pelo que sem isto um project errado ou um erro de escrita na description são permanentes. Leia primeiro a entrada com workTimes_get. Aplica-se a mesma verificação de descrição curta que em workTimes_log: cerca de 32 caracteres — o limite é uma definição por organização e pode ser 0, o que a desativa — OU uma referência de ticket "#" OU uma ligação http(s), qualquer uma das três. Escrita. |
| workTimes_delete | Elimina uma entrada de tempo de trabalho registada, por id. Para um duplicado ou uma entrada registada contra trabalho que nunca aconteceu — prefira workTimes_update quando a entrada é real mas está errada, para que as horas permaneçam no registo em vez de desaparecerem dele. As horas registadas alimentam as finanças e a utilização do projeto, pelo que uma eliminação altera silenciosamente números reportados de um período passado. Escrita. |
Contactos de Clientes
Ferramentas
| clientContacts_create | Crie uma pessoa de contacto para um cliente (client, type, name, email obrigatórios). Escrita. |
Contas Bancárias de Contrapartes
Ferramentas
| counterpartyBankAccounts_create | Associe uma conta bancária a uma contraparte (counterparty + accountNumber). Escrita. |
Linhas do Plano de Pagamentos
Ferramentas
| paymentScheduleLines_import | Carrega o plano de prestações inteiro de um contrato numa só chamada, em vez de uma ida e volta por linha. Construído para contratos de promotor imobiliário, que são pagos em tranches de construção — uma única venda são seis a doze prestações, e um registo delas são centenas. Cada linha identifica o seu contrato PELO NOME (para um contrato de promotor importado, o seu número de acordo), uma data de vencimento, e um valor em UNIDADES MENORES — grosze, pelo que 5 300,00 é "530000" e "5300" regista silenciosamente 53,00. As linhas são reconciliadas com as linhas já existentes por contract+date+amount+note, pelo que uma linha desconhecida é criada, uma idêntica é ignorada, e reexecutar o mesmo lote não altera nada; PaymentScheduleLine não tem coluna de referência externa, pelo que essa chave natural é a chave de reconciliação. Uma linha cujo nome de contrato não corresponda a nada, ou corresponda a MAIS do que um contrato, é reportada como falhada em vez de associada a um palpite — colocar uma prestação no contrato errado deturpa dois fluxos de caixa ao mesmo tempo. Passe dryRun:true primeiro num carregamento real. Máximo de 1000 linhas. Escrita. |
| paymentScheduleLines_create | Adiciona uma prestação ao plano de pagamentos de um contrato — o plano do que se espera que seja faturado ou pago, e quando. Passe o IRI do contrato, uma data e um valor. É isto que resolve o problema de plano de pagamentos em falta que contracts_get reporta num contrato não cíclico: uma taxa única continua a ter um plano, que é simplesmente uma única linha para o valor total no dia em que vence. Os contratos cíclicos não são verificados quanto a isto, porque o sistema não gera automaticamente linhas a partir de uma cadência. O VALOR ESTÁ EM UNIDADES MENORES — grosze, não złote: 5 300,00 é "530000", e "5300" regista silenciosamente uma linha de 53,00. A API devolve-os da mesma forma, pelo que se deve reler um com contracts_paymentScheduleLines em caso de dúvida sobre a escala. Releia o resultado com contracts_paymentScheduleLines. Escrita. |
| paymentScheduleLines_update | Altera uma linha do plano de pagamentos por id — a sua date, amount ou note. Use-a quando uma prestação atrasa ou é renegociada, em vez de eliminar e recriar, para que a linha mantenha qualquer fatura já associada a ela. O VALOR ESTÁ EM UNIDADES MENORES — grosze, não złote: 5 300,00 é "530000", e "5300" regista silenciosamente uma linha de 53,00. A API devolve-os da mesma forma, pelo que se deve reler um com contracts_paymentScheduleLines em caso de dúvida sobre a escala. Escrita. |
| paymentScheduleLines_delete | Remove uma linha do plano de pagamentos por id. Elimina o PLANO, não o dinheiro: uma fatura ou transação já associada à linha não é afetada, mas deixa de estar reconciliada com nada. Prefira paymentScheduleLines_update para uma prestação que mudou. Escrita. |
Logótipo da Organização
Ferramentas
| organizationLogo_upload | Carrega/substitui o logótipo da organização (imagem base64 + contentType + filename). Leia o atual via configs_get organization-logo-url. Escrita. |
Ícone da Organização
Ferramentas
| organizationIcon_upload | Carrega/substitui o ícone/favicon da organização (imagem base64 + contentType + filename). Leia o atual via configs_get organization-icon-url. Escrita. |
Armazenamento
Ferramentas
| storage_upload | Anexa um ficheiro a qualquer registo que o armazenamento genérico da Flowtly aceite — um ATIVO (relationName "property"), um projeto, uma tarefa, um cliente, uma localização, um contratante, uma fatura. Esta é a única via para uma IMAGEM de ativo: fazer upload com relationName "property" define a imagem que a aplicação mostra para esse ativo (servida como `file` no payload do ativo). Property não tem coluna de imagem -- a imagem é derivada desta tabela no momento da leitura, razão pela qual nada na entidade sugere que existe. É UMA única posição, e o upload mais recente prevalece, pelo que uma segunda imagem substitui a primeira em vez de se adicionar a uma galeria. O mesmo se aplica a location, invoices e transaction-attachments; clients, agreements e candidates, pelo contrário, acumulam todos os uploads em `files`. TODAS AS OUTRAS RELAÇÕES NÃO LIGAM O UPLOAD A NADA VISÍVEL, e relationName "employees" é aquela com que se deve ter cuidado: guarda os bytes e NÃO cria nenhum Document, pelo que People > Documents fica vazio e o payload do funcionário não traz nenhum ficheiro. A rota /documents de qualquer registo devolve entidades Document, e um upload não cria nenhuma — foi assim que PDFs assinados de NDA e de ESOP chegaram a ser reportados como arquivados enquanto o separador Documents não mostrava nada (#255). Um verdadeiro documento de funcionário requer POST /documents com um DocumentType cujo relationName seja `employee`, o id do funcionário e o IRI da linha Storage que esta chamada devolve. NÃO MONTE ISSO À MÃO: use employeeDocuments_createUploadTicket, que faz os três passos — guarda os bytes, cria o Document e relê-o através de /people/{id}/documents — e reporta stored / linked / verified separadamente. Esta ferramenta fica-se pelos bytes. Também não recorra a agreementTypes.*: um AgreementType é o tipo de um CONTRATO de trabalho (Umowa o pracę, Umowa zlecenie) em Ludzie > Umowy, e não é um DocumentType. Reporte bytes guardados, registo de negócio ligado e visibilidade verificada como três afirmações separadas, e afirme apenas as que efetivamente fez. `file` é omitido das respostas de LIST, a menos que o pedido passe ?include=file, pelo que se deve reler um registo para confirmar que a imagem chegou. Passe relationName + relationId (o id da ferramenta de listagem desse registo; um IRI /assets/7 é aceite e reduzido), mais os bytes em base64 com um contentType e filename. LIMITE DE TAMANHO: os bytes viajam como base64 dentro desta chamada, pelo que deve mantê-los abaixo de cerca de 150 KB — as fotografias ultrapassam quase sempre esse valor, e para essas use storage_createUploadTicket, que não tem limite. As permissões são as que a edição do registo PROPRIETÁRIO exigir: o backend resolve relationName para essa entidade e consulta o voter dela, pelo que arquivar contra um ativo requer a permissão de ativos, e contra um cliente a de clientes. Para um contrato, prefira antes contractAttachments_create — também resolve contracts.problem_missing_document, o que esta não faz. Escrita. |
| storage_createUploadTicket | Gera um ticket de curta duração e uso único para anexar um ficheiro GRANDE a qualquer registo — a forma como as IMAGENS de ativos realmente entram, já que uma imagem está sempre acima do limite de base64. Em property/location/invoices/transaction-attachments, o upload mais recente torna-se a imagem visível do registo, substituindo a anterior; em clients/agreements/candidates, os uploads acumulam-se. Use isto em vez de storage_upload sempre que o ficheiro tenha mais do que algumas dezenas de KB: essa ferramenta transporta os bytes como base64, que quem chama a API tem de emitir como texto, e um JPEG de 400 KB torna-se cerca de 533 mil caracteres base64, muito além do que cabe numa resposta. Passe relationName + relationId mais um filename; recebe de volta um uploadUrl e um curl pronto a executar. Depois envie os BYTES BRUTOS do ficheiro para esse URL (curl --data-binary @photo.jpg) — não base64, não multipart — e a resposta traz o registo Storage criado. O ticket expira em 15 minutos, funciona uma vez, e só pode arquivar contra o único registo que nomeia. Escrita. |
Anexos do Contrato
Ferramentas
| contractAttachments_create | Anexa um documento a um contrato — normalmente o PDF assinado, ou um anexo (DPA, SLA, anexo de preço) arquivado junto dele. Passe os bytes como base64 com um fileName e o id de contrato de contracts_list; `contractId` aqui é um id SIMPLES, ao contrário dos IRIs que contracts_update espera para counterparty e project, embora um IRI completo /contracts/<id> seja aceite e reduzido. LIMITE DE TAMANHO: os bytes viajam como base64 dentro desta chamada, pelo que o documento inteiro tem de caber numa única resposta do modelo — mantenha-o abaixo de cerca de 150 KB, e para qualquer coisa maior use antes contractAttachments_createUploadTicket, que foi construído exatamente para isto e não tem esse limite. Um contrato assinado com um cartão de assinatura normalmente ultrapassa bastante esse valor (673 617 bytes tornam-se 898 156 caracteres base64, várias vezes o que uma resposta pode transportar), e não vem nenhum erro quando não cabe, porque a chamada não pode sequer ser emitida — o pedido nunca chega ao servidor, pelo que se deve verificar o tamanho do ficheiro ANTES de começar, em vez de o descobrir por falha. É isto que resolve o problema de documento em falta que contracts_get reporta, pelo que um contrato mantido via API deixa de estar na fila de "a precisar de arrumação" da aplicação. Um único documento assinado pode suportar várias linhas de contrato (um negócio com uma parte recorrente e outra pontual são duas linhas, porque `cyclic` é por registo) — chame isto uma vez por id de contrato com os mesmos bytes. O que acontece a seguir depende de kind. kind "contract": `status` volta como "analyzing" e o backend lê o documento de forma assíncrona, normalmente em poucos minutos; consulte contracts_get até o anexo estar "analyzed" ou "failed" (uma falha traz failureReason e failureRetryable). A leitura apenas PREENCHE campos VAZIOS do contrato e nunca substitui um nome, direção, montante, datas, moeda, condições de pagamento, linhas de calendário ou preços já presentes; todos os valores extraídos ficam no analysisSummary do anexo, e analysisSummary.notApplied lista o que deixou como sugestão. kind "annex": guardado e NÃO analisado; `status` é "stored", que é final, e o contrato não muda. Trate analysisSummary como uma SUGESTÃO a verificar, e não como um facto em que confiar. Escrita. |
| contractAttachments_createUploadTicket | Gera um ticket de curta duração e uso único para anexar um documento GRANDE a um contrato — o PDF assinado, ou um anexo. Use isto em vez de contractAttachments_create sempre que o ficheiro tenha mais do que algumas dezenas de KB: essa ferramenta transporta os bytes como base64, que quem chama a API tem de emitir como texto, e um contrato assinado real (~700 KB, ~900 mil caracteres base64) está muito além do que cabe numa resposta. Passe o id de contrato de contracts_list mais um fileName; recebe de volta um uploadUrl e um curl pronto a executar. Depois envie os BYTES BRUTOS do ficheiro para esse URL (curl --data-binary @file.pdf) — não base64, não multipart — e a resposta é o anexo criado. O ticket expira em 15 minutos, funciona uma vez, e só pode anexar ao único contrato que nomeia. É isto que resolve o problema de documento em falta que contracts_get reporta. Escrita. |
Transações da Fatura
Ferramentas
| invoiceTransactions_create | Regista um pagamento contra uma fatura emitida (de venda). `invoice` é um IRI de fatura de invoices_list; `date` é a data em que o pagamento é considerado efetuado. `transaction` é opcional — omita-o para registar liquidação sem linha bancária, o que é o que se pretende para faturas históricas cujo extrato bancário nunca foi importado. `amount` é opcional e assume por defeito o valor em dívida da fatura. Registar um pagamento é o que impede uma fatura emitida e vencida de ser tratada como não paga, sendo também o que impede que lembretes de pagamento sejam colocados na fila para ela. Nada impede o registo de dois pagamentos contra uma fatura, por isso leia primeiro invoices_get se não tiver a certeza de que já está liquidada. Escrita. |
| invoiceTransactions_update | Atualiza um registo de pagamento de fatura existente por id (de invoiceTransactions em invoices_get, ou paginando invoiceTransactions). O uso mais comum: associar um pagamento registado sem linha bancária a uma transação que acabou de importar via transactions_importStatement, definindo `transaction` para um IRI/id de transação de transactions_list. A ARMADILHA: isto é um PATCH, mas o backend continua a exigir `invoice` e `date` em cada chamada — NÃO junta os valores existentes por si. Leia primeiro o registo (ou já os tenha da chamada de criação) e reenvie o seu `invoice` e `date` inalterados juntamente com o que pretende realmente alterar, ou a atualização é recusada. `transaction` aceita null para desassociar um pagamento de uma linha bancária. `amount` é opcional. Escrita. |
| invoiceTransactions_delete | Elimina um registo de pagamento de uma fatura por id — os ids são lidos em invoiceTransactions de invoices_get. Isto remove O REGISTO DE QUE UMA FATURA FOI PAGA, não uma transação bancária: use quando uma fatura carrega um pagamento que nunca deveria ter existido, sendo o caso habitual o mesmo pagamento lançado duas vezes — uma à mão e outra pela importação do extrato que depois o conciliou. Consulte primeiro invoices_get e elimine o registo cuja `transaction` é a errada (mantenha o que aponta para a linha bancária importada real); eliminar o último pagamento restante deixa a fatura novamente por pagar, o que volta a ativar os seus lembretes de pagamento. Requer ROLE_INVOICES_MANAGER. Irreversível, de grande impacto. Escrita. |
Gestão de Recursos
Ferramentas
| resourcing_importTimeline | Importa uma folha de cronograma de alocação de recursos (obtenha-a via o MCP do Drive, passe o seu CSV tal e qual). Este é um espelho de SUBSTITUIÇÃO TOTAL das linhas de Alocação da organização para `year`: as linhas na folha são criadas/atualizadas, e qualquer linha existente para esse ano ausente da folha é ELIMINADA — não é uma fusão. SIMULAÇÃO POR DEFEITO: um dryRun omitido pré-visualiza e não escreve nada; passe dryRun:false para aplicar. O relatório dá `created` / `replaced` mais `unmatchedPeople` / `unmatchedProjects`. DUAS COISAS FÁCEIS DE PASSAR DESPERCEBIDAS: uma linha da folha cujo projeto não é resolvido é IGNORADA enquanto a chamada continua a reportar sucesso, pelo que um resultado positivo pode esconder uma importação parcial; e um código de papel que o catálogo de posições ainda não tenha é CRIADO como uma nova posição em vez de ser recusado — ver `createdPositions`. Ambos são assinalados em `warnings` quando ocorrem; transmita isso ao utilizador em vez de reportar apenas `created`. Uma folha que resulte em zero linhas é recusada (parece exatamente uma leitura incorreta prestes a apagar todo o cronograma) a menos que passe force:true. Leia allocations_list depois para ver o que ficou registado. Alto impacto. Escrita. |
Organização
Ferramentas
| organization_whoami | Devolve a organização a que esta ligação MCP está associada — { orgId, name, slug, userId }. Chame-a para confirmar A QUE inquilino está prestes a escrever antes de qualquer create/update: a ligação está fixada exatamente a uma organização pelo token, e escrever prospetos/registos na organização errada é um incidente real. Apenas leitura. |
Valores Reais de Recursos
Ferramentas
| resourcingActuals_get | Horas reportadas vs. o plano, por pessoa por semana, ao longo de uma janela from/to — a pergunta 'a equipa está realmente conforme o plano?', à qual NENHUMA outra ferramenta de recursos responde: as alocações dizem o que foi PLANEADO, esta diz o que foi ENTREGUE. Devolve colunas de semana mais uma linha por pessoa (% planeada, % reportada, variação, totais e uma repartição por projeto). reportedPercent nulo significa 'sem contrato nessa semana' e 0 significa 'existia um contrato e nada foi reportado' — NÃO junte os dois. Passe financials para receita/custo/margem, que são omitidos caso contrário. Requer o módulo de recursos e ROLE_RESOURCING_MANAGER. Apenas leitura. |
Banco de Recursos
Ferramentas
| resourcingBench_get | Quem NÃO está alocado numa janela from/to — o banco de recursos. Recorra a isto quando perguntarem quem colocar num novo projeto ou onde a capacidade está a ser desperdiçada; resourcingActuals_get diz quão carregadas as pessoas estão, este diz quem não tem carga nenhuma. NÃO SABE NADA SOBRE AUSÊNCIAS: freePercent é 100 menos as alocações confirmadas, nada mais, pelo que alguém em três semanas de férias aprovadas aparece como 100% livre, sem nenhum campo na resposta a indicar o contrário. Responder a 'quem está disponível' apenas com isto vai colocar pessoas em projetos enquanto estão ausentes — cruze com holidays_active ou holidays_list. Requer o módulo de recursos. Apenas leitura. |
Cronograma de Recursos
Ferramentas
| resourcingSchedule_get | O cronograma de recursos planeado ao longo de uma janela from/to — a linha temporal de alocação tal como o planeador a mostra. Use-a para o que está RESERVADO para o futuro; use resourcingActuals_get para o que foi efetivamente reportado contra ela. Requer o módulo de recursos e ROLE_RESOURCING_MANAGER. Apenas leitura. |