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

Debug

O debug da ACBr API mostra a comunicação feita com a SEFAZ ou a prefeitura durante a transmissão de um documento fiscal: os envelopes SOAP enviados e recebidos, os status retornados e o payload original da emissão. Use-o para diagnosticar rejeições e falhas de comunicação, e para gerar evidências ao abrir chamado no suporte da ACBr API ou no órgão autorizador.

Antes de começar

Duas coisas resolvem quase todas as dúvidas deste serviço:

O token precisa do escopo debug. Se a sua credencial ainda não tem esse escopo, veja Autenticação e escopo debug.
São dois IDs diferentes. O ID do documento fiscal serve para uns endpoints; o ID da requisição HTTP, para outros.

ID do documento fiscal — ex.: nfs_1f2e3d4c5b6a70819203a4b5c6d7e8f9

Retornado pela API na emissão do documento; o prefixo varia conforme o tipo (nfe_, nfs_, cte_, mdfe_…). Use em:

GET /debug/{id}
GET /debug/{id}/original-payload

ID da requisição HTTP — ex.: req_3c4d5e6f708192a3b4c5d6e7f8091a2b

Sempre com o prefixo req_, obtido em requisicoes[].http_request.id na resposta do endpoint acima. Use em:

GET /debug/http-requests/{id}/request-content
GET /debug/http-requests/{id}/response-content

ID do documento (nfe_, nfs_, cte_…)
  └─► GET /debug/{id}
        └─► requisicoes[].http_request.id  (req_…)
              ├─► GET /debug/http-requests/{req_…}/request-content
              └─► GET /debug/http-requests/{req_…}/response-content

O ID req_ só existe na resposta de GET /debug/{id} — por isso os endpoints de conteúdo nunca são o primeiro passo.

Fluxo de uso passo a passo

