BeeL.

Faturamento eletrônico espanhol com VeriFactu (AEAT): emitir faturas, gerenciar clientes, validar NIFs.

GitHub
2

Documentação

BeeL

Servidor MCP BeeL — Facturação eletrónica VeriFactu para agentes de IA

Servidor MCP de facturação eletrónica espanhola com VeriFactu (AEAT): cria, emite e retifica faturas a partir de Claude, ChatGPT, Cursor ou VS Code.
Servidor MCP para facturação eletrónica espanhola com conformidade VeriFactu — emite, corrige e regista faturas na AEAT diretamente do seu agente de IA.
beel.es · Documentação da API · Guia MCP · npm

npm version CI Changelog MCP server License: MIT

Um servidor MCP (Model Context Protocol) que permite a um agente de IA emitir faturas eletrónicas espanholas legalmente conformes — registo VeriFactu na AEAT, tipos de fatura F1/F2, retificações R1–R5, validação de NIF contra o censo, e as chaves de regime que a regulamentação exige. Ligue-o ao Claude, ChatGPT, Cursor ou VS Code e o seu agente pode tratar da faturação espanhola — facturación electrónica e factura electrónica VeriFactu — de ponta a ponta, sem que escreva uma única chamada de API.

Não é um wrapper gerado em torno de uma API. Três coisas tornam-no utilizável por um modelo:

  • As ferramentas derivam do contrato OpenAPI público, pelo que o esquema de entrada de cada ferramenta é o esquema real da operação — enums, itens de linha, chaves de regime e tudo o resto. A superfície não pode divergir da API.
  • Uma política de inclusão de ferramentas decide o que um agente deve realmente receber. Transferências binárias, uploads multipart, infraestrutura de webhooks, operações que apenas uma sessão de navegador pode autenticar, e as obsoletas são excluídas por regra, não manualmente.
  • Proteções fiscais viajam com as ferramentas: os invariantes que um wrapper gerado perderia, tanto como documentação que o modelo lê como como verificações pré-voo que impedem um pedido não conforme antes de se tornar um documento fiscal.

Um único código, dois transportes: o servidor remoto alojado em https://mcp.beel.es/mcp (Streamable HTTP + OAuth — um início de sessão por utilizador, nada para instalar), e um servidor local stdio construído a partir deste repositório para uso sem cabeça, onde uma chave de API funciona e um início de sessão baseado em navegador não.

Início rápido

Adicione https://mcp.beel.es/mcp como conector no Claude, ChatGPT, Cursor ou VS Code e inicie sessão com a sua conta BeeL. Nada para instalar e sem chave de API para gerir: o servidor atua com as suas próprias credenciais, e o fluxo OAuth é descoberto a partir do URL.

# Claude Code
claude mcp add --transport http beel https://mcp.beel.es/mcp

Essa é toda a configuração para uso interativo. Continue a ler apenas se precisar do servidor local.

Executar localmente

Use o servidor local quando o OAuth não puder: um trabalho agendado que emite faturas, um pipeline de CI, ou qualquer processo sem cabeça onde ninguém esteja presente para concluir um início de sessão no navegador. Autentica com uma chave de API em vez disso.

Requer Node ≥ 20.

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "beel": {
      "command": "npx",
      "args": ["-y", "@beel_es/mcp"],
      "env": { "BEEL_API_KEY": "beel_sk_test_xxx" }
    }
  }
}

# Claude Code
claude mcp add beel --env BEEL_API_KEY=beel_sk_test_xxx -- npx -y @beel_es/mcp

Chaves com prefixo beel_sk_test_ são seguras para experimentar; beel_sk_live_ emite documentos fiscais reais.

As versões são publicadas a partir de CI através de npm publicação confiável, pelo que têm proveniência: o npm regista o commit e o fluxo de trabalho exatos de onde cada compilação veio. Verifique com npm audit signatures.

Cada versão também é anunciada no MCP Registry como es.beel/mcp, listando ambos os transportes, para que os clientes que navegam no registry encontrem o servidor sem serem apontados para ele. O nome é autenticado por um registo DNS em beel.es, pelo que diz que o servidor vem de nós e não meramente de algum repositório.

