IntegroBR NFS-e Recebidas e Emitidas — API Pública (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.

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.).