NF-e verification
DANFE retrieval
Returns the DANFE of an NF-e your account verified, by access key, as a PDF file.
/openapi/v3/consultas/danfe/{chave}token, timestamp and sign signature headers, see Authentication.Returns the DANFE (A4 layout) of an NF-e verified by your account, as a PDF file. Each call renders the PDF from the invoice's latest verification verdict at that moment; the platform does not store PDFs, retrieval itself never contacts SEFAZ, and it is not charged separately.
This endpoint has its own scope that the platform enables separately: having the chave lookup does not grant PDF retrieval, and vice versa.
Failures return an HTTP status and a bare {code, message} object (codes at the bottom of the page); errors are JSON even when the request carries Accept: application/pdf. Authentication failures (401 / 403 / 429) use the platform envelope, see Authentication and authorization errors.
Path parameters
chave* | string | Access key |
* Required field
Content-Type: application/pdf; Content-Disposition: inline; filename="{chave}.pdf"; Cache-Control: no-store; X-Tffiscal-Nfe-Status, the tax status this PDF reflects, Autorizada (regular version) or Cancelada (watermarked as cancelled), so you can tell them apart without parsing the PDF.Authentication works as for the chave lookup: send the token, timestamp and sign headers; the GET body is the empty string and the chave is part of the signed path (full rules in Authentication). Given app_secret = sk_live_9f8e7d6c5b4a, the chave 35260764962869000108550990001366171195929648 and timestamp = 1784906308, the signing string is:
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/danfe/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
Whether a PDF is produced depends on the invoice's verification verdict at the moment you fetch it:
| Current verdict | Result |
|---|---|
VALIDATED | Regular DANFE |
REJECTED with status Cancelada | DANFE with a CANCELADA watermark on every page |
Verification still running (PENDING_SEFAZ / VALIDATING) | 409 + 10015301; fetch after the webhook |
Anything else (other REJECTED, VALIDATION_ERROR) | 409 + 10015302; no PDF |
- Only NF-e (model 55) DANFEs are produced.
- For an XML submitted without the authorization protocol (protNFe), the protocol number and authorization time printed on the PDF come from the official record the platform obtained from SEFAZ.
- The PDF reflects the latest verdict at the moment you fetch it, so the same invoice can yield different PDFs over time. For example, if the invoice is cancelled later and the platform's re-verification returns
Cancelada, the next fetch returns the watermarked version. Fetching does not refresh the verdict; verdicts change under the rules in Idempotency and re-verification, and each new verdict is pushed via webhook. - The response carries
Cache-Control: no-store: do not cache it in proxies or gateways; store the file yourself if you need to keep it. - How long you can fetch it: while the platform keeps the verification record (3 months by default); after that, submit the invoice for verification again.
- On
invoice.verify.completed, return 2xx first and fetch the PDF asynchronously. Do not fetch it inside the webhook handler: a slower handler lowers the rate at which the platform can push webhooks to you (handler requirements are in Receiver requirements). - Fetch only for
VALIDATEDand, if you need them, verdicts withstatusCancelada; any other verdict returns 409. - Retry 503 after
Retry-After; do not blindly retry 404 or 409 (10015301: wait for the webhook;10015303: first resubmit the XML as described in "When the original XML is missing" right below). - Rate limits: this endpoint has its own endpoint group, "DANFE retrieval", which does not consume the "invoice verification" group quota; the application-level quota is still shared with other endpoints. Fetching every invoice roughly doubles your call volume relative to submissions, so agree on quotas with the platform (see Rate limiting and backoff).
The platform renders the DANFE from the XML you submitted. In rare cases (for example an archive storage failure) the platform did not keep the original XML of an invoice, and retrieval returns 409 + 10015303. To fix it:
- Resubmit the same XML unchanged (byte for byte identical to the previous submission) through XML verification, without
forceRevalidate. While the verdict is still within its reuse period (see Idempotency and re-verification: for exampleVALIDATEDfor 24 hours after it was reached, cancelled invoices always), the platform reuses the existing verdict (no new verification, no new webhook event) and stores the original XML. After the reuse period, the resubmission is fully re-verified under the usual rules and the new verdict is pushed via webhook. - Fetch the PDF again (after a full re-verification, once the new verdict arrives).
Notes:
- An XML with different content is fully re-verified under Idempotency and re-verification; for cancelled / denied / voided invoices different content is reused as is and nothing is stored. Always resubmit the XML unchanged.
- If you no longer have the XML either, the platform cannot produce the DANFE (the SEFAZ status query does not return the item details).
| Code | HTTP | |
|---|---|---|
| 10015104 | 400 | Malformed chave (length / characters / check digit). Validate locally first: 44 digits, the last one is a mod-11 check digit. |
| 10015300 | 404 | Your account has no verification record for this invoice (a verification by another integrator does not count). Submit it through XML verification first; do not retry. |
| 10015301 | 409 | Verification not finished yet (PENDING_SEFAZ / VALIDATING). Fetch after receiving invoice.verify.completed. |
| 10015302 | 409 | The current verdict produces no PDF: only VALIDATED and REJECTED with status Cancelada do. Do not retry. |
| 10015303 | 409 | The platform is missing the original XML of this invoice. Resubmit the same XML unchanged through XML verification, without forceRevalidate, then fetch again (see "When the original XML is missing" on this page). |
| 10015304 | 503 | The original XML is still being archived. Retry after Retry-After (5 seconds). |
| 10015305 | 503 | Generation is busy or temporarily unavailable. Retry after Retry-After; contact the platform if it lasts more than a few minutes. |
| 10001000 | 500 | Internal platform error. Retry with backoff; if persistent, contact the platform with the request timestamp and path. |
