NF-e
NF-e issuance on behalf of sellers - endpoint order, status semantics, prerequisites, idempotency, scope, integration checklist and troubleshooting.
Overview
The NF-e endpoints issue product invoices (NF-e) on behalf of a registered company: issuance is accepted immediately and authorized asynchronously with SEFAZ, the result arrives by webhook or query, and an authorized invoice can be cancelled or amended with correction letters (CC-e).
Endpoints
Before issuing, the company must be registered through Register company, have its certificate linked through Link certificate, and your application should have a callback URL registered through Register webhook. The empresaId returned at registration is the path variable of every endpoint below.
| Step | Endpoint | Notes |
|---|---|---|
| 1 Issue NF-e | POST /openapi/v2/empresas/{empresaId}/nf-e | Accepted immediately; authorized asynchronously with SEFAZ |
| 2 Query NF-e | GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId} | Status, invoice data, DANFE / XML download links |
| 3 Cancel NF-e | DELETE /openapi/v2/empresas/{empresaId}/nf-e/{nfeId} | Within 24 hours of authorization |
| 4 Register correction letter | POST /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}/carta-correcao | Within 720 hours of authorization, up to 20 per invoice, protocol returned synchronously |
| 5 List correction letters | GET /openapi/v2/empresas/{empresaId}/nf-e/{nfeId}/carta-correcao | Each entry carries the receipt XML and the DACCE download link |
Every request carries the three signature headers described in Authentication; the signed path includes the /openapi prefix and the path variables (empresaId / nfeId).
Status semantics
status | Meaning |
|---|---|
AguardandoAutorizacao | From acceptance until SEFAZ replies |
Autorizada | Authorized by SEFAZ; linkDanfe / linkDownloadXml become available |
Negada | Rejected; motivoStatus carries the SEFAZ status code and description (for example 778 - Rejeicao: NCM inexistente). Fix and resubmit |
Cancelada | After a successful cancellation |
The authorized and denied outcomes are also delivered to your callback URL; the payload shapes are described in Webhooks.
Company status and prerequisites
The registration endpoint places the company in the platform approval queue; the company can issue invoices only after operations approve it and the certificate is linked. Issuing before approval returns error 10004004 (company not issuable). Check approval progress with platform operations.
Every company has one current environment (test Homologacao / production Producao); newly registered companies default to test, and switching to production is an operations action. The ambienteEmissao in an issuance request must match the current environment of the company; a mismatch returns 10004030, a hard guard against test invoices being issued into production. See Environments.
Idempotency and resubmission
Accepted issuance requests return HTTP 200 with no body and enter the asynchronous issuance flow; the result arrives via webhook or the query endpoint. Re-submitting the same id reuses the original task; if the previous attempt was denied (Negada), resending the same id with corrected fields issues again with the new payload, no new id needed. Changing key fields such as the recipient while the previous attempt is still processing or already authorized is rejected with 10004032.
Scope
| Item | Support |
|---|---|
| Invoice purpose | Regular and return invoices (finalidade=Normal / Devolucao); complementary / adjustment invoices not yet supported |
| Recipient | CPF buyers; CNPJ buyers must carry inscricaoEstadual (ICMS taxpayer) |
| Consumer presence | OperacaoPelaInternet only |
| Payment methods | One or more entries whose valor must add up to the invoice total; card processor info is not written into the NF-e |
| Freight | Fixed to no transport (modFrete=9) |
| Tax rates | Tax codes plus optional rate parameters; for CRT=3 companies omitted ad-valorem rates are filled from the rate table, and pCredSN for CSOSN 101/201 falls back to the company profile |
| DANFE link | Available in the query response and, as nfeLinkDanfe, in the authorized callback; the PDF is rendered on the first download |
| Correction letter (CC-e) | Registration and list, protocol returned synchronously, DACCE included; still no invoice.cce.registered callback |
digestValue / customer phone / address complement | Not provided at present |
Integration checklist
- Register a company → 200 +
empresaId; register the same CNPJ again → 400 +10003002. - Link the certificate → 200 with no body; wrong password → 400 +
CER0005. - Register the webhook → 200 +
webHookId. - After approval, issue with
ambienteEmissao=Homologacao→ 200 with no body; then query →AguardandoAutorizacaobecomesAutorizada, andlinkDanfe/linkDownloadXmldownload successfully. - Receive the authorized callback: the
tokenheader equals the registered value and the payload hasnfeStatus=Autorizada. - Negative cases:
ambienteEmissao=Producao→ 400 +10004030;presencaConsumidor=OperacaoPresencial→ 400 +10004031. - Cancel the just-authorized invoice → 200; query again →
Cancelada; cancel an unknown id → 404 +NFe0001. - Failure paths: wrong
sign→ 401 +10009003; unsubscribed endpoint → 403 +10009005.
Troubleshooting
Signature mismatch (401, 10009003)?
See the troubleshooting section under Authentication.
Issuance stuck in AguardandoAutorizacao?
While the company is in the test environment, this depends on the availability of the SEFAZ test environment; if it persists for more than a few minutes, contact the platform with the empresaId and nfeId.
Issuance returns 10004004?
The company has not been approved yet, or its certificate is not linked / has expired. Complete approval and certificate association after registration first.
Callbacks not arriving?
Make sure uri is a publicly reachable https/http address that returns 2xx; the platform retries with backoff and trips a circuit breaker after consecutive failures. Calling Register webhook again restores delivery.