Offline NFC-e
Entry point for offline NFC-e issuing: when you need it, how to choose between the embedded SDK and the Invoice Assistant, the integration flow, the numbering and upload rules, and how you get the results.
This page is the entry point for offline NFC-e issuing: when you need it, how to choose between the two integration options and which steps the integration takes. After reading it you can pick an option and know which page covers each step. The company must already be integrated as required for cloud NFC-e.
When you need offline issuing
When the store loses its connection to the platform, the till must still issue the invoice on the spot and hand it to the consumer. Offline issuing lets the till issue an offline contingency invoice (an NFC-e signed and issued on the local machine while offline, waiting to be uploaded for authorization) and print the receipt right away; once the network is back, the invoice is uploaded automatically (sent to the platform and then to SEFAZ for authorization), and the result is delivered to you as usual.
While the network is up, invoices are authorized online as usual, with the same results as cloud NFC-e.
Which option to choose
| Option 1: SDK embedded in the POS | Option 2: Integrate the Invoice Assistant | |
|---|---|---|
| What it is | The POS embeds the development kit and the offline issuing core runs with the POS | TF Fiscal Invoice Assistant (a Windows program) is installed on the store computer and the POS calls its local interface |
| Who it suits | In-house Java POS software that should not require an extra program at the store | Integrators who do not want to change the POS internals; stores without a POS that use the assistant's built-in quick issuing |
| What you do | Add the SDK, ship the runtime with the installer, call the issuing methods, handle events | The store installs the assistant; the POS points its issuing calls to the local address, with the same request body as the cloud issuing endpoint |
| Effort | Medium: you write initialization, pairing and event handling code | Small: only the call address and the authentication header change |
| Tax classes | Supported with a connection; when offline, send impostos | Supported with a connection; when offline, send impostos |
Recommendation: if your POS is in-house Java software, choose the embedded SDK; otherwise choose the Invoice Assistant. The embedded SDK is available only for Java. Pick either option; different tills of the same company can also use different options.
Integration flow
Before you start, the company must be registered with NFC-e enabled and have its certificate linked.
- Generate pairing codes: for each till, call Generate pairing code and hand the returned pairing code (a single-use credential that binds one till to the company) to the store. The first call enables offline issuing for the company.
- Install and pair at the store: for the embedded SDK, see the preparation and pairing sections of the Embedded SDK tutorial; for the Invoice Assistant, see the installation and pairing section of the Invoice Assistant tutorial. Each till is paired only once.
- Issue: with the embedded SDK, call the issuing method, see Issue your first invoice; with the Invoice Assistant, call the local issuing endpoint, see Issuing, query and upload. Online and offline issuing use the same call.
- Get the results: the POS receives them locally, and the integrator server receives webhooks as usual, see How you get the results.
The pairing code validity and the maximum offline duration are controlled by the platform. The testing environment supports full integration testing; invoices issued there have no fiscal value. After the company switches environment, generate new pairing codes in the new environment and pair the tills again.
Numbers and series
- Device series: an NFC-e series of each till's own. Online and offline issuing both use it, and the till takes numbers in one sequence and signs locally: online, it hands the signed invoice to the platform, which forwards it to SEFAZ; offline, it keeps issuing offline invoices in the same sequence. Online and offline invoices of one till therefore have continuous numbers. For the same reason online issuing also needs the local certificate and tax data, which are synchronized automatically after pairing.
- Setting the series and first number: when generating the pairing code, set the device series with
serieand the first invoice number withnumeroInicial; if omitted, the platform assigns the series and starts at 1.serieOfflinein List devices is the device series. - Separate from the cloud series: NFC-e issued through the cloud issuing endpoint keeps using the series in the company profile, which never overlaps a device series. When the same CNPJ issues through several integrators, each must use non-overlapping series (device series included); otherwise SEFAZ rejects them.
- Several tills sharing one series: several tills in one store can also share one device series, with numbers taken in one place and kept continuous. The Invoice Assistant in local network mode is shared by the whole store, see Several tills in one store; the embedded SDK uses primary/secondary mode, see Multiple tills (primary/secondary mode).
- Numbers the platform handles: when an online submission has an unclear result, an online invoice is rejected, or a state does not accept number voiding, the platform closes out the numbers automatically; neither the POS software nor the integrator has to do anything. Details in the appendix.
Offline invoices and upload
- An invoice issued while offline has status
ContingenciaPendente; its receipt carries the offline contingency mark and is handed to the consumer as usual. - Once the network is back, it is uploaded automatically with no action needed; after SEFAZ authorizes it, the status becomes
Autorizada. - An offline invoice rejected by SEFAZ must be corrected under the same number and sent again; only content that does not affect amounts or taxes can change (for example NCM, CFOP, consumer document).
- Offline invoices must be uploaded within the deadline set by the state, as configured by the platform; you are warned when the deadline is near, and after it the till can no longer issue offline.
- A cancellation requested before the offline invoice is authorized is held by the platform and sent the moment the invoice is authorized.
- Invoices with fuel cannot be issued offline.
- Item lines that reference a tax class (
classeImposto) need a connection; when offline, sendimpostosinstead, see Tax classes and connectivity.
Tax classes and connectivity
Item lines can reference a tax class with classeImposto, as in cloud issuing; cfop and impostos can then be omitted. Tax classes are stored only on the platform: when issuing, the Invoice Assistant and the embedded SDK first send the request to the platform, which expands it into complete impostos; taxes are then calculated, signed and issued on the device. The expansion is the same as in cloud issuing.
- A connection is required: when offline or when the platform cannot be reached, a request that references a tax class is rejected with
10029780, asking you to sendimpostosinstead. A rejected request does not use an invoice number, so the next invoice keeps the sequence. - The POS software provides the offline fallback: the Invoice Assistant and the embedded SDK do not cache tax classes. To keep issuing while offline, the POS software must store the expanded
impostosand sendimpostoson the item lines when offline. With the embedded SDK, thePedidoreturned byConsultarfor an invoice issued online is the expanded request. - Tax class rejected: a tax class that does not exist, one that no longer matches the company's tax regime (
IncompativelComRegime) and similar cases return the same error codes and messages as cloud issuing, such as10005202and10005220; the messages follow the Invoice Assistant interface language or the embedded SDKidioma. - Tax class recorded: each invoice records the tax class number and version used by each item line, and reports them to the platform with the invoice.
How you get the results
| Channel | Content |
|---|---|
| POS | The embedded SDK uses SDK events; the Invoice Assistant uses its local callback or queries |
| Integrator server | The usual NFC-e webhooks: upload accepted nfce.contingency_issued, authorized nfce.authorized, rejected nfce.rejected, cancellation nfce.canceled / nfce.cancel_rejected |
| Device events | nfce.device.activated (pairing), nfce.device.deactivated (deactivation), nfce.device.upload_overdue (upload deadline close); data is the device object |
- Invoices issued by a till: the webhook payload carries an extra
dispositivoIdat the end; when the device reported the till, it is followed by the till identifierterminal, which tells which till issued the invoice. For the Invoice Assistant it is the POS token name; for the embedded SDK in primary/secondary mode it is the secondary's terminal name. - Invoices without a till identifier: when the device did not report a till, for example invoices issued by the embedded SDK primary itself or in standalone mode, queries and webhooks omit the
terminalkey instead of returningnull. - Subscription: which events are delivered and how to subscribe to only some of them, see the subscription rules in Webhooks.
Endpoints
| Endpoint | Purpose |
|---|---|
| Generate pairing code | One per till, valid for 72 hours, single use |
| List devices | Connection status and invoices waiting for upload for each till |
| Deactivate device | Call it when a till is replaced or retired; permanent; offline invoices already issued are still uploaded |
Appendix: numbers the platform handles for you
The platform handles all of the following; neither the POS software nor the integrator has to do anything.
| Case | What the platform does |
|---|---|
| Unclear result after an online submission, such as a timeout, a network loss or no timely answer from the platform | That number is not used again; the till issues an offline invoice with the next number and hands it to the consumer. The platform then checks the original number: if SEFAZ authorized it, the platform cancels it by substitution; if not, the platform voids the number at SEFAZ |
| SEFAZ rejects an online invoice | The platform voids the number and it is not reused |
| The platform refuses it on the spot and never sends it out | The number goes to the next invoice |
| AC, BA and SP, or another state that switched its voiding service off | The numbers that would be voided above are not reported, and numbering simply continues after the gap. Those numbers count as used and are never issued again |