Uma listagem anterior sob io.github.beel-es/beel-mcp (v0.2.2) foi retirada quando o nome mudou. Os nomes do registry são identidades em vez de rótulos, pelo que uma renomeação é uma nova entrada em vez de um redirecionamento; ambos apontam para o mesmo pacote npm e o mesmo servidor alojado.

O que fornece

  • 125 ferramentas de API derivadas de openapi/public-api.yaml — faturas, clientes, produtos, faturas recorrentes, séries e configuração fiscal, validação de NIF, empresas.
  • 7 ferramentas sintéticas para as quais a API não tem um único endpoint: beel_docs_search, beel_docs_get, beel_docs_list sobre a documentação (o endpoint de pesquisa do site de docs e o Markdown de uma página de cada vez, ou algumas das suas secções numa chamada: uma página longa responde com o seu índice); beel_rules_list e beel_rules_get sobre o catálogo de regras fiscais (por id, vários ids de uma vez, domínio, palavra-chave ou código de erro); beel_schema_get, os campos dos esquemas de pedido e resposta como declarações compactas semelhantes a TypeScript do contrato incluído (por nome de esquema, ou por nome de ferramenta para a sua consulta, corpo e tipo de retorno); e beel_get_setup_status, que reporta por NIF exatamente o que falta antes de poder emitir, a única próxima ação a tomar, e os ids a partir dos quais uma integração começa (empresa, série padrão por tipo de documento, estado VeriFactu e padrões fiscais).
  • Recursos de proteção sob beel://guardrails/* — as regras fiscais, um recurso por domínio, os guias de uso da API, e beel://guardrails/errors, um catálogo de cada código de erro com a ação que exige. Os domínios e guias que se aplicam são nomeados na descrição de cada ferramenta que restringem.
  • 7 prompts de fluxo de trabalho que codificam a ordem segura de operações para os fluxos onde a ordem é o que os torna seguros: issue-invoice (validar NIF → escolher F1/F2 → verificar as portas VeriFactu → emitir), fix-invoice (anular vs corrigir), onboard-nif, setup-representation, invite-member, connect-payments e upgrade-integration.
  • Visualizador de PDF de fatura inline (MCP Apps): gerar um PDF de fatura abre-o num painel lateral em hosts que o suportam.

Um catálogo gerado de cada ferramenta, com os âmbitos que cada uma requer, vive em docs.beel.es/mcp/tools (npm run tools:catalog).

O que deliberadamente não é uma ferramenta

Transferências binárias (pré-visualização de PDF, ZIP em massa, exportação Excel/CSV), uploads multipart (importação CSV/Holded, submissão de PDF assinado), infraestrutura de webhooks, operações que apenas uma sessão de navegador pode autenticar, e cada operação deprecated. Um agente não pode conduzi-las, e cada uma custa contexto que uma ferramenta utilizável precisa. As regras estão em src/policy/tool-policy.ts.

As proteções fiscais

A faturação eletrónica espanhola tem invariantes que um LLM errará a partir do esquema sozinho — anular uma fatura que deveria ter sido corrigida, usar R1 numa fatura simplificada, editar algo que a AEAT já registou. O servidor aborda isso em três camadas, e a diferença entre elas importa:

