This guide on brazil nf-e in erpnext is written for Indian SMEs, with code samples, ERPNext / Medusa recipes, and step-by-step fixes you can copy into a real project. In Brazil, you don't ship goods and invoice afterwards — you get the invoice authorised first, or the goods stay in the warehouse. An NF-e (modelo 55) is transmitted as signed XML to the issuer's state SEFAZ, which validates it and returns an authorisation protocol with cStat 100 — "Autorizado o uso da NF-e." The DANFE that travels with the load is only a printout of that authorised document. Move goods without it and you are transporting without valid fiscal documentation. This guide covers the clearance model, how to couple dispatch to authorisation in ERPNext, and where the 2026 tax reform lands. This guide on brazil nf-e in erpnext is written for Indian SMEs, with code samples, ERPNext / Medusa recipes, and step-by-step fixes you can copy into a real project.
The mistake foreign teams make is treating the NF-e like a Western invoice — raise it, print it, ship, worry about tax later. In Brazil the fiscal event comes first, and the truck waits for it. I am Manoj, and I lead ERPNext and Frappe implementation programmes for multi-jurisdiction and compliance-heavy rollouts at MithTech, a 35-person Bangalore practice that designs, customises, integrates and operates business-critical software. Coupling dispatch to SEFAZ authorisation is the design decision that makes or breaks a Brazilian ERPNext rollout.
When can the goods actually ship?
The single rule that governs a Brazilian dispatch: nothing leaves until the NF-e is authorised. Every other document state — drafted, submitted, rejected — is a hold.
Pick the NF-e's current state to see whether the DANFE is valid and whether the goods can legally ship.
A DANFE (Documento Auxiliar da Nota Fiscal Eletrônica) is not itself a fiscal document — it is an auxiliary printed representation carrying the 44-digit access key. Anyone holding it can confirm the NF-e exists and was authorised. Print one before cStat 100 comes back and it references nothing. The authorisation protocol (protNFe, with its nProt number and receipt timestamp) is what makes the DANFE meaningful, which is why dispatch must wait for it.
Where the tax reform lands
Layout 4.00 remains the current NF-e/NFC-e schema. The 2026 consumption-tax reform (LC 214/2025) introduces IBS, CBS and IS, and Nota Técnica 2025.002 adds the fields to carry them — new item-level groups and totals, cClassTrib and per-item tax codes — on top of that layout, not as a new layout number.
Select your tax regime to see when the new IBS/CBS/IS fields become mandatory and what to plan for.
How do you bolt clearance onto ERPNext?
ERPNext ships no maintained Brazilian fiscal module — the official community effort stalled when its sponsor moved on, and no first-party localisation covers SEFAZ clearance or the reform. The realistic architecture routes NF-e through a fiscal gateway (PAC) that owns the schema, the certificate handling and the per-state web services.
Copy-paste the layered architecture, the dispatch hook that gates shipping on cStat 100, the daily reconciliation, and the operational habits that keep clearance from stalling dispatch.
Layer ERPNext behind a fiscal gateway
Keep ERPNext as the system of record. A custom Frappe app maps ERPNext data to the gateway's JSON; the gateway (PlugNotas, Focus NFe, NFe.io and similar) builds the signed XML and talks to the state SEFAZ web service. Do not attempt raw SEFAZ integration from the ERP — the schema and endpoints move too often.
Gate dispatch on authorisation
On submit, map the invoice, submit to the gateway, and poll for the result. Only when cStat 100 comes back do you unlock the Delivery Note and print the DANFE. A rejection blocks dispatch and surfaces the flagged field for correction — the same discipline as reconciling an Indian e-invoice IRN before you rely on it.
Store the fiscal record on the document
Save the authorisation protocol, the 44-digit access key (chNFe), the authorised XML and the DANFE PDF on the ERPNext document. The XML — not the PDF — is the fiscal record you must retain.
Reconcile and handle contingency
Reconcile daily: chase any document stuck without a final status, and confirm every shipped Delivery Note maps to an authorised NF-e. If SEFAZ is unavailable, follow the proper contingency mode — never ship on an unauthorised document intending to fix it later.
When sales, logistics and fiscal are different desks
In a Brazilian operation the sales desk raises the invoice, the fiscal/tax team owns the NF-e transmission, and logistics loads the truck. The risk sits where they meet: logistics loading against a DANFE that was printed before authorisation came back, or sales treating a submitted invoice as shippable. The three roles each see a "done" that isn't the same "done."
The control is to make cStat 100 the only signal that unlocks dispatch, enforced in the system rather than by a person reading a screen. Validate party and item fiscal data (CNPJ, NCM, CST) at master-data time so rejections are rare, and surface a single status on the document that logistics can trust: authorised, or not. A dashboard of documents submitted-but-not-authorised keeps a stuck NF-e from becoming a truck waiting at the gate — or worse, a truck on the road without valid documentation.
Draft policy for your fiscal and logistics leads to ratify. No goods leave the warehouse until the corresponding NF-e has returned cStat 100 from SEFAZ. Dispatch is gated in ERPNext on the authorisation result, never on the Sales Invoice being submitted. The authorised XML, access key and protocol are stored on the document before the DANFE is printed. Documents submitted without a final status are reconciled daily; SEFAZ outages are handled through the official contingency mode, not by shipping on an unauthorised document. Item and party fiscal data are validated at master-data setup to minimise rejections. Confirm current NF-e layout and reform (IBS/CBS) requirements on nfe.fazenda.gov.br and with your Brazilian accountant before adoption.
Should you buy the gateway, or build the integration?
| Use a fiscal gateway (PAC) | Build raw SEFAZ integration |
|---|---|
| The gateway owns the NF-e schema and per-state endpoints | You take on the full schema and 27-state web-service surface |
| Certificate handling and NT-version updates are managed for you | You track every Nota Técnica and certificate change yourself |
| Fastest route to an authorised go-live | Only worth it for very high volume or unusual control needs |
| A community app like erpnext_fiscal_br can sit on top — verify its state | You maintain the mapping and reform readiness in-house |
| Either way: gate dispatch on cStat 100 and store the authorised XML | Either way: sandbox-test the full clearance flow before production |
How do you At a glance — quick reference?
| Aspect | What to know |
|---|---|
| When to use Brazil NF-e in ERPNext | Standard fit for the common case; review edge cases against the table. |
| Typical effort | 1–4 hours for a small team; longer with custom data or multi-entity setups. |
| Main risk | Skipping reconciliation or running before the data is clean. |
| What to do next | Run the steps below, then verify against the checklist. |
FAQ: what do people ask most?
+Why can't I ship goods in Brazil before the NF-e is authorised?
Because the goods must travel with a DANFE, and a DANFE is only valid once the underlying NF-e has been authorised by SEFAZ with cStat 100. Moving goods without an authorised NF-e is transporting without valid fiscal documentation, which exposes the load to seizure and penalties. Authorisation, not invoice submission, is what releases the shipment.
+What does cStat 100 mean in an NF-e?
cStat 100 is the SEFAZ status code "Autorizado o uso da NF-e" — the document is authorised for use. It is returned in the authorisation protocol (protNFe) alongside the protocol number and receipt timestamp. Until you receive it, the NF-e is not authorised and the goods cannot ship.
+Does ERPNext support Brazil NF-e out of the box?
Not natively. ERPNext ships no maintained Brazilian fiscal module; the official community localisation effort stalled. Teams integrate SEFAZ clearance through a fiscal gateway (PAC) via a custom Frappe app, or start from a community app such as erpnext_fiscal_br whose maintenance status you should verify for your version and for the 2026 reform.
+How do the 2026 IBS and CBS reforms affect the NF-e?
The reform (LC 214/2025) adds IBS, CBS and IS, and Nota Técnica 2025.002 introduces new fields on top of layout 4.00 to carry them. General-regime taxpayers are the first cohort; Simples Nacional and MEI issuers are obligated later, in the 2027 phase. The exact go-live and rejection dates have moved across NT versions — confirm the current NT 2025.002 version on the official portal.
+What happens if we ship on a DANFE printed before authorisation?
The DANFE references an NF-e that was never authorised, so it is not backed by a valid fiscal document. The goods are in transit without valid documentation, and if the NF-e is later rejected there is no authorised record to correct against. This is exactly why dispatch must be gated on cStat 100 in the system, not left to whoever prints the DANFE.
+Which NF-e layout version is current?
Layout 4.00 remains the current NF-e and NFC-e schema version. Nota Técnica releases such as NT 2025.002 add fields and rules on top of layout 4.00 for the 2026 tax reform; they are additive notes, not a new layout number.
What related issues might you hit?
- India's GST e-invoicing IRP round-trip — the same clearance mental model in a different jurisdiction.
- Saudi Arabia's ZATCA Phase 2 clearance vs reporting — another authority-stamps-first e-invoicing regime.
- ERPNext multi-currency and multi-company setup — running a Brazilian entity inside a wider group.
What is the bottom line?
Brazil inverts the usual order: the fiscal event comes before the physical one, and the truck waits for SEFAZ. Get the coupling right — dispatch gated on cStat 100, the authorised XML stored, reconciliation running daily — and clearance becomes a background step. Get it wrong and you are either stranding shipments or, worse, moving goods on documents that were never valid.
Rolling out ERPNext for a Brazilian entity and unsure about NF-e clearance?
We layer ERPNext behind a fiscal gateway, gate dispatch on SEFAZ authorisation, and sandbox-test the full clearance flow — including the 2026 IBS/CBS fields — before you go live.