Verificação de NF-e
Obter DANFE
Devolve o DANFE de uma NF-e verificada pela sua conta, pela chave de acesso, como arquivo PDF.
/openapi/v3/consultas/danfe/{chave}token, timestamp e sign, veja Autenticação.Devolve o DANFE (layout A4) de uma NF-e verificada pela sua conta, como arquivo PDF. Cada chamada gera o PDF a partir do veredito de verificação mais recente da nota naquele momento; a plataforma não armazena PDFs, a obtenção em si não consulta a SEFAZ e não é cobrada à parte.
Este endpoint tem um escopo próprio, que a plataforma habilita separadamente: ter a consulta por chave não dá acesso ao PDF, e vice-versa.
As falhas devolvem um status HTTP e um objeto simples {code, message} (códigos no fim da página); os erros vêm em JSON mesmo quando a requisição traz Accept: application/pdf. Falhas de autenticação (401 / 403 / 429) usam o envelope da plataforma, veja Erros de autenticação e autorização.
Parâmetros de caminho
chave* | string | Chave de acesso |
* Campo obrigatório
Content-Type: application/pdf; Content-Disposition: inline; filename="{chave}.pdf"; Cache-Control: no-store; X-Tffiscal-Nfe-Status, a situação fiscal que este PDF reflete, Autorizada (versão normal) ou Cancelada (com marca d'água de cancelada), para distinguir as duas sem interpretar o PDF.A autenticação é a mesma da consulta por chave: envie os cabeçalhos token, timestamp e sign; o corpo do GET é a string vazia e a chave faz parte do caminho assinado (regras completas em Autenticação). Com app_secret = sk_live_9f8e7d6c5b4a, a chave 35260764962869000108550990001366171195929648 e timestamp = 1784906308, a string assinada é:
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/danfe/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
Gerar ou não o PDF depende do veredito da verificação da nota no momento em que você o obtém:
| Veredito atual | Resultado |
|---|---|
VALIDATED | DANFE normal |
REJECTED com status Cancelada | DANFE com a marca d'água CANCELADA em todas as páginas |
Verificação em andamento (PENDING_SEFAZ / VALIDATING) | 409 + 10015301; obtenha depois do webhook |
Qualquer outro (demais REJECTED, VALIDATION_ERROR) | 409 + 10015302; sem PDF |
- Só é gerado o DANFE de NF-e (modelo 55).
- Para um XML enviado sem o protocolo de autorização (protNFe), o número do protocolo e a data de autorização impressos no PDF vêm do registro oficial que a plataforma obteve da SEFAZ.
- O PDF reflete o veredito mais recente no momento em que você o obtém, então a mesma nota pode gerar PDFs diferentes ao longo do tempo. Por exemplo, se a nota for cancelada depois e a nova verificação da plataforma devolver
Cancelada, a próxima obtenção traz a versão com marca d'água. Obter o PDF não atualiza o veredito; os vereditos mudam conforme as regras de Idempotência e nova verificação, e cada novo veredito é enviado pelo webhook. - A resposta traz
Cache-Control: no-store: não a guarde em cache de proxies ou gateways; se precisar manter o arquivo, salve-o você mesmo. - Por quanto tempo é possível obtê-lo: enquanto a plataforma mantiver o registro da verificação (3 meses por padrão); depois disso, envie a nota para verificação de novo.
- Ao receber
invoice.verify.completed, responda 2xx primeiro e obtenha o PDF de forma assíncrona. Não o obtenha dentro do tratamento do webhook: um tratamento mais lento reduz a taxa com que a plataforma consegue enviar webhooks para você (os requisitos do tratamento estão em Requisitos do receptor). - Obtenha o PDF só para
VALIDATEDe, se precisar, para vereditos comstatusCancelada; qualquer outro veredito devolve 409. - Repita o 503 após o
Retry-After; não repita às cegas 404 nem 409 (10015301: aguarde o webhook;10015303: primeiro reenvie o XML como descrito em "Quando falta o XML original", logo abaixo). - Limite de taxa: este endpoint tem um grupo de endpoints próprio, "obtenção de DANFE", que não consome a cota do grupo "verificação de notas"; a cota da aplicação continua compartilhada com os demais endpoints. Obter o PDF de todas as notas praticamente dobra o volume de chamadas em relação aos envios, então combine as cotas com a plataforma (veja Limite de taxa e backoff).
A plataforma gera o DANFE a partir do XML que você enviou. Em casos raros (por exemplo, uma falha no armazenamento de arquivamento), a plataforma não guardou o XML original da nota, e a obtenção do PDF devolve 409 + 10015303. Para resolver:
- Reenvie o mesmo XML sem alterações (idêntico byte a byte ao envio anterior) pela verificação de XML, sem
forceRevalidate. Enquanto o veredito estiver dentro do período de reutilização (veja Idempotência e nova verificação: por exemplo,VALIDATEDpor 24 horas a partir do momento em que foi obtido, notas canceladas sempre), a plataforma reutiliza o veredito existente (sem nova verificação e sem novo evento de webhook) e guarda o XML original. Depois do período de reutilização, o reenvio passa por uma verificação completa conforme as regras habituais, e o novo veredito é enviado pelo webhook. - Obtenha o PDF de novo (depois de uma verificação completa, quando o novo veredito chegar).
Observações:
- Um XML com conteúdo diferente é verificado de novo por completo conforme Idempotência e nova verificação; para notas canceladas / denegadas / inutilizadas, um conteúdo diferente é reutilizado como está e nada é guardado. Reenvie sempre o XML sem alterações.
- Se você também não tiver mais o XML, a plataforma não consegue gerar o DANFE (a consulta de situação na SEFAZ não devolve os itens da nota).
| Código | HTTP | |
|---|---|---|
| 10015104 | 400 | Chave malformada (comprimento / caracteres / dígito verificador). Valide localmente antes: 44 dígitos, o último é dígito verificador mod-11. |
| 10015300 | 404 | Sua conta não tem registro de verificação desta nota (a verificação feita por outro integrador não conta). Envie a nota antes pela verificação de XML; não repita a requisição. |
| 10015301 | 409 | Verificação ainda não concluída (PENDING_SEFAZ / VALIDATING). Obtenha o PDF depois de receber invoice.verify.completed. |
| 10015302 | 409 | O veredito atual não gera PDF: só VALIDATED e REJECTED com status Cancelada geram. Não repita. |
| 10015303 | 409 | A plataforma não tem o XML original desta nota. Reenvie o mesmo XML sem alterações pela verificação de XML, sem forceRevalidate, e obtenha de novo (veja "Quando falta o XML original" nesta página). |
| 10015304 | 503 | O XML original ainda está sendo arquivado. Repita após o Retry-After (5 segundos). |
| 10015305 | 503 | Geração ocupada ou temporariamente indisponível. Repita após o Retry-After; se durar mais de alguns minutos, contate a plataforma. |
| 10001000 | 500 | Erro interno da plataforma. Repita com backoff; se persistir, contate a plataforma com o timestamp e o caminho da requisição. |
