Claude para contabilistas: consultar faturas no TOConline

Um contabilista pode usar o Claude para consultar contas, documentos de venda, clientes e links de PDF do TOConline através de um servidor MCP só de leitura. O acesso exige autorização OAuth, fica limitado às empresas escolhidas e pode ser alterado ou revogado no dashboard. O assistente não recebe credenciais da API do TOConline nem executa ações fiscais.

Como funciona o Claude para contabilistas com TOConline MCP?

O Model Context Protocol, ou MCP, permite que o Claude peça dados a uma ferramenta externa durante uma conversa. Neste caso, o cliente MCP fala com uma ponte alojada, a ponte valida a autorização e consulta a API do TOConline para a conta indicada. A resposta regressa à conversa em formato estruturado.

Isto não equivale a entregar o acesso total do TOConline ao assistente. Cada consulta aos dados de uma empresa inclui um identificador explícito de conta e o servidor confirma se essa conta pertence ao conjunto autorizado. Por exemplo, um gabinete pode permitir a consulta da empresa Alfa sem partilhar a empresa Beta com a mesma ligação ao Claude.

A página de TOConline MCP apresenta o endpoint e o processo de ligação. O objetivo desta integração é responder a perguntas operacionais sobre informação existente, não substituir o programa de faturação nem a validação profissional do contabilista.

O centro de integrações MCP reúne as ligações disponíveis. Os gabinetes que usam outro fornecedor também podem consultar a página de InvoiceXpress MCP.

Que dados do TOConline podem ser consultados?

O conjunto atual contém oito ferramentas. Todas estão marcadas como só de leitura. Três identificam as contas disponíveis e o respetivo estado; as outras cinco consultam documentos de venda, clientes e links de PDF.

A listagem de documentos aceita paginação e filtros de tipo FT ou FR e de estado. O detalhe pode incluir totais, IVA, vencimento, moeda e dados de cliente quando o TOConline os devolve. Por exemplo, pode listar-se a primeira página de FT e depois abrir um documento concreto pelo seu ID.

Que perguntas práticas pode um contabilista fazer?

Os exemplos seguintes são modelos de perguntas, não respostas simuladas. Os nomes, números e valores apresentados pelo Claude dependerão sempre das contas autorizadas e dos dados reais devolvidos pelo TOConline.

Uma pergunta fica mais verificável quando inclui a empresa, o tipo de documento, a página ou o ID pretendido. “Mostra o documento 8472 da conta Alfa” delimita melhor o pedido do que “encontra aquela fatura do mês passado”. O resultado deve conservar o ID usado, para que a equipa consiga conferir o documento no sistema de origem.

Como ligar o TOConline ao Claude?

1. Criar ou selecionar o espaço de trabalho no dashboard e adicionar a ligação TOConline da empresa. Os dados API são obtidos no TOConline em Empresa, Configurações, Dados API.

2. Testar e guardar a ligação. A autenticação da API do TOConline usa o identificador, o segredo, o endereço OAuth e o endereço base da API; estes dados não devem ser colados numa conversa.

3. No assistente de configuração do perfil TOConline, avançar para a ligação do assistente de IA e copiar o URL do servidor MCP indicado na interface.

4. No Claude, seguir o fluxo correspondente ao plano. Num plano individual, adicionar o URL como conector personalizado. Em Team ou Enterprise, um Owner ou Primary Owner adiciona primeiro o conector, após o que cada membro estabelece a respetiva ligação. O início de sessão abre no navegador.

5. Escolher o espaço de trabalho e apenas as ligações contabilísticas necessárias. Depois de autorizar, começar por pedir a lista de contas e confirmar os IDs antes de consultar documentos.

Por exemplo, um gabinete com dez empresas pode começar por conceder ao conector acesso a uma única empresa de teste. A autorização pode ser alargada depois, sem entregar ao Claude o identificador, o segredo ou os tokens usados pela API do TOConline.

Que diferença existe entre o OAuth do TOConline e o acesso do Claude?

Existem duas ligações distintas. A primeira autentica o serviço junto da API comercial do TOConline. A documentação oficial descreve um código de autorização, um token de acesso e a respetiva renovação. Estes elementos ficam no lado do servidor que comunica com o fornecedor.

A segunda ligação autoriza o cliente MCP. Durante esse OAuth, a pessoa inicia sessão no dashboard, escolhe um espaço de trabalho e seleciona as contas que o assistente pode ler. Essa seleção torna-se um grant. Uma empresa adicionada mais tarde não entra automaticamente no grant já existente.

