InvoiceXpress MCP e Claude: cinco coisas que a documentação não diz

Atualizado: 24 de agosto de 2026

O InvoiceXpress lançou um servidor MCP. Em português simples: dá para ligar o Claude diretamente à conta de faturação e pedir-lhe coisas por escrito, sem abrir formulários.

A página do produto diz que a configuração demora menos de um minuto. Demorou mais, por uma razão que não está documentada em lado nenhum. E depois de ligado, meia dúzia de chamadas revelaram comportamentos que também não estão.

Isto não é uma review. É o registo do que partiu, com as mensagens de erro literais.

1. O erro de configuração: Unknown client_id

O endereço a colar nos conectores personalizados do Claude é este, e só este:

https://mcp.invoicexpress.com/mcp

Se, como eu, tiver o nome da conta à mão e vir um campo chamado OAuth Client ID nas definições avançadas, a tentação é preenchê-lo. Não preencha. O resultado é um ecrã branco com isto:

{"error":"invalid_client","error_description":"Unknown client_id"}

E, no endereço do browser, um pedido a oauth/authorize?...&client_id=NOME_DA_CONTA.

A razão é que o servidor do InvoiceXpress suporta registo dinâmico de cliente. Os metadados públicos dizem-no:

{
  "registration_endpoint": "https://api-v3.app.invoicexpress.com/oauth/register",
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["mcp"]
}

O Claude está preparado para chamar sozinho o /oauth/register, receber um client_id gerado e usá-lo. Ao preencher o campo à mão, esse passo é saltado e é enviado um identificador que o InvoiceXpress nunca emitiu — daí o invalid_client.

Solução: apagar o conector (não editar — apagar), voltar a criá-lo apenas com o endereço, e deixar as definições avançadas completamente vazias. Não é preciso registar nenhuma aplicação de programador, nem existe client secret para obter: o "none" acima significa que é um cliente público com PKCE.

2. A pergunta que a documentação não responde: um rascunho é perigoso?

Esta era a minha maior dúvida antes de tocar em fosse o que fosse. Em Portugal, um documento emitido por software certificado leva ATCUD, leva QR Code, é comunicado à AT e não se apaga. A ajuda do próprio InvoiceXpress é clara: «Apenas é possível apagar documentos em estado Rascunho». Tudo o resto exige anulação ou nota de crédito, e fica no registo para sempre.

A documentação do MCP não diz se existe ambiente de testes. A conta diz.

"trial": true,
"at_configured": false,
"at_communication_type": null

E a única série existente numa conta nova:

"serie_name": "INVOICEXPRESSDEMO",
"register_status": "",
"is_default": true

Uma série com register_status vazio não está registada na AT. Sem registo não há código de validação, e sem código de validação não há ATCUD válido. Com at_configured: false por cima, nada do que se cria nesse estado chega às Finanças.

Criei uma fatura para confirmar. A resposta:

"status": "draft",
"sequence_number": "rascunho",
"atcud": "N/A"

O sequence_number é literalmente a palavra rascunho: não é consumido nenhum número da série. E o endpoint do QR Code recusa-se a colaborar:

422: O código QR não está disponível para documentos em rascunho.

Melhor ainda, o desenho das ferramentas protege-o: create_invoice não tem sequer um parâmetro de estado. Finalizar é uma ferramenta separada, change_invoice_state, com um enum explícito — finalized | deleted | canceled | settled | second_copy. O passo irreversível tem nome próprio e tem de ser pedido de propósito.

Apaguei o rascunho a seguir, com state: "deleted", e a conta voltou a zero documentos.

3. Omitir o IVA não adivinha — falha

Este é o achado que mais me agradou, e explico já porquê.

Criei uma linha de fatura sem indicar taxa nenhuma, a ver o que acontecia:

422: Razão de isenção deve ter uma opção selecionada

Repare no que não aconteceu. Não aplicou os 23% por omissão, apesar de o IVA23 da conta estar marcado como default_tax: 1. Assumiu isenção, e como a lei portuguesa obriga a justificar qualquer isenção com um código (M07 e companhia), recusou-se a emitir sem ele.

Porque é que isto importa tanto: o modo de falhar mais caro num sistema de faturação automática não é o erro — é o palpite. Já documentei o caso oposto em Espanha, onde os valores do Stripe vêm em cêntimos e um sistema que não valida emite alegremente uma fatura de 12.100 € em vez de 121,00 €. Ninguém dá por isso até ao trimestre.