Os exemplos abaixo usam a URL de produção (https://prod.acbr.api.br). Em homologação/sandbox, use https://hom.acbr.api.br.

1. Consultar o debug do documento fiscal

Use o ID do documento fiscal, aquele que a API retornou quando o documento foi emitido.

Requisição

GET https://prod.acbr.api.br/debug/nfs_1f2e3d4c5b6a70819203a4b5c6d7e8f9 HTTP/1.1
Host: prod.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: application/json

Resposta

{
    "id": "nfs_1f2e3d4c5b6a70819203a4b5c6d7e8f9",
    "tipo": "nfse",
    "created_at": "2026-08-20T12:09:29.457Z",
    "requisicoes": [
        {
            "created_at": "2026-08-20T12:09:32.834Z",
            "tipo": "envio_lote",
            "lote_id": "lns_2a3b4c5d6e7f80912a3b4c5d6e7f8091",
            "http_request": {
                "id": "req_3c4d5e6f708192a3b4c5d6e7f8091a2b",
                "method": "POST",
                "uri": "https://nfse.fazenda.df.gov.br/wsnfsenacional/nfse.asmx",
                "headers": "SOAPAction: http://www.sped.fazenda.gov.br/nfse/GerarNfse",
                "response_status_code": 200,
                "response_status_reason": "OK",
                "response_headers": "HTTP/1.1 200 OK\r\nDate: Thu, 20 Aug 2026 12:09:32 GMT\r\nContent-Length: 11756\r\nContent-Type: text/xml; charset=utf-8\r\nServer: Microsoft-IIS/10.0\r\nStrict-Transport-Security: max-age=2592000\r\nX-Powered-By: ASP.NET",
                "response_time": 2251
            }
        },
        {
            "created_at": "2026-08-20T12:09:33.804Z",
            "tipo": "consulta_lote",
            "lote_id": "lns_2a3b4c5d6e7f80912a3b4c5d6e7f8091",
            "http_request": {
                "id": "req_4d5e6f708192a3b4c5d6e7f8091a2b3c"
            }
        },
        {
            "created_at": "2026-08-21T11:42:35.590Z",
            "tipo": "consulta_lote",
            "lote_id": "lns_2a3b4c5d6e7f80912a3b4c5d6e7f8091",
            "http_request": {
                "id": "req_5e6f708192a3b4c5d6e7f8091a2b3c4d"
            }
        },
        {
            "created_at": "2026-08-21T19:34:41.735Z",
            "tipo": "consulta_lote",
            "lote_id": "lns_2a3b4c5d6e7f80912a3b4c5d6e7f8091",
            "http_request": {
                "id": "req_6f708192a3b4c5d6e7f8091a2b3c4d5e",
                "method": "GET",
                "uri": "https://sefin.nfse.gov.br/sefinnacional/nfse/53001000000000019100000000000000000000000000000001",
                "headers": "SOAPAction:",
                "response_status_code": 200,
                "response_status_reason": "OK",
                "response_headers": "HTTP/1.1 200 OK\r\nCache-Control: no-cache\r\nDate: Fri, 21 Aug 2026 19:34:41 GMT\r\nPragma: no-cache\r\nContent-Length: 5385\r\nContent-Type: application/json; charset=utf-8\r\nExpires: -1\r\nServer: Microsoft-IIS/10.0\r\nX-AspNet-Version: 4.0.30319\r\nX-Powered-By: ASP.NET\r\nX-Powered-By: ARR/3.0\r\nX-Powered-By: ASP.NET",
                "response_time": 85
            }
        }
    ]
}

Cada item de requisicoes representa uma interação com o autorizador:

tipo: envio_lote (envio do lote), consulta_lote (consulta do processamento do lote) ou cons_sit_dfe (consulta de situação do DF-e);
lote_id: identificador do lote ao qual a requisição pertence — observe que várias consultas podem compartilhar o mesmo lote;
codigo_status / motivo_status: o retorno da SEFAZ/prefeitura para aquela etapa, quando informado;
http_request.id: é este valor que você usará nos próximos passos.

No exemplo acima, o documento gerou quatro interações: um envio_lote e três consulta_lote, todas com o mesmo lote_id. A última consulta, um dia depois, é a que efetivamente obteve o retorno do autorizador.

Requisições sem detalhes

Alguns itens trazem apenas o http_request.id, sem method, uri ou dados de resposta. Isso indica que a requisição foi registrada mas não chegou a ser transmitida ou respondida (por exemplo, uma consulta interrompida). Nesses casos, os endpoints de conteúdo tendem a retornar vazio — use o id de uma requisição que possui response_status_code.

2. Obter o corpo da requisição enviada ao autorizador

Use o http_request.id obtido no passo anterior, e não o ID do documento.

Requisição

GET https://prod.acbr.api.br/debug/http-requests/req_3c4d5e6f708192a3b4c5d6e7f8091a2b/request-content HTTP/1.1
Host: prod.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Resposta

O corpo é retornado exatamente como foi armazenado pela API — normalmente o envelope SOAP enviado ao autorizador, possivelmente compactado (GZIP):

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GerarNfse xmlns="http://www.sped.fazenda.gov.br/nfse">
      <nfseCabecMsg>...</nfseCabecMsg>
      <nfseDadosMsg>...</nfseDadosMsg>
    </GerarNfse>
  </soap:Body>
</soap:Envelope>

Conteúdo compactado

Se o conteúdo retornado não for legível, ele provavelmente está compactado com GZIP. Salve a resposta em arquivo e descompacte antes de analisar. Em curl, use --compressed:

curl -H "Authorization: Bearer $TOKEN" \
  "https://prod.acbr.api.br/debug/http-requests/req_3c4d5e6f708192a3b4c5d6e7f8091a2b/request-content" \
  --compressed -o requisicao.xml

3. Obter o corpo da resposta recebida do autorizador

Também usa o http_request.id, no mesmo formato do passo anterior.

Requisição

GET https://prod.acbr.api.br/debug/http-requests/req_3c4d5e6f708192a3b4c5d6e7f8091a2b/response-content HTTP/1.1
Host: prod.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Resposta

O envelope SOAP retornado pela SEFAZ/prefeitura, no formato original. Em caso de falha de infraestrutura no autorizador, o conteúdo pode ser um HTML ou XML de erro em vez do envelope esperado — o que por si só já é um diagnóstico útil.

4. (Opcional) Conferir o payload original recebido pela API

Este endpoint usa o ID do documento fiscal, e não o http_request.id. Ele retorna o conteúdo exatamente como a ACBr API o recebeu no momento da emissão — útil para verificar divergências entre o que o seu sistema enviou e o que foi processado.

Requisição

GET https://prod.acbr.api.br/debug/nfs_1f2e3d4c5b6a70819203a4b5c6d7e8f9/original-payload HTTP/1.1
Host: prod.acbr.api.br
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIw...
Accept: */*

Resposta

{
  "infDPS": {
    "tpAmb": 1,
    "dhEmi": "2026-08-20T12:09:28-03:00",
    "serie": "1",
    "nDPS": "45",
    "prest": { "CNPJ": "00000000000191" },
    "toma": { "CNPJ": "00000000000272", "xNome": "CLIENTE EXEMPLO LTDA" },
    "serv": { "cServ": { "cTribNac": "010101", "xDescServ": "SERVICO DE EXEMPLO" } },
    "valores": { "vServPrest": { "vServ": 1000.00 } }
  }
}

5. Encaminhar as evidências

Salve os conteúdos obtidos nos passos 2 e 3 em arquivos e encaminhe-os ao suporte da ACBr API, da SEFAZ ou da prefeitura, conforme o caso.

Autenticação e escopo `debug`

Todas as requisições à API devem ser autenticadas usando um token de acesso contendo o scope debug.

O escopo debug precisa existir em dois lugares

O escopo debug só funciona se ele estiver:

Autorizado no seu Client ID (a credencial criada no Console da ACBr API); e
Solicitado no parâmetro scope da requisição que gera o token de acesso.

Se a credencial que você usa hoje não possui o escopo debug autorizado, pedir o escopo na requisição de token não é suficiente: o servidor de autenticação recusa a requisição, porque o escopo não existe na credencial. Nesse caso, crie uma nova credencial (novo Client ID / Client Secret) no console e gere um novo token com o escopo correto.

Passo 1 — Garantir o escopo `debug` na credencial

Acesse o Console da ACBr API e abra a seção Credenciais de API.
Verifique se a credencial que você utiliza possui o escopo debug autorizado.
Não possui? Clique em Criar credencial, selecione o tipo (Produção ou Sandbox), inclua o escopo debug entre os escopos da credencial e confirme.
Anote o novo Client ID e Client Secret (o Client Secret é exibido uma única vez).

Consulte Criação das credenciais para o passo a passo completo.

Passo 2 — Gerar um novo token com o escopo `debug`

Mesmo que a credencial já tenha o escopo autorizado, um token gerado anteriormente sem debug continua sem debug. É necessário gerar um novo token incluindo o escopo:

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=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET&scope=nfe%20debug

Dica

Os escopos são separados por espaço, que no corpo application/x-www-form-urlencoded deve ser codificado como %20. Inclua o debug junto dos escopos que você já utiliza (nfe, nfce, cte, mdfe, nfse, etc.).

Passo 3 — Conferir se o token realmente recebeu o escopo

Na resposta do endpoint de token, verifique a propriedade scope:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIw...",
    "token_type": "bearer",
    "scope": "empresa nfe debug",
    "expires_in": 2592000
}

Se a palavra debug não aparecer em scope, o token não terá acesso aos endpoints de debug — volte ao Passo 1 e crie uma nova credencial com o escopo autorizado.

Erro comum

Se a própria requisição de token for recusada (ex.: invalid_scope), é porque o escopo debug não existe na credencial usada. Não adianta repetir a requisição: crie uma nova credencial com o escopo debug no console.

Já um token válido, porém sem o escopo, resulta em HTTP 401/403 ao chamar os endpoints de debug. Isso não é um problema com o ID do documento, e sim com o token.

Resolução de problemas

Sintoma	Causa provável	O que fazer
`401` / `403` em qualquer endpoint de debug	Token sem o escopo `debug`	Confira o campo `scope` da resposta do token. Se faltar `debug`, verifique o escopo da credencial no console e gere um novo token — veja Autenticação e escopo `debug`
A requisição de token é recusada ao incluir `scope=debug` (ex.: `invalid_scope`)	O escopo `debug` não existe na credencial (Client ID) usada	Crie uma nova credencial no console incluindo o escopo `debug` e gere um novo token com ela
`404` em `/debug/http-requests/{id}/...`	Foi usado o ID do documento (`nfe_...`, `nfs_...`) no lugar do `http_request.id`	Chame antes `GET /debug/{id}` e use o valor de `requisicoes[].http_request.id` — veja Antes de começar
`404` em `/debug/{id}`	ID do documento incorreto, ou documento de outra conta/ambiente	Confirme o ID retornado na emissão e se está usando o ambiente correto (`prod` × `hom`)
`requisicoes` vazio	O documento ainda não chegou a ser transmitido ao autorizador (ex.: falha de validação antes do envio)	Use `GET /debug/{id}/original-payload` para inspecionar o que foi recebido pela API
Conteúdo retornado ilegível	Envelope compactado com GZIP	Salve em arquivo e descompacte — veja a dica no passo 2

Consulte a referência à API para Debug para saber mais sobre todos os endpoints disponíveis.

Debug

Antes de começar​

Fluxo de uso passo a passo​

1. Consultar o debug do documento fiscal​

2. Obter o corpo da requisição enviada ao autorizador​

3. Obter o corpo da resposta recebida do autorizador​

4. (Opcional) Conferir o payload original recebido pela API​

5. Encaminhar as evidências​

Autenticação e escopo debug​

Passo 1 — Garantir o escopo debug na credencial​

Passo 2 — Gerar um novo token com o escopo debug​

Passo 3 — Conferir se o token realmente recebeu o escopo​

Resolução de problemas​

Antes de começar

Fluxo de uso passo a passo

1. Consultar o debug do documento fiscal

2. Obter o corpo da requisição enviada ao autorizador

3. Obter o corpo da resposta recebida do autorizador

4. (Opcional) Conferir o payload original recebido pela API

5. Encaminhar as evidências

Autenticação e escopo `debug`

Passo 1 — Garantir o escopo `debug` na credencial

Passo 2 — Gerar um novo token com o escopo `debug`

Passo 3 — Conferir se o token realmente recebeu o escopo

Resolução de problemas