Um administrador pode abrir Assistentes de IA, editar a seleção ou revogar o acesso. A edição aplica a nova lista às chamadas seguintes. A revogação invalida a autorização do assistente, incluindo os tokens de acesso e renovação associados. Por exemplo, ao terminar uma avença, remove-se primeiro a empresa do grant ou revoga-se todo o conector.

O acesso é realmente só de leitura?

Sim, para o perfil TOConline MCP descrito aqui. A API oficial do TOConline suporta mais operações, mas este servidor publica apenas o subconjunto de consulta listado acima. Uma capacidade existente no fornecedor não fica automaticamente disponível ao Claude.

• Não cria documentos de venda.
• Não edita, finaliza ou anula documentos.
• Não envia documentos por correio eletrónico.
• Não cria pré-visualizações fiscais.
• Não adiciona, altera, revoga ou revela credenciais TOConline.

“Descarregar PDF” também não altera o documento: a ferramenta pede ao fornecedor um link de impressão e devolve esse endereço. A documentação oficial indica que o PDF está disponível para documentos finalizados. Se o documento ainda não cumprir essa condição, deve esperar-se um erro, não uma finalização automática.

Que limites devem ser considerados antes de confiar numa resposta?

O estado apresentado por provider_account_status é o estado guardado da ligação. A operação não executa um teste novo, não atualiza tokens e não corrige credenciais. Quando surgir “requer nova autenticação” ou outra indicação de atenção, a correção pertence ao dashboard, não à conversa.

As listas são paginadas. A pesquisa de clientes percorre páginas e pode devolver um aviso quando atinge o limite de pesquisa antes de concluir. Esse aviso não deve ser transformado em “não existe”. Por exemplo, uma pesquisa sem correspondências num conjunto truncado pede uma consulta mais específica ou confirmação direta no TOConline.

O MCP também não certifica que um documento está contabilisticamente correto, que uma taxa de IVA foi bem escolhida ou que o período está fechado. Mostra dados do fornecedor para apoiar o trabalho. Uma conclusão fiscal continua a exigir o documento, o contexto da operação e os controlos profissionais aplicáveis.

Como proteger dados de clientes durante a consulta?

Só de leitura não significa ausência de dados pessoais. Uma pesquisa de clientes pode devolver nome, NIF, correio eletrónico, morada, localidade, código postal ou telefone quando esses campos existem no TOConline. Deve conceder-se apenas a empresa necessária e evitar perguntas que tragam dados sem utilidade para a tarefa.

As ferramentas de conta devolvem resumos, não o segredo, o token de acesso ou o token de renovação. Cada ferramenta de negócio exige ainda o identificador da conta. Por exemplo, conhecer um ID de documento não concede acesso se o grant não incluir a conta à qual esse documento pertence.

Convém verificar o destinatário antes de copiar uma resposta para uma mensagem ou relatório. Se o pedido for apenas “o PDF está disponível?”, não é necessário reproduzir a ficha completa do cliente. A minimização deve acontecer tanto na autorização como na pergunta e no uso posterior da resposta.

Que fluxos contabilísticos fazem sentido com este MCP?

O primeiro fluxo é a triagem de ligações. Lista-se o conjunto autorizado, consulta-se o estado de cada conta e encaminham-se para o dashboard as ligações que precisam de atenção. Isto evita começar uma pesquisa de documentos numa conta indisponível.

O segundo é a localização de documentos. Pode listar-se uma página de FT ou FR, abrir os IDs relevantes e obter o link de PDF de um documento finalizado. É útil, por exemplo, quando um cliente pede uma segunda via e já se conhece a empresa e o período aproximado, mas a paginação deve ser continuada até abranger o conjunto necessário.

O terceiro é a confirmação de cadastro. Pesquisa-se por nome, NIF ou outro termo disponível, abre-se o cliente correto por ID e confere-se a ficha devolvida. A alteração continua a ser feita no TOConline. Para escolher entre fornecedores e perceber diferenças de integração, veja a comparação entre TOConline e InvoiceXpress.

Quando deve o pagamento ficar separado da consulta contabilística?

O MCP consulta o que já existe no TOConline. Não transforma uma cobrança num documento fiscal, não decide o tipo FT ou FR e não reconcilia por si só o pagamento com a fatura. Um resultado de pagamento e um documento de venda são registos diferentes, mesmo quando partilham uma referência.

Quando se pretende automatizar a emissão depois de um pagamento Stripe, é necessário um fluxo próprio com regras, validação e tratamento de falhas. Esse processo está descrito no guia sobre como automatizar a faturação Stripe em Portugal. O MCP permanece como interface de consulta para perguntas concretas, com acesso limitado e revogável.