1. Consultivo — duas fontes, mantidas separadas de propósito:

  • As regras fiscais são o catálogo que o site de documentação publica em docs.beel.es/api/rules.json: cada regra tem um id (COR-002), uma declaração, por que existe, a sua base legal, os códigos de erro que a aplicam e exemplos. O servidor lê em tempo de execução (em cache, como os outros ficheiros de docs) e serve através de beel_rules_list / beel_rules_get e um recurso por domínio (beel://guardrails/corrective, …). Nada fiscal é redigitado aqui. Um instantâneo do catálogo acompanha o pacote como recurso de recurso para quando o host de docs está inacessível; npm run sync:rules é o seu único escritor, e um teste falha se foi editado manualmente. Os antigos URIs beel://guardrails/cancel-vs-rectify, invoice-types e regime-keys ainda resolvem, para os domínios que os substituíram.
  • Os guias de uso da API — src/guardrails/rules/*.md — cobrem o que não é uma regra fiscal mas ainda assim tropeça um agente: como uma linha declara o seu preço, como uma série é configurada, em que empresa uma operação atua, como ler a validação de NIF e a prontidão de emissão, e qual ferramenta executa cada operação de fatura. Ligam a ids de regras em vez de os reafirmar.

Os domínios e guias que se aplicam são nomeados na descrição de cada ferramenta que restringem, para que a restrição viaje com a chamada.

2. Aplicado — src/guardrails/validate.ts, verificado antes de o pedido ser enviado, para que um payload mau nunca consuma uma chave de idempotência:

VerificaçãoCódigo
Exatamente um campo de preço por linhaLINE_UNIT_PRICE_XOR_DECLARED_TOTAL
Sem desconto num total declaradoLINE_DECLARED_TOTAL_FORBIDS_DISCOUNT
Sem retenção de IRPF numa fatura simplificada (F2)SIMPLIFICADA_FORBIDS_IRPF
Sem nif ou alternative_id no destinatário de uma fatura simplificada (F2)SIMPLIFIED_INVOICE_FORBIDS_IDENTIFIED_RECIPIENT
Sobretaxa de equivalência apenas sob regime 18, e 18 apenas com umSURCHARGE_REQUIRES_REGIME / REGIME_REQUIRES_SURCHARGE
O formato da série pode distinguir os seus períodos de reinícioSERIES_ANNUAL_REQUIRES_YEAR / SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR
A numeração só é inicializada na chamada que ativa a empresaNUMBERING_REQUIRES_ACTIVATION
As linhas SUPLIDO carregam a sua referência de origemverificado localmente
Texto de isenção apenas sob razão OTROverificado localmente
As retificações passam pela sua própria operação, não type: CORRECTIVEverificado localmente

3. Explicado — a API BeeL já responde bem: o seu message é escrito para um humano no idioma do chamador, error.details carrega os detalhes, e o campo RFC 7807 type liga a uma página de documentação para esse código exato. O servidor retransmite tudo isso intacto, e adiciona apenas as duas coisas que uma resposta não pode carregar: o remédio como uma chamada de ferramenta — os docs dirigem-se a alguém com o painel aberto ("crie uma série nas definições"), um agente precisa de beel_set_default_series — e se repetir pode possivelmente ajudar, que é o que impede um agente de fazer loop num 403 que precisa de um administrador. Quando o código é um que uma regra publicada cita, o erro também nomeia essa regra (id, título, ligação). src/guardrails/catalog.ts contém apenas códigos onde um desses se aplica; qualquer outra coisa passa, porque uma paráfrase seria pior do que o original e divergiria dele. Os blockers[] aninhados de EMISSION_NOT_READY são o caso mais claro: chegam como strings nuas sem mensagem e sem ligação, e cada um sai a nomear a ferramenta que o limpa.

A API BeeL é a autoridade em tudo isto. Cada regra aplicada espelha uma rejeição que o contrato documenta, pelo que o pré-voo é um subconjunto estrito do que a API recusa: só pode tornar a falha mais rápida e melhor explicada, nunca permitir algo que a API rejeitaria. Regras que dependem de estado do lado do servidor — correspondência do censo AEAT, o teto F2 de €3 000, se uma série existe — permanecem consultivas de propósito, porque adivinhá-las localmente rejeitaria faturas válidas. Defina BEEL_DISABLE_PREFLIGHT=1 para contornar as verificações locais completamente.

Listas curadas manualmente são ancoradas por testes: cada código catalogado deve ainda aparecer no contrato, cada operationId verificado deve ainda resolver para uma ferramenta real, e cada referência de proteção deve apontar para uma proteção que existe. Uma renomeação de API falha CI em vez de desligar silenciosamente uma verificação fiscal.

Configuração

Apenas servidor local

VariávelPropósito
BEEL_API_KEYChave de API. O prefixo seleciona o ambiente: beel_sk_test_ → Teste, beel_sk_live_ → Produção.
BEEL_ENV / BEEL_CONFIG_DIROpcional. Com BEEL_API_KEY não definido, recorre ao ~/.config/beel/config.json da CLI (beel login); BEEL_ENV (test/live, padrão test) escolhe qual chave armazenada.

Partilhado

VariávelFinalidade
BEEL_BASE_URLURL base da API. Padrão https://app.beel.es/api.
BEEL_DOCS_URLFonte de documentação para as ferramentas de docs e regras. Padrão https://docs.beel.es.
BEEL_REQUEST_TIMEOUT_MSLimite máximo para uma única chamada de API. Padrão 30000.
BEEL_DISABLE_PREFLIGHTDefina como 1 para ignorar as proteções obrigatórias.

Todos os padrões estão em src/shared/defaults.ts; nada é codificado duas vezes. As variáveis de implantação remota estão documentadas em DEPLOY.md.

O servidor inicia e lista as ferramentas sem nenhuma credencial — ele só gera erro quando uma ferramenta de API é realmente chamada. Requisições POST carregam um Idempotency-Key estável derivado da própria requisição, então um agente que tenta novamente "criar fatura" nunca pode gerar uma segunda fatura.

Autohospedagem

O servidor remoto roda em Cloudflare Workers. Consulte DEPLOY.md para o namespace KV, o cliente OAuth que o BeeL deve ter registrado e os segredos envolvidos.

Desenvolvimento

npm ci
npm run dev          # stdio server from source
npm test             # vitest
npm run typecheck    # both the Node and the Worker configs
npm run build        # single-file bundle to dist/index.js
npm run inspect      # MCP Inspector against the local build
npm run spec:verify  # the vendored contract still matches its lock
npm run sync:rules   # refresh the bundled rules snapshot from docs.beel.es

openapi/public-api.yaml é uma cópia gerada do contrato da API, e openapi/spec.lock.json registra sua versão, contagem de operações e hash. O CI falha se os dois discordarem, o que mantém um contrato versionado honesto. Consulte CONTRIBUTING.md.

O restante do ecossistema de desenvolvedores BeeL

Tudo abaixo deriva do mesmo contrato OpenAPI, então o vocabulário — tipos de fatura, chaves de regime, séries, estados VeriFactu — é idêntico onde quer que você o encontre.

API RESTO próprio contrato. Todo o resto é uma projeção dele
CLIA mesma superfície a partir de um terminal, com sandbox por padrão
Nó n8nFaturamento dentro de um fluxo de trabalho sem código
Plugin Claude CodeImplemente, audite e mantenha uma integração BeeL
Documentação legível por máquinallms.txt para agentes que preferem ler a adivinhar

FAQ

O que é o servidor MCP BeeL? Um servidor MCP que expõe a faturação eletrônica VeriFactu espanhola como ferramentas que um agente de IA pode chamar — para que Claude, ChatGPT, Cursor ou VS Code possam criar clientes, emitir faturas F1/F2, registrá-las na AEAT e enviar corretivos R1–R5 em seu nome.

Como conecto o faturamento VeriFactu ao Claude / ChatGPT / Cursor? Adicione https://mcp.beel.es/mcp como conector e faça login com sua conta BeeL — veja Início rápido. Nada para instalar e nenhuma chave de API para colar no uso interativo.

É realmente compatível com VeriFactu? Sim. As faturas são registradas na AEAT sob VeriFactu, a numeração e as séries seguem a regulamentação, e as proteções fiscais impedem requisições não conformes antes que elas se tornem um documento fiscal.

VeriFactu ou TicketBAI? Este servidor tem como alvo o VeriFactu, o sistema nacional da AEAT. O TicketBAI (regime do País Basco) está fora do escopo.

Posso usá-lo sem um agente de IA? Sim — é um servidor MCP padrão, então qualquer cliente compatível com MCP funciona, e a mesma superfície de faturamento está disponível como API REST, CLI e nó n8n.

Contribuição

Relatórios de bugs e pull requests são bem-vindos — veja CONTRIBUTING.md para saber como o projeto está organizado e quais convenções são essenciais, e Discussões para perguntas. Issues marcadas como good first issue são um bom ponto de partida. Espera-se que todos os participantes sigam o Código de Conduta. Problemas de segurança devem ser enviados para security@beel.es em vez de uma issue pública; veja SECURITY.md.

Licença

MIT © BeeL.