Skip to main content

GST & compliance

Brazil NF-e in ERPNext: Why Shipment Waits for SEFAZ Clearance (2026)

In Brazil the state SEFAZ must authorise the NF-e (cStat 100) before goods move. How to gate dispatch in ERPNext, and where the IBS/CBS reform stands.

Updated 12 Oct 20268 min readBy ManojFirst published 3 Aug 2026

In Brazil you don't ship goods and invoice afterwards: the invoice is authorised first, or the goods stay in the warehouse. An NF-e (modelo 55) is sent 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 a printout of that authorised document. This guide covers the clearance model, how to tie dispatch to authorisation in ERPNext, and where the IBS/CBS reform stands as of October 2026. It describes the integration, not tax advice: confirm the rules with your Brazilian accountant.

The mistake foreign teams make is treating the NF-e like any other invoice: raise it, print it, ship, sort out tax later. In Brazil the fiscal event comes first, and the truck waits for it. I am Manoj, and I lead ERPNext and Frappe work at MithTech, a team of Frappe specialists in Bengaluru. Tying dispatch to SEFAZ authorisation is the key design decision in a Brazilian ERPNext rollout.

When can the goods actually ship?

The rule for a Brazilian dispatch: nothing leaves until the NF-e is authorised. Every other state (drafted, submitted, rejected) is a hold.

Interactive

NF-e Clearance Decider

Pick the NF-e's current state to see whether the DANFE is valid and whether the goods can legally ship.

cStat 100 — Autorizado o uso

Can the goods ship?
Yes — the NF-e is authorized
Is the DANFE valid?
Valid — prints the 44-digit access key and the authorization protocol
Where it is
SEFAZ returned protNFe with the protocol number and receipt timestamp
cStat
100 — Autorizado o uso da NF-e
Goods
May ship, accompanied by the DANFE that references the authorized NF-e

The DANFE is only an auxiliary print of the NF-e — it is valid solely once SEFAZ returns cStat 100. Couple dispatch to authorization, never to document submission.

A DANFE (Documento Auxiliar da Nota Fiscal Eletrônica) is not itself a fiscal document: it is a printed aid carrying the 44-digit access key, which anyone can use to confirm the NF-e exists and was authorised. Print one before cStat 100 comes back and it points to nothing. The authorisation protocol (protNFe, with its nProt number and receipt timestamp) is what gives the DANFE meaning, which is why dispatch waits for it.

Where the tax reform lands

Layout 4.00 remains the NF-e/NFC-e schema. The consumption-tax reform (Lei Complementar 214, 16 January 2025) introduces IBS, CBS and IS, and Nota Técnica 2025.002-RTC adds the fields to carry them (item-level groups and totals, cClassTrib, per-item tax codes) within that layout, not as a new layout number. As of 12 October 2026 the NF-e portal lists version 1.52 for testing from 26 October and production from 16 November 2026. Dates have moved several times; check the portal before you plan.

Interactive

IBS/CBS Reform Readiness Checker

Select your tax regime to see when the new IBS/CBS/IS fields become mandatory and what to plan for. Dates move: confirm them on the official portal.

Lucro Real / Presumido (CRT 3)

General-regime taxpayers are the first cohort to carry the new IBS/CBS/IS item groups (Grupo UB, totals group W03, cClassTrib). Through 2026 these fields move through a homologation-then-production transition with tolerance windows — and the exact date an NF-e without them is rejected has shifted more than once across NT 2025.002 versions. Track the current NT version on the official portal and get your gateway on the matching schema.

Reform timeline (LC 214/2025, NT 2025.002) as understood 2026-08-03. The IBS/CBS go-live and rejection dates have moved across NT versions — this is guidance on ordering, not a filing date. Confirm the current NT 2025.002 version on nfe.fazenda.gov.br.

How do you bolt clearance onto ERPNext?

ERPNext ships no maintained Brazilian fiscal module, and the community localisation threads on the forum and GitHub didn't lead to one. The practical architecture routes NF-e through a fiscal gateway that owns the schema, the certificate handling and the per-state web services.

Code recipe

Architect · Dispatch · Reconcile · Prevent

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.

ERPNext ships no maintained Brazil fiscal module. You bolt SEFAZ clearance onto ERPNext through a fiscal gateway (PAC) — do not try to talk raw SEFAZ web services from the ERP.

text
Layers (do not collapse them):

  ERPNext (Sales Invoice / Delivery Note)
      |  custom Frappe app maps ERP data -> gateway JSON
      v
  Fiscal gateway / PAC  (PlugNotas, Focus NFe, NFe.io, ...)
      |  builds signed UBL/NF-e XML, talks to SEFAZ
      v
  State SEFAZ web service  (authorization / rejection)