Aqui o comportamento é o contrário: perante uma instrução ambígua, para. Um sistema que se recusa a adivinhar vale muito mais do que um que responde sempre alguma coisa — sobretudo quando do outro lado está um modelo de linguagem a preencher campos a partir de uma frase em português.

4. A armadilha do cliente duplicado (esta foi culpa minha)

Uma conta nova traz já um cliente criado: Consumidor Final, com o NIF 999999990. É o mecanismo português para faturar a quem não dá contribuinte.

Ao criar a fatura, passei um objeto client com o nome e esse mesmo NIF, a contar que fosse reconhecido. Não foi. Ficaram dois:

197529058  Consumidor Final  999999990   16:04
197536253  Consumidor Final  999999990   17:24   ← criado por mim

Dois clientes com um NIF nacional reservado e único. E, entre as 53 ferramentas do MCP, não existe nenhuma para apagar clientes — só criar, ler e atualizar. Tive de o apagar na interface web.

A armadilha é estrutural: no esquema, client está marcado como obrigatório e client_id como opcional. O campo obrigatório empurra-o exatamente para o caminho que duplica. Para referenciar um cliente existente é client_id que se usa — e passa a valer a pena confirmar antes, com find_client.

5. Os erros chegam em português

As descrições das ferramentas estão em inglês. As mensagens de erro vêm em português. Se estiver a construir tratamento de erros por correspondência de texto, conte com isso.

Encontrei o mesmo padrão no Quipu, em Espanha, onde um erro de série chega em catalão enquanto o resto da API responde em castelhano. Parece ser um hábito da casa nas APIs ibéricas de faturação.

Detalhe menor da mesma família: o campo atcud vem "N/A" na criação e "N/D" na eliminação. Duas convenções para a mesma ausência, no ciclo de vida do mesmo documento.

O mesmo problema legal, duas soluções opostas

Esta é a parte que só se vê tendo integrado os dois lados da fronteira.

Espanha e Portugal têm exatamente o mesmo problema: como faturar a um particular que não tem de dar o número de contribuinte. As soluções técnicas não podiam ser mais diferentes.

Em Espanha o tipo de documento muda e arrasta consigo uma série de numeração separada, que tem de ser correlativa e sem huecos por si só. Em Portugal o documento é o mesmo; o que muda é o cliente.

Consequência prática para quem automatiza: no lado espanhol o trabalho está em escolher a série certa antes de emitir. No lado português está em não duplicar o cliente ao emitir. São problemas completamente diferentes, e nenhuma das duas documentações menciona a existência da outra abordagem.

O que testei e o que não testei

Testei: ligação do MCP, autenticação OAuth, leitura de conta, séries, taxas, clientes, artigos e documentos; criação de uma fatura em rascunho; leitura desse rascunho; tentativa de gerar o QR Code; e eliminação. Numa conta real, em modo trial, com a série por registar. Todos os blocos JSON e mensagens de erro acima são respostas literais, com os dados pessoais da conta removidos.

Não testei: emissão finalizada. Isso exigiria registar uma série na AT e deixaria um documento fiscal permanente e incancelável nos meus registos. Não há ambiente de testes documentado, e a curiosidade não justifica um ATCUD queimado. Também não testei notas de crédito, guias de transporte, recibos, pagamentos parciais nem exportação de SAF-T.

Do lado espanhol, o que digo do Quipu vem de duas integrações completas — WooCommerce e Stripe — construídas e postas a correr contra a API real até emitir faturas corretas. Estão documentadas em os erros do Quipu com o n8n.

Vale a pena?

Para ler dados e perceber o estado do negócio, o MCP do InvoiceXpress é bastante mais direto do que montar chamadas à API à mão — e o acesso está incluído em todos os planos, incluindo o gratuito. É, à data, compatível apenas com o Claude.

Para emitir, a resposta honesta é: com cuidado, e com a certeza de que percebeu a diferença entre criar e finalizar. As duas coisas são ferramentas separadas por uma boa razão.

E se estiver a decidir que programa usar antes de chegar a esta fase, o critério que interessa está aqui: o que é mesmo obrigatório na faturação em Portugal.

Testado em agosto de 2026 contra o MCP e a API do InvoiceXpress. As APIs mudam: confirme antes de construir por cima disto. Isto não é aconselhamento fiscal.