Offline NFC-e
Generate pairing code
Generates the single-use code a till pairs with; the first call enables offline issuing for the company.
/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacaotoken, timestamp and sign signature headers, see Authentication.One code per till. The code already carries the platform address, the company and the environment; at the store it is enough to enter it together with the A1 certificate. The company must be active and have NFC-e enabled in the environment (the emissaoNFeConsumidor block of the registration); Producao also needs a valid A1 certificate. There is no limit on devices per company: as long as a series is available, more tills can be added. Each device has an NFC-e series of its own, used online and offline with continuous numbering; serie and numeroInicial set that series and the first number, and when omitted the platform assigns the series and starts at 1. NFC-e issued through the cloud API keeps using the company profile series.
Path parameters
empresaId* | string | Company identifier |
* Required field
Request body
nomeDispositivo | string | Device name |
ambiente | string | Issuing environment |
formaPermitida | string | Allowed form |
serie | int | Device series |
numeroInicial | int | Start number |
* Required field
codigoAtivacao to the store.success | bool | Call outcome |
message | string | Result text |
| object | Generated pairing code |
Business errors come back with HTTP 200 and success = false; a missing resource comes back with HTTP 404 and field validation with HTTP 400. Always branch on code.
Hand the code to the store as text or as a .tfa file: the file is the code text itself, UTF-8 on a single line. The code works once and expires in 72 hours; if lost, generate another. A company accepts at most 20 pending codes (unused and not expired).
First code, no body
Empty body {} (or no body): default name, company current environment and any form. The first call enables offline issuing for the company; there is no separate step. nomeDispositivo, ambiente and formaPermitida not sent.
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Dispositivo 1","ambiente": "Homologacao","formaPermitida": "Qualquer","serie": null,"numeroInicial": null}}
Till with the SDK, named
Code only for the POS with the Embedded SDK. nomeDispositivo and formaPermitida = Sdk optional and sent; ambiente not sent, means the company current environment. The request is the example at the top of the page.
nomeDispositivo | string | Device name |
formaPermitida | string | Allowed form |
* Required field
Response: code for the SDK
Store or hand over codigoAtivacao now; it never comes back in any other query.
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Caixa 01","ambiente": "Homologacao","formaPermitida": "Sdk","serie": null,"numeroInicial": null}}
Series and start number set
For the till to use a series agreed with the store. serie and numeroInicial optional and sent; the first invoice of the device, online or offline, gets number 1 of series 21, and the next ones follow in sequence. The series is checked again at pairing; if it stopped being free in the meantime, pairing returns the same error code and a new code is needed.
{"nomeDispositivo": "Caixa 03","serie": 21,"numeroInicial": 1}
serie | int | Device series |
numeroInicial | int | Start number |
* Required field
Replace the computer keeping the series
The old till was deactivated and has already uploaded all offline invoices (pendentesTransmissao = 0). Send the same serie without numeroInicial: the platform continues after the highest number already known on the series and returns the effective number in numeroInicial. If the old till still has invoices to upload, the response is 10029225.
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Caixa 01","ambiente": "Homologacao","formaPermitida": "Qualquer","serie": 2,"numeroInicial": 422}}
ambienteEnvironment
| Values | Meaning |
|---|---|
| Homologacao | Testing: invoices without fiscal value, for integration tests |
| Producao | Production: invoices with fiscal value; requires a valid company A1 certificate |
formaPermitidaAllowed form
Omitted means Qualquer.
| Values | Meaning |
|---|---|
| Qualquer | Can be paired by the Invoice Assistant or by a POS with the SDK |
| Assistente | Only the Invoice Assistant pairs it; a POS with the SDK gets 10029209 |
| Sdk | Only a POS with the SDK pairs it; the Assistant refuses the code |
| Code | HTTP | |
|---|---|---|
| 10029100 | 404 | Company does not exist or belongs to another integrator. |
| 10029101 | 200 | The company cannot issue NFC-e: inactive, no NFC-e in the environment or, for Producao, no valid A1 certificate; message gives the reason. |
| 10029219 | 200 | ambiente differs from the company current environment. |
| 10029104 | 200 | Company offline issuing disabled by the platform; contact the platform. |
| 10029201 | 200 | There are already 20 pending codes for this company; use them or wait for them to expire. |
| 10029221 | 200 | serie between 890 and 999; NFC-e of a CNPJ issuer only uses series 0 to 889. |
| 10029222 | 200 | serie is the company profile NFC-e series in one of the environments; choose another. |
| 10029223 | 200 | serie is already held by another active device or a pending code of the company; message says which. |
| 10029224 | 200 | numeroInicial is not greater than the highest number already known on the series; message gives that number. |
| 10029225 | 200 | serie belongs to a deactivated or revoked device that still has offline invoices to upload; wait for the upload to finish. |
| 10029001 | 200 | ambiente or formaPermitida outside the values; message says which. |
| 10001001 | 400 | Field validation, including serie outside 0 to 999 or numeroInicial outside 1 to 999999999; message points to the field. |