Why the gateway:
  • It owns the NF-e schema (layout 4.00 + NT versions),
    the digital certificate handling, and the per-state
    web-service endpoints — all of which move.
  • You keep ERPNext as the system of record and store the
    fiscal result back on the document.

Community app 'erpnext_fiscal_br' exists (simplified,
verify its maintenance + CBS/IBS readiness for your
version) — treat it as a starting point, not a guarantee.

0 of 4 steps done

Tick a step’s number when it is done; the ticks stay on this device.

Layer ERPNext behind a fiscal gateway

Keep ERPNext as the system of record. A custom Frappe app maps ERPNext data to the gateway's API; the gateway (PlugNotas, Focus NFe, NFe.io and similar) builds the signed XML and talks to the state SEFAZ web service. Avoid raw SEFAZ integration from the ERP unless you can track every Nota Técnica: the schema and endpoints change often.

Gate dispatch on authorisation

On submit, map the invoice, send it 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 shows the field to correct.

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 to keep.

Reconcile and handle contingency

Reconcile daily: chase any document without a final status, and confirm every shipped Delivery Note maps to an authorised NF-e. If SEFAZ is unavailable, use the official 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 team owns the NF-e transmission, and logistics loads the truck. The risk sits where they meet: logistics loading against a DANFE printed before authorisation, or sales treating a submitted invoice as shippable. Each role sees a different "done".

Make cStat 100 the only signal that unlocks dispatch, enforced by the system rather than by someone reading a screen. Check party and item fiscal data (CNPJ, NCM, CST) when masters are set up so rejections are rare, and show one status logistics can trust: authorised, or not. A dashboard of submitted-but-not-authorised documents stops a stuck NF-e becoming a truck waiting at the gate, or a truck on the road without valid documents.

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.

Use a gateway, or build the integration?

Use a fiscal gateway (PAC)Build raw SEFAZ integration
The gateway owns the NF-e schema and per-state endpointsYou take on the full schema and every state's (or virtual authoriser's) web services
Certificate handling and NT-version updates are managed for youYou track every Nota Técnica and certificate change yourself
Fastest route to an authorised go-liveOnly worth it for very high volume or unusual control needs
A community app like erpnext_fiscal_br can sit on top: verify its stateYou maintain the mapping and reform readiness in-house
Either way: gate dispatch on cStat 100 and store the authorised XMLEither way: sandbox-test the full clearance flow before production

At a glance

AspectWhat to know
Rule of thumbNo dispatch until SEFAZ returns cStat 100
Record to keepThe authorised XML, protocol and access key
In ERPNextA custom app plus a fiscal gateway; no maintained Frappe module
ReformIBS/CBS fields in NT 2025.002-RTC on layout 4.00; dates per the NF-e portal

FAQ: what do people ask most?

Why can't I ship goods in Brazil before the NF-e is authorised?

Because the goods travel with a DANFE, and a DANFE only means something once SEFAZ has authorised the NF-e behind it with cStat 100. Moving goods without an authorised NF-e is moving them without valid fiscal documents, which exposes the load to seizure and penalties under state rules. Authorisation, not invoice submission, 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. Teams integrate SEFAZ clearance through a fiscal gateway with a custom Frappe app, or start from a community app such as erpnext_fiscal_br (small, last updated December 2025 when we checked), whose state you should verify for your version and for the 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-RTC adds fields within layout 4.00 to carry them. Per Receita Federal and the IBS Management Committee, the fields are mandatory on NF-e from 3 August 2026, the rejection rule was postponed with no new date, and Simples Nacional issuers (MEI included) follow from 1 January 2027. Dates have moved across NT versions; confirm the current position on the official portal and with your accountant.

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 is the bottom line?

Brazil reverses the usual order: the fiscal event comes before the physical one, and the truck waits for SEFAZ. Gate dispatch on cStat 100, store the authorised XML and reconcile daily, and clearance becomes a background step. Get it wrong and you either strand shipments or move goods on documents that were never valid.

Your next step

Rolling out ERPNext for a Brazilian entity?

GST & compliance

Now see GST compliance

Comments & ratings

No comments yet. Start a new discussion.

0

Manoj · Published on 3 August 2026

Worked with us? Leave a Google review

Questions about this? Talk to the team.

Book a 30-minute Google Meet, WhatsApp us, or send a message. The engineer who works on this replies.

Send us a message

Your details go to our team's CRM and are used only to reply.