Guias

Faturas

O agente pode ler uma fatura emitida a partir de uma conta Fakturoid ou ABRA Flexi ligada e usá-la como base para uma chamada de lembrete - nunca emite uma fatura nem a marca como paga.

O que pode e o que não pode fazer

• Pesquisar faturas emitidas por número ou nome da empresa (list_invoices).
• Ler o estado mais recente de uma fatura diretamente junto do fornecedor (get_invoice).
• Criar uma Tarefa de lembrete (taskType: "invoice") que faz referência à fatura.

Não pode

• Não emite, edita nem elimina nenhuma fatura.
• Não marca uma fatura como paga - só o próprio Fakturoid ou ABRA o podem fazer.
• Não liga o Fakturoid com credenciais - apenas através do fluxo OAuth no navegador.

Ligar uma conta

Ambos os serviços de faturação são geridos no mesmo local que os calendários, na secção Dados e integrações do portal (/propojeni). list_integrations e GET /v1/integrations são apenas de leitura: devolvem o estado da ligação e, opcionalmente, um connectUrl, mas não ligam nada por si. O fluxo completo para o agente (list_integrations -> connectUrl -> um passo no navegador) está na página Ligações.

Fakturoid

Liga-se apenas através de OAuth no navegador - POST /v1/integrations com provider: "fakturoid" é rejeitado pela REST com integration_unsupported; não é possível enviar credenciais desta forma. Quando a conta tem mais do que uma empresa com faturação ativa, o navegador é redirecionado, após o início de sessão, para a própria página Dados e integrações da volai (/propojeni) e é aí que aparece a seleção da empresa - a entrada em integrations só é criada depois dessa escolha. ready para fakturoid em GET /v1/integrations indica apenas que a volai tem configuradas as credenciais OAuth do Fakturoid (FAKTUROID_CLIENT_ID e restantes) - NÃO que uma conta concreta está efetivamente ligada. Saber se a ligação está concluída vê-se pela presença de uma entrada na matriz integrations.

ABRA Flexi

Liga-se com credenciais, tal como o Apple Calendar: POST /v1/integrations com {provider: "abra-flexi", baseUrl, company, username, password}. O endereço do servidor (baseUrl) tem de corresponder a um anfitrião previamente autorizado pelo operador (ABRA_FLEXI_ALLOWED_HOSTS) - qualquer outro é rejeitado.

Ler faturas

Um fluxo em dois passos: primeiro pesquisar e depois ler de novo a fatura que interessa.

• list_invoices({integrationId, search?}) - search (até 100 carateres) é uma pesquisa feita no fornecedor por número de fatura ou nome da empresa; devolve as primeiras 40 linhas do Fakturoid ou 50 do ABRA, sem paginação. Restrinja search quando houver demasiados resultados.
• get_invoice({integrationId, invoiceId}) - invoiceId é o externalId copiado de list_invoices. Devolve o estado mais recente diretamente do fornecedor, e não o que a volai tem guardado.

Equivalentes REST: GET /v1/integrations/{id}/invoices?search=... e GET /v1/integrations/{id}/invoices/{invoiceId}.

status é paid, unpaid, overdue ou unknown; amountDueMinor é um inteiro na subunidade da PRÓPRIA MOEDA DA FATURA (não necessariamente CZK), e null significa que o saldo não está verificado. O detalhe inclui também provider, fetchedAt e evidence: "provider_response".

Lembretes através de Tarefas

As chamadas de lembrete em massa por faturas em dívida são feitas através de Tarefas.

Uma tarefa com taskType: "invoice" é criada com source: "integration", e cada destinatário (ou a tarefa inteira, quando todos os destinatários partilham a mesma fatura) leva externalRefs.invoice = {connectionId, externalId, provider?} - connectionId é o identificador da ligação obtido de list_integrations e externalId o identificador da fatura obtido de list_invoices. Sem essa referência, create_task/POST /v1/tasks falha com um erro validation cuja mensagem menciona recipients.externalRefs, e nenhuma tarefa é guardada. Se a um registo existente faltasse a referência obrigatória, get_task/GET /v1/tasks/{id} listá-lo-ia em issues e start_task rejeitaria a tarefa com o mesmo erro de validação.

Cada destinatário tem também um campo paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - gerido pelo sistema e só de leitura, derivado da leitura mais recente da fatura junto do fornecedor, feita mesmo antes da marcação. É not_applicable sem referência a uma fatura, unknown logo após a criação ou quando o estado ou o montante não podem ser verificados e, nos restantes casos, acompanha a resposta do Fakturoid/ABRA - uma fatura paga faz com que a tarefa salte esse item (skipped) e defina paid. O próprio sistema nunca define disputed atualmente - apenas o portal o pode apresentar - e faz parte da enumeração pública (TaskItem em /openapi.json) para uma futura marcação manual de litígio.

Erros

• integration_not_found - Não existe nenhuma ligação com este integrationId ou esta não pertence a esta conta.
• integration_unsupported - A ligação não é de faturação (um calendário, por exemplo) ou trata-se de uma tentativa de ligar o Fakturoid com credenciais em vez de OAuth.
• integration_unauthorized - O Fakturoid ou o ABRA revogaram o acesso - volte a ligar no portal.
• integration_provider_error - O fornecedor não está a responder neste momento ou devolveu um erro - tente mais tarde e considere entretanto o estado da fatura desconhecido.
• integration_invalid_query - O ABRA rejeitou search por conter barras invertidas ou aspas misturadas - simplifique a consulta.

A tabela completa com todos os códigos está na secção de faturas da referência da API REST e em erros MCP.

Segurança

A API REST e o MCP nunca devolvem tokens de acesso nem palavras-passe do Fakturoid ou do ABRA Flexi, e nós guardamo-los cifrados. Desligar uma integração só é possível no portal ou através da REST (DELETE /v1/integrations/{id}) - o MCP não tem para isso qualquer ferramenta, de propósito, por ser irreversível.