Recursos para IAAbra o contexto completo da documentação em Markdown para ChatGPT, Claude, Cursor, Copilot e outros agentes.

Onboard Integração

Use este roteiro como checklist inicial para implementar uma integração com a ACBr API com segurança.

Ordem recomendada

Crie ou acesse sua conta no Console da ACBr API.
Ative um plano ou garanta créditos disponíveis.
Escolha o ambiente inicial:
- Homologação: https://hom.acbr.api.br
- Produção: https://prod.acbr.api.br
Crie credenciais de API para o ambiente escolhido e armazene client_id e client_secret em local seguro.
Gere um token OAuth 2 com o fluxo client_credentials.
Teste uma chamada simples, como consulta de CEP ou CNPJ.
Cadastre empresa, certificado e configurações fiscais quando o serviço exigir emissão ou operação fiscal.
Implemente o serviço fiscal desejado.
Trate erros HTTP, rejeições fiscais, paginação, cotas, consumo de créditos e retentativas.
Valide em homologação, use o debug quando necessário e depois promova para produção.

Dados essenciais

URLs base

Use a URL conforme o ambiente da sua credencial:

URL base da API de produção

https://prod.acbr.api.br

Aceita documentos com finalidade produção e homologação.

URL base da API de homologação

https://hom.acbr.api.br

Aceita documentos com finalidade homologação.

URL de autenticação OAuth 2

https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token

As credenciais do tipo Produção e Sandbox utilizam o mesmo endpoint de autenticação. O que muda é a URL base da API usada depois de obter o token.

Autenticação

Toda requisição para a ACBr API deve enviar o header HTTP Authorization no formato abaixo:

Authorization: Bearer <access_token>

Esse access_token é obtido via OAuth 2 usando o fluxo client_credentials.

Para obter o token, faça uma requisição POST para a URL de autenticação com:

header Content-Type: application/x-www-form-urlencoded;
corpo com os campos grant_type, client_id, client_secret e scope.

Exemplo:

POST https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token HTTP/1.1
Host: auth.acbr.api.br
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=abcdef&client_secret=123456&scope=cep%20cnpj%20nfse

Campos do payload:

grant_type: sempre client_credentials;
client_id: seu Client ID;
client_secret: seu Client Secret;
scope: escopos que o token deve possuir, separados por espaço, como cep cnpj nfse.

Primeiro teste

Primeiro obtenha o token:

curl --request POST "https://auth.acbr.api.br/realms/ACBrAPI/protocol/openid-connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=SEU_CLIENT_ID" \
  --data-urlencode "client_secret=SEU_CLIENT_SECRET" \
  --data-urlencode "scope=cep cnpj nfse"

Depois use o token nas chamadas da API:

GET https://prod.acbr.api.br/cep/01311200 HTTP/1.1
Host: prod.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Para validar a integração antes de escrever código, consulte Usando Postman.

Fluxo de implementação

Abrir fluxo em tela cheia

Checklist

Como usar o debug

O debug ajuda a investigar falhas em emissões, eventos fiscais e comunicação com SEFAZ ou prefeituras.

Use o debug quando precisar:

analisar rejeições ou falhas sistêmicas;
verificar o payload original recebido pela ACBr API;
consultar a sequência técnica de chamadas realizadas;
obter envelopes SOAP de requisição e resposta;
enviar evidências para suporte técnico ou órgão autorizador.

Fluxo recomendado:

Identifique o ID do documento fiscal.
Chame Debug de DF-e informando o ID do documento.
Para ver o payload recebido pela ACBr API, chame Payload original recebido.
Na resposta do debug, localize o ID da requisição HTTP que deseja inspecionar.
Chame Corpo da requisição HTTP para obter o conteúdo enviado ao autorizador.
Chame Corpo da resposta HTTP para obter o conteúdo recebido do autorizador.
Guarde os arquivos retornados para análise interna ou abertura de chamado.

Todas as chamadas de debug exigem token com scope debug.

Como abrir suporte com evidências

Antes de abrir um chamado, confira a página de Status da ACBr API para verificar se existe incidente, degradação ou manutenção em andamento.

Abra um tópico em Dúvidas Privadas ACBr API quando:

o erro persistir após nova tentativa;
a resposta da API não estiver clara para a sua integração;
houver divergência entre o payload enviado e o retorno recebido;
a rejeição fiscal não parecer compatível com os dados enviados;
o debug indicar falha de comunicação com SEFAZ, prefeitura ou autorizador.

Quando a dúvida for rápida e não exigir envio de evidências, análise de payload ou investigação de documento fiscal, utilize os canais do Discord que começam com api-.

Inclua no chamado:

ambiente utilizado: homologação ou produção;
URL chamada, método HTTP e horário aproximado da requisição;
código HTTP retornado pela ACBr API;
corpo da resposta da requisição, quando disponível;
ID da resposta ou ID da requisição retornado pela ACBr API, quando disponível;
client_id que gerou o ID da resposta ou da requisição;
link do endpoint na Referência API;
ID do documento fiscal, quando aplicável;
payload original recebido pela ACBr API, obtido pelo debug;
corpo da requisição HTTP enviado ao autorizador, obtido pelo debug;
corpo da resposta HTTP recebida do autorizador, obtido pelo debug;
mensagem de rejeição da SEFAZ, prefeitura ou autorizador, quando houver;
passos para reproduzir o problema.

Não envie client_secret, token de acesso, certificado digital, senha do certificado ou outros segredos em local algum. Se precisar compartilhar payloads com dados sensíveis, envie no fórum em Dúvidas Privadas ACBr API, onde somente você e os consultores ACBr têm acesso.

Onboard Integração

Ordem recomendada​

Dados essenciais​

URLs base​

Autenticação​

Primeiro teste​

Fluxo de implementação​

Checklist​

Como usar o debug​

Como abrir suporte com evidências​

Próximos passos​