API Pública IntegroBR: NFS-e, NF-e e CT-e (1.0)

Toda chamada exige uma chave de API no cabeçalho Authorization:

Authorization: Bearer ibr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Gere uma chave em Painel → Chaves de API (/painel/chaves-api). Ela é exibida uma única vez no momento da criação — se perder, revogue e crie outra.

Existem dois ambientes de chave, e eles nunca se misturam:

Tentar acessar um recurso do ambiente errado com uma chave (ex.: pedir o detalhe de uma empresa de produção usando uma chave sandbox) devolve 404 — nunca 403 — pra não revelar se o recurso existe no outro ambiente.

Clientes oficiais, de código aberto, cobrindo todas as rotas desta página (incluindo paginação por cursor e verificação de assinatura de webhook).

Não usa Node, PHP ou Ruby? Qualquer cliente HTTP serve — a API é REST simples, sem exigir nenhum SDK.

O MCP (Model Context Protocol) é o padrão aberto que permite a um assistente de IA consultar sistemas externos. Com o servidor MCP da IntegroBR instalado, você pergunta em português no Claude, no ChatGPT ou em qualquer cliente compatível, e ele responde com os seus dados reais:

• "Quanto entrou de nota esse mês?"
• "Algum fornecedor parou de faturar pra gente?"
• "Me mostra as notas acima de R$ 5.000 de agosto"
• "Quanto já usei da franquia do plano?"

Instalação

Gere uma chave em Painel → Chaves de API e adicione ao arquivo de configuração do seu cliente MCP. No Claude Desktop, é o claude_desktop_config.json:

{
  "mcpServers": {
    "integrobr": {
      "command": "npx",
      "args": ["-y", "@integrobr/mcp-server"],
      "env": { "INTEGROBR_API_KEY": "ibr_live_..." }
    }
  }
}

Pacote no npm: @integrobr/mcp-server, código aberto sob licença MIT. Uma chave de sandbox (ibr_test_...) funciona igual e não toca em dado de produção: é o jeito seguro de experimentar antes de apontar pra conta real.

Ferramentas disponíveis

Valores em listar_documentos são filtrados em centavos: R$ 1.500,00 é 150000. A própria descrição da ferramenta avisa isso ao modelo.

Somente leitura, e isso é uma decisão de projeto

O servidor MCP da IntegroBR não emite nota, não cancela, não cria empresa e não remove nada. Ele só lê. Os endpoints de escrita desta API existem e funcionam, mas nenhum deles é exposto ao agente.

O motivo é o modelo de ameaça do MCP. Um servidor MCP entrega as ferramentas a um modelo que decide sozinho quando chamá-las, a partir de texto que pode ter vindo de qualquer lugar, inclusive do conteúdo de um documento fiscal que a própria ferramenta acabou de trazer. A descrição do serviço de uma nota é texto livre que qualquer fornecedor escreve. Num servidor que sabe emitir nota, esse texto passa a ser uma superfície de injeção com consequência fiscal real.

Quem precisa automatizar emissão usa a API REST direto, com código que passa por revisão e por um deploy, e não por um modelo decidindo no meio de uma conversa.

Internamente, todo acesso do servidor MCP passa por uma única função que só faz GET. Expor escrita exigiria mudar essa função de propósito, e isso é o atrito que se quer.

Como se compara com o MCP da NFE.io

A NFE.io também publica um servidor MCP, e as duas escolhas de arquitetura são opostas. Vale entender a diferença antes de decidir, porque ela não é de tamanho, é de modelo de confiança. Dados públicos consultados em 2 de setembro de 2026.

Onde eles são mais convenientes, e é justo dizer: por ser remoto, o deles não exige Node instalado, e boa parte das ferramentas responde sem autenticação nenhuma, o que torna o teste inicial mais rápido.

Onde nós somos mais seguros, e é o que importa quando o agente toca dado fiscal de verdade: sua chave de API nunca sai da sua máquina, e nenhum agente consegue emitir uma nota fiscal em nome da sua empresa através do nosso servidor. Um servidor MCP remoto que emite nota concentra as duas coisas ao mesmo tempo: recebe a sua credencial e tem permissão de escrita com ela.

E, na parte que é a razão de existir da IntegroBR, não há sobreposição: o monitoramento das notas que a sua empresa recebe de fornecedores, incluindo NFS-e, que costuma ser justamente a que fica descoberta.

GET /documents usa paginação por cursor (é a única lista que pode crescer sem limite prático). A resposta sempre traz:

{ "itens": [ /* ... */ ], "proximoCursor": "id-do-ultimo-item-ou-null" }

Passe o valor de proximoCursor de volta no parâmetro cursor da próxima chamada — ele é o id do último item da página anterior, não um token opaco. proximoCursor: null significa que não há mais páginas. Um cursor que não existe mais (nunca existiu, ou o item foi removido entre uma chamada e outra) não gera erro — a resposta vem com itens: [] e proximoCursor: null, como se a paginação tivesse chegado ao fim.

GET /companies não é paginado — devolve um array direto com todas as empresas da conta (o volume esperado é baixo o suficiente pra não precisar).

120 requisições por minuto, por chave de API (janela fixa de 60s). Passar do limite devolve 429 Too Many Requests:

{ "message": "Limite de requisições excedido. Tente novamente em instantes.", "code": "RATE_LIMITED" }

Erros seguem sempre o mesmo formato:

{ "statusCode": 404, "message": "Empresa não encontrada nesta conta.", "error": "Not Found" }

message pode ser uma string única ou uma lista de strings (erro de validação de campos, um item por campo inválido).

Configure webhooks pelo painel (Painel → Webhooks) para ser avisado em tempo real, sem precisar ficar consultando GET /documents. Dois eventos existem hoje:

• NOTA_RECEBIDA — uma nota nova foi capturada.
• EVENTO_FISCAL_RECEBIDO — um evento (cancelamento, substituição etc.) foi capturado para uma nota já conhecida.

Toda entrega é um POST com o corpo:

{ "tipo": "NOTA_RECEBIDA", "dados": { /* mesmo formato de um item de GET /documents */ } }

E dois cabeçalhos:

Verifique a assinatura antes de confiar no payload (exemplo em Node.js):

const crypto = require("crypto");

function assinaturaValida(corpoBruto, assinaturaRecebida, segredo) {
  const esperada = crypto.createHmac("sha256", segredo).update(corpoBruto).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(assinaturaRecebida));
}

Entregas com falha (timeout, conexão recusada, resposta não-2xx) são reenviadas com backoff exponencial. O segredo do webhook só é exibido uma vez, na criação (ou ao rotacionar) — guarde com o mesmo cuidado de uma senha.

Informações da sua conta e do seu consumo no ciclo atual.

CNPJs monitorados pela sua conta.

Notas fiscais e seus eventos (cancelamento, substituição etc.).