Factuarea

Factuarea MCP

Todo o seu back office, a um servidor MCP de distância.
Faturação com VeriFactu, compras, catálogo, declarações fiscais, registo de horas e automações
para empresas espanholas — como ferramentas para Claude, ChatGPT, Cursor, VS Code e qualquer cliente MCP.

English · Español

Factuarea é uma plataforma de faturação e gestão para empresas e freelancers em Espanha. Este é o seu servidor oficial de Model Context Protocol — o mesmo serviço que a equipa Factuarea executa em produção, não um wrapper construído sobre ele. Tudo o que pode fazer no painel da Factuarea ou através da sua API REST, o seu agente pode fazer em conversa: desde emitir uma fatura VeriFactu até verificar quem registou a entrada esta manhã.

Ligar

O servidor está em https://mcp.factuarea.com. Adicione-o ao seu cliente e inicie sessão com a sua conta Factuarea — sem instalação, sem chave para copiar. No ecrã de consentimento escolhe a empresa, o ambiente (produção ou teste) e exatamente quais permissões conceder.

O acesso MCP está incluído em todos os planos Factuarea, também durante o período de teste.

claude mcp add --transport http factuarea https://mcp.factuarea.com \
  --header "Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "mcpServers": {
    "factuarea": {
      "command": "npx",
      "args": ["-y", "@factuarea/mcp"],
      "env": { "FACTUAREA_API_KEY": "fact_test_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Peça-lhe coisas como

"Fatura os Talleres Ruiz pela nota de entrega de ontem e envia-lhes por email."

"Quais faturas deste trimestre ainda estão por pagar? Envia a cada cliente um lembrete."

"Converte o orçamento 2026-014 numa fatura, mas move a data de vencimento para o dia 30."

"Regista esta fatura de fornecedor e marca-a como paga por transferência bancária."

"Aumenta todos os preços na lista de preços grossista em 5 %."

"Prepara o livro do Modelo 303 para o terceiro trimestre."

"Porque é que a encomenda WooCommerce #1042 não gerou uma fatura?"

"Quem na equipa ainda não registou a entrada hoje?"

O que cobre

Cada ferramenta, o seu domínio e a permissão necessária: docs.factuarea.com/mcp/tools.

Juntamente com as ferramentas, o servidor publica 9 guias fiscais como recursos (factuarea://guardrails/…: emissão, anulação versus retificação, tipos de fatura, linhas e montantes, chaves de regime de IVA, séries, identificação do comprador, pré-requisitos VeriFactu, múltiplas empresas) e 5 fluxos de trabalho guiados como prompts: emitir uma fatura, corrigir uma falhada, registar um cliente por NIF, ligar uma loja online e rastrear uma encomenda que nunca foi faturada.

Projetado para um agente que lida com dinheiro real

Não vai quebrar o registo fiscal. Alguns erros não podem ser desfeitos depois de uma fatura existir para a agência tributária: eliminar uma fatura emitida em vez de a anular, editar uma que já não é um rascunho, anular uma retificativa. O servidor recusa essas chamadas antes de qualquer coisa ser executada, e a recusa (mcp_guardrail_violation) nomeia a regra violada (rule_id) e o guia que explica o caminho correto (guardrail_uri), para que o agente possa corrigir o rumo por si próprio.

Uma repetição nunca cria uma segunda fatura. Operações que não podem ser desfeitas aceitam um idempotency_key. Se o agente repetir a chamada após um timeout, recebe o resultado original de volta, marcado como uma repetição, em vez de um documento duplicado.

Só vê o que permitiu. Cada credencial lista apenas as ferramentas que os seus âmbitos permitem, e cada chamada é verificada novamente. Aplicações de terceiros ligadas através de OAuth recebem um catálogo selecionado; as operações mais sensíveis — escritas VeriFactu, eliminação GDPR, pagamentos, chaves de API e empresas geridas — precisam da chave de API do próprio proprietário. Nenhuma credencial acede a dados de uma empresa à qual não foi concedida.

Pratique primeiro numa cópia. Uma credencial de teste funciona numa réplica sandbox da sua empresa que herda o seu plano: nada é enviado para a AEAT, nenhum email chega aos seus clientes, nenhum webhook sai, e os envios FACe são simulados.

Segurança e privacidade

OAuth 2.1 com PKCE e tokens de atualização rotativos; chaves de API mostradas uma vez, armazenadas com hash, com expiração opcional e lista de permissões de IP; aplicações ligadas podem ser revogadas a partir do painel. Política de privacidade: factuarea.com/privacidad. Vulnerabilidades: siga por favor SECURITY.md.

Mais da Factuarea para programadores

• Documentação — referência da API REST, guias, códigos de erro e llms.txt
• SDKs — TypeScript e PHP
• CLI — a API a partir do seu terminal
• Plugins Claude Code — este servidor mais competências para construir uma integração
• Integrações — n8n e WooCommerce

Perguntas

Contribuir

Este repositório contém o pacote npm e os manifestos de registro; o servidor em si é executado na plataforma da Factuarea. Leia CONTRIBUTING.md para configurar o projeto (e AGENTS.md se você trabalha com um agente de codificação), e o Código de Conduta antes de participar. As alterações estão listadas no CHANGELOG.

Licença

O código neste repositório é MIT. O uso do servidor hospedado e da Factuarea está sujeito aos termos de serviço da Factuarea.