Offline NFC-e
Invoice Assistant tutorial
Invoice Assistant tutorial: install and pair the Invoice Assistant on the store's Windows computer, have the POS call the local interface (same paths as the cloud NFC-e endpoints) to issue online or offline, get results through local callbacks or polling, plus deployment and operations, quick issuing and FAQ.
TF Fiscal Invoice Assistant (the Invoice Assistant below) is a program installed on a Windows computer in the store, made of a background service and a desktop interface. The background service embeds the offline issuing core and offers, on the local machine, an interface with the same paths and the same request body structure as the cloud NFC-e issuing endpoint (tax classes need a connection); the POS only has to point its calls to the local machine to get both online issuing and offline issuing, and after reading this page you can complete installation, integration and result handling. Before you start, the integrator calls Generate pairing code for this POS computer (formaPermitida = Assistente or Qualquer) and hands the pairing code to the store.
1 Install and pair the assistant ──► 2 POS calls the local interface to issue ──► 3 Get the results (local callback or polling)
1 Installation and pairing
Requirements
| Item | Description |
|---|---|
| Computer | Windows, the same machine as the POS; for one Assistant serving several tills see Local network mode |
| Permissions | Installing requires administrator rights |
| Installer | TfFiscalAssistente-{versao}-Setup.exe ({versao} is the version number), available from the "Downloads" tab of the "Offline issuance → Offline issuance" page in the console side menu (any signed-in user; the table shows the file size and SHA-256); if the computer lacks the WebView2 runtime it is installed automatically, which needs internet access |
| Pairing code | Generated by the integrator with Generate pairing code, formaPermitida = Assistente or Qualquer; text or .tfa file |
| Certificate | The A1 certificate of the company: already in the Windows certificate store, or a PFX file plus password |
After installation the Start menu "TF Fiscal" and the desktop get an "Assistente Fiscal" shortcut, and the background service starts with Windows. The desktop interface is for the store manager and cashiers: Overview, Issue, Today's invoices, Invoice details, Products, POS integration, Settings, About & diagnostics. Closing the interface or a crash in it does not affect issuing by the background service.
To install on many computers at once, use the silent MSI install instead, see Bulk deployment.
Setup wizard
The first time the desktop interface opens it starts the setup wizard, which only asks for the pairing code and the certificate; the platform address, environment, company and device series all come from the pairing code and the pairing result.
| Step | Content |
|---|---|
| 1 Welcome | Choose the interface language, Portuguese by default; error messages returned by the platform use this language too, and a later change in the settings takes effect immediately |
| 2 Pairing code | Paste the code, import a .tfa file or scan it with the camera. The Assistant first checks it locally and shows the environment (production / testing), the expiry, and the device series and start number set by the integrator, or that the platform assigns them starting at 1 when not set; a code restricted to the SDK form is stopped at this step |
| 3 Certificate | Lists certificates in the store that carry a CNPJ, are not expired and have a private key; or import a PFX. The imported private key is set as non-exportable and the PFX password is not stored |
| 4 Manager PIN | Set a 6 to 8 digit manager PIN, used for cancellation, correction, token management, export, backup and similar operations |
| 5 Pair | Pairs online; on success shows the company name, CNPJ, device name, device series and the number of the first invoice of this device; on failure shows the error code and what to do |
| 6 Done | Shows the local interface address and leads to "POS integration" to generate a cashier token, or straight to "Issue" |
Pairing
- If pairing fails because the platform cannot be reached, just click pair again with the same pairing code; do not generate a new one: a new code takes up one more device slot.
- Certificates shown in the list with the notice "The service cannot access the key" are stored in the local machine certificate store and cannot be used by the background service account yet: run
scripts\conceder-acesso-chave.ps1 -Thumbprint {thumbprint}({thumbprint}is the certificate thumbprint) from the installation folder as administrator, then click "Refresh". - When the same computer serves several companies (several CNPJs), entering the setup wizard again means "Add company"; it needs the manager PIN and follows the same flow.
2 Connecting the POS software
Generating a cashier token
The store manager generates the cashier token on the "POS integration" page of the desktop program:
- Enter a name (such as
PDV 01), the accessible companies (tick them when there are several CNPJs) and an optional callback URL. - The token is
tfl_followed by 43 characters and is shown only once, when generated; with a callback URL, the callback secretwhsec_…is also shown, likewise only once. - The token can be revoked on the same page with one click, effective immediately.
The cashier token only works against the local Assistant, so a leak only affects that one Assistant and it can be revoked on its own; the integrator's cloud application secret never has to go to the store.
POS software uses only the local interface below. The management interface used by the desktop program itself (paths starting with /assistente/api/) is not open to POS software: it accepts only local origins, needs a manager or cashier session, and requests carrying a session must also include the anti-forgery token issued at sign-in, so other web pages or programs cannot forge such requests.
Address and authentication
| Item | Value |
|---|---|
| Address | http://127.0.0.1:8765; in local network mode, the local network address of the Assistant computer |
| Authentication | Header Authorization: Bearer tfl_…; no cloud token / timestamp / sign |
| Content type | Content-Type: application/json |
Endpoint list
| Method | Path | Purpose | Cloud counterpart |
|---|---|---|---|
| POST | /openapi/v2/empresas/{empresaId}/nfce | Issue | Issue NFC-e |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId} | Query | Query NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar | Cancel | Cancel NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar-substituicao | Cancellation by substitution | Cancel by substitution |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cupom?formato=ESCPOS_80 | Receipt, including PDF format | Local only |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml | Authorized XML download | Local only |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml-cancelamento | Cancellation XML download | Local only |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/correcao | Same-number correction after an upload rejection | Local only |
| GET | /openapi/local/v1/situacao | Assistant status | Local only |
Differences from the cloud endpoints
- Authentication: cashier token, see Address and authentication.
modoRespostahas no effect: the local interface always waits for the result. When the online result is unclear, the core drops that number and signs offline with the next number, and the platform settles the original number after checking it; only when offline signing is not possible at that moment does it return HTTP 202 withAguardandoAutorizacao. Other successes return 200.- Tax classes need a connection: item lines can reference a tax class with
classeImposto, which the platform expands before the invoice is issued; when offline or when the platform cannot be reached, the request returns 400 and10029780, asking you to sendimpostosinstead, and no invoice number is used. The Assistant does not cache tax classes, so the POS software must store the expandedimpostosfor the offline fallback, see Tax classes and connectivity. empresaId: must be a company paired on this Assistant and accessible to the token; not paired returns 404 and10029801, no access for the token returns 403 and10029902.- Receipt and XML links:
linkDanfepoints to the local receipt (HTML format);linkDownloadXmlpoints to the local XML endpoint once the authorized XML has been downloaded to the machine, otherwise it isnull. - Local extra fields: besides the cloud fields, the response carries the fields below.
| Field | Description |
|---|---|
situacaoLocal | Local status. Two values more than status: Rejeitada (offline invoice upload rejected by SEFAZ, can be corrected under the same number) and Recusada (refused by the platform); in these two cases status shows Negada. situacaoLocal itself being Negada means rejected online, with no same-number correction. All values in Invoice status values |
cStat / xMotivo | SEFAZ result code and result message. Always together; null while pending upload and when refused by the platform |
tentativaOnline | Online attempt flag. true means it tried online first and switched to offline after an unknown result; false for invoices authorized online and for invoices signed offline directly right after a connection failure |
transmitida | Uploaded flag. Query only |
cancelamentoPendente | Pending cancellation flag. Query only; true for a cancellation requested before the offline invoice was authorized |
correcoes | Number of corrections. Query only |
xmlAutorizadoDisponivel | Authorized XML ready flag. Query only; true means it has been downloaded to the machine |
terminal | Till identifier. Name of the cashier token that issued the invoice; null for invoices issued with quick issuing in the desktop program. Reported to the platform with the invoice; same value as terminal in the cloud query and webhooks |
Response formats
| Case | HTTP | Body |
|---|---|---|
| Issue, query, correction succeeded | 200; online pending 202 | Bare object with the same structure as the cloud query, plus the local extra fields |
| Cancellation or cancellation by substitution accepted | 200 | No body; outcome in the X-Tffiscal-Cancelamento response header |
| Receipt or XML download succeeded | 200 | The file as is; types in Receipt and XML download |
| Business error | 400; invoice or company not found 404; XML unavailable 409; Assistant busy 429; internal error 500; downgrade protection 503 | Array [{codigo, mensagem}], codigo as a numeric string; one entry per field on request validation failure |
| Token or source authentication failed | 401 / 403 | Platform envelope {success, errorType, code, message} |
Error examples and how to handle each error code are in Error handling.
3 Issuing, query and upload
Issuing online
The request body is the same as cloud issuing; item lines that reference a tax class (classeImposto) need a connection, see Differences from the cloud endpoints. With the network up, the Assistant takes the next number of the device series, signs the invoice and hands it to the platform, which forwards it to SEFAZ; the result is the same as synchronous cloud issuing. Once offline it keeps the same sequence for offline invoices, so online and offline numbers are continuous, see Numbers and series.
The example below is an in-store sale with an unidentified consumer:
POST /openapi/v2/empresas/1934811222334455/nfce HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{"id": "PDV01-000130","ambienteEmissao": "Homologacao","pedido": {"presencaConsumidor": "OperacaoPresencial","pagamento": { "formas": [ { "tipo": "Dinheiro", "valor": 50.00 } ], "troco": 7.50 }},"itens": [{"cfop": "5102", "codigo": "PF-FRANGO", "descricao": "PRATO FEITO FRANGO", "ncm": "21069090","quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 32.50,"impostos": { "icms": { "situacaoTributaria": "102" }, "pis": { "situacaoTributaria": "49" }, "cofins": { "situacaoTributaria": "49" } }},{"cfop": "5405", "codigo": "7894900011517", "descricao": "REFRIGERANTE LATA 350ML", "ncm": "22021000", "cest": "0300700","quantidade": 2, "unidadeMedida": "UN", "valorUnitario": 5.00,"impostos": { "icms": { "situacaoTributaria": "500" }, "pis": { "situacaoTributaria": "49" }, "cofins": { "situacaoTributaria": "49" } }}]}
| Field | How to fill |
|---|---|
id | POS sale number. Required; it is the idempotency key: a retry of the same sale must use the same id, and the Assistant returns the original invoice without issuing again |
ambienteEmissao | Issuing environment. Required; the same environment the device was paired in |
pedido, itens | Order and items. Required; same rules as Issue NFC-e |
cliente | Consumer. Optional; not sent when the consumer is not identified |
modoResposta | Response mode. Not sent; ignored locally |
After SEFAZ authorizes, HTTP 200 comes back. First come all the cloud query fields (the echoed pedido and itens are omitted here), then the local extra fields:
{"id": "PDV01-000130","tipo": "NFC-e","status": "Autorizada","motivoStatus": null,"ambienteEmissao": "Homologacao","dataCriacao": "2026-11-11T14:02:10Z","dataUltimaAlteracao": "2026-11-11T14:02:11Z","numero": "419","serie": "2","dataEmissao": "2026-11-11T14:02:10Z","chaveAcesso": "35261111222333000181650020000004191123456780","dataAutorizacao": "2026-11-11T14:02:11Z","protocolo": { "numero": "135261234567990" },"qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004191123456780|3|2","urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta","linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cupom?formato=HTML","linkDownloadXml": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/xml","emitidaEmContingencia": false,"alertas": [],"valorTotal": 42.50,"situacaoLocal": "Autorizada","cStat": 100,"xMotivo": "Autorizado o uso da NF-e","tentativaOnline": false}
Issuing offline
Same request as issuing online. When the platform cannot be reached, the Assistant signs an offline contingency invoice locally and returns HTTP 200 with ContingenciaPendente:
{"id": "PDV01-000131","tipo": "NFC-e","ambienteEmissao": "Homologacao","situacaoLocal": "ContingenciaPendente","status": "ContingenciaPendente","chaveAcesso": "35261111222333000181650020000004219123456783","serie": "2","numero": "421","dataEmissao": "2026-11-11T15:00:00Z","qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...","urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta","emitidaEmContingencia": true,"cStat": null,"xMotivo": null,"tentativaOnline": true,"linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=HTML"}
serieis the device series of this device, shared with its online invoices and numbered continuously, different from the company profile series used by the cloud issuing endpoint; digit 35 of the access key is 9.- There is no
protocolo; print the receipt and hand it to the consumer: get the ESC/POS bytes from the receipt endpoint and send them to the printer; the receipt carries the offline contingency mark automatically, and the number of copies is set by the platform. tentativaOnline=truemeans it tried online first with an unclear result; this invoice uses the number after the one of the online attempt, and the platform settles that original number after checking it; when the last connection attempt had just failed and it signed offline directly, it isfalse.- Once online it is uploaded automatically; for the upload rules see Offline invoices and upload. The integrator server receives
nfce.contingency_issuedand thennfce.authorized, see How you get the results; the POS learns the result through the local callback or a query.
Query and upload result
Query the invoice with the id used when issuing:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
After the upload is authorized:
{"id": "PDV01-000131","tipo": "NFC-e","ambienteEmissao": "Homologacao","situacaoLocal": "Autorizada","status": "Autorizada","chaveAcesso": "35261111222333000181650020000004219123456783","serie": "2","numero": "421","dataEmissao": "2026-11-11T15:00:00Z","qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...","urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta","emitidaEmContingencia": true,"protocolo": { "numero": "135261234568001" },"cStat": 100,"xMotivo": "Autorizado o uso da NF-e","tentativaOnline": true,"transmitida": true,"cancelamentoPendente": false,"correcoes": 0,"dataUltimaAlteracao": "2026-11-11T16:20:31Z","linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=HTML","xmlAutorizadoDisponivel": true,"linkDownloadXml": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml"}
emitidaEmContingenciastaystrueafter authorization.- The Assistant downloads the authorized XML automatically after the upload is authorized; when
xmlAutorizadoDisponivelisfalseyou can also call the XML endpoint directly and the Assistant fetches it from the platform, see Receipt and XML download.
4 Get the results
The POS has two ways to get later results such as uploads and cancellations: configure a local callback so the Assistant pushes them, or poll with queries. Both can be used at the same time.
Polling
If you do not want to use callbacks, the POS periodically calls the query for invoices whose status is not final (ContingenciaPendente, AguardandoAutorizacao, or situacaoLocal = Rejeitada), for example once a minute, until the status is final; when pendentesTransmissao of GET /openapi/local/v1/situacao is 0, all offline invoices have been uploaded.
Local callback
When a callback URL was given while generating the cashier token, the Assistant pushes the invoice results of this Assistant to the POS. Headers, signature algorithm and payload structure are the same as the cloud webhook, so the cloud signature check code can be reused; the only difference is the key: use the whole callback secret whsec_… shown when the token was generated, not the integrator's app_secret.
Events
Header X-Tffiscal-Event | Trigger | nfeStatus |
|---|---|---|
nfce.contingency_issued | Signed offline on the local machine | ContingenciaPendente |
nfce.authorized | Authorized after upload, after correction, or after an online pending result | Autorizada |
nfce.rejected | Offline invoice upload rejected by SEFAZ, or an online pending invoice later rejected by SEFAZ | Negada, nfeMotivoStatus is return code plus reason |
nfce.canceled | Cancellation succeeded, including cancellation by substitution | Cancelada |
nfce.cancel_rejected | Cancellation refused | CancelamentoNegado |
nfce.intake_rejected | Local only: the platform refused this offline invoice | Recusada, nfeMotivoStatus is the platform error code plus reason; contact the platform to investigate |
nfce.device.deactivated | Local only: device deactivated or revoked | Payload in Payload |
The nfce.rejected payload does not tell the two kinds of rejection apart: after receiving it, query the invoice and act on situacaoLocal. Rejeitada is an upload rejection, handled by same-number correction; Negada is an online rejection with no same-number correction: fix it and issue again with a new id.
Operational reminders such as license, certificate, connection status and unused number reporting are not pushed to the POS; the desktop program shows them on the Overview page.
Headers and signature check
POST {callbackUrl}Content-Type: application/json; charset=utf-8X-Tffiscal-Event: nfce.contingency_issuedX-Tffiscal-Event-Id: 7b0c1d9e-2a52-4e0f-9a3e-5d2f1c0b8a77X-Tffiscal-Delivery-Id: 0f5f8d0c-9a4b-4b3d-8c0e-61f2b7d4a913X-Tffiscal-Timestamp: 1762786800X-Tffiscal-Signature: 9c1e…
{callbackUrl}is the callback URL entered when generating the token.- The signature is
hex(HMAC-SHA256(callback secret, timestamp + "." + raw request body)), 64 lowercase hex characters, computed over the raw bytes received. - Deduplicate by
X-Tffiscal-Event-Id: it does not change across retries and redeliveries.
Self-test the signature check with this fixed vector:
| Input | Value |
|---|---|
| Callback secret | whsec_testsecret |
X-Tffiscal-Timestamp | 1762790400 |
| Request body | {"tipo":"NFC-e","nfeId":"PDV-1"} |
| Expected signature | 415bce74a6740037c540f3839e69a08bd3026c8337dd49c73e8a4877889de0a4 |
Payload
Invoice events have the same fields in the same order as the cloud NFC-e callback, with dispositivoId at the end. There are no cloud file links locally: nfeLinkDanfe and nfeLinkXml are always null; get the receipt from the local receipt endpoint:
{"tipo": "NFC-e","empresaId": "1934811222334455","nfeId": "PDV01-000131","nfeStatus": "Autorizada","nfeMotivoStatus": null,"nfeLinkDanfe": null,"nfeLinkXml": null,"nfeNumero": "421","nfeSerie": "2","nfeChaveAcesso": "35261111222333000181650020000004219123456783","nfeDataEmissao": "2026-11-11T15:00:00Z","nfeDataAutorizacao": "2026-11-11T16:20:30Z","nfeNumeroProtocolo": "135261234568001","nfeQrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...","dispositivoId": "1900000000000000001"}
Payload of the device deactivated event nfce.device.deactivated:
{"tipo": "NFC-e","empresaId": "1934811222334455","dispositivoId": "1900000000000000001","situacao": "Desativado","motivo": "Caixa substituido","ocorridoEm": "2026-11-20T18:00:00Z"}
situacao is Desativado (deactivated by the integrator), Revogado (revoked by the platform), EmpresaDesativada (offline issuing for the company disabled by the platform), AplicativoBloqueado (POS software blocked by the platform) or VersaoBloqueada (POS version blocked or below the minimum); see Device status values.
Retries
- Any 2xx means delivered; non-2xx, connection failure or no response within 5 seconds counts as a failure.
- After a failure it retries after 10 seconds, 30 seconds, 2 minutes, 10 minutes and 30 minutes, then once an hour; it stops if still not delivered 24 hours after being queued.
- The "POS integration" page shows the delivery records (kept for 7 days) and allows a manual resend.
- Callback failures do not affect issuing or upload.
5 Common operations
| Operation | How | Details |
|---|---|---|
| Handle a rejected invoice | Tell them apart by situacaoLocal: Rejeitada is corrected under the same number; Negada / Recusada is issued again with a new id | Handling rejections |
| Print the receipt, download the XML | GET …/cupom?formato=…, GET …/xml, GET …/xml-cancelamento | Receipt and XML download |
| Cancel an invoice | POST …/cancelar, then read the X-Tffiscal-Cancelamento response header | Cancellation |
| Two invoices issued for the same sale | POST …/cancelar-substituicao, which cancels the original online invoice and points to the offline substitute | Cancellation by substitution |
| Show offline and pending upload on the POS screen | GET /openapi/local/v1/situacao | Assistant status |
| Handle errors | Act on the HTTP status and the error code | Error handling |
Handling rejections
Rejected invoices all have status = Negada; how to handle them depends on situacaoLocal:
situacaoLocal | Meaning | Action |
|---|---|---|
Rejeitada | Offline invoice upload rejected by SEFAZ. The invoice was already handed to the consumer and the number is taken | Correct it under the same number and send it again; do not issue another one, see below |
Negada | Rejected online by SEFAZ, including rejection after an online pending result. The platform voids the number; it is not reused | Fix the request and issue again with a new id |
Recusada | The platform refused this offline invoice. The number did not take effect | Contact the platform to find the cause; after fixing, issue again with a new id |
Submitting an issuing request with changed content under the original id returns 400 and 10029818.
Example query result after an upload rejection (the fields that are the same as in Query and upload result are omitted):
{"id": "PDV01-000131","tipo": "NFC-e","ambienteEmissao": "Homologacao","situacaoLocal": "Rejeitada","status": "Negada","chaveAcesso": "35261111222333000181650020000004219123456783","serie": "2","numero": "421","emitidaEmContingencia": true,"motivoStatus": "778 - Rejeicao: Informado NCM inexistente","cStat": 778,"xMotivo": "Rejeicao: Informado NCM inexistente","transmitida": true,"correcoes": 0}
For a same-number correction, fix the complete issuing request and submit it, with the same id as the original request. In the example below, ... stands for content identical to the original request; only the item line's ncm changed:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/correcao HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{ "id": "PDV01-000131", "ambienteEmissao": "Homologacao", "pedido": { "...": "..." }, "itens": [ { "ncm": "22021000", "...": "..." } ] }
- Only content that does not affect amounts and taxes may change, such as item NCM, CFOP or consumer document; number, series, access key and issue time stay the same.
- A change in the totals or in any line tax returns 400 and
10029821; a status other thanRejeitadareturns10029820. - Success returns HTTP 200 with the same structure as the Issuing offline response, and
situacaoLocalgoes back toContingenciaPendente, waiting for the next upload.
Receipt and XML download
Choose the receipt format with formato:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=ESCPOS_80 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
formato | Response type | Use |
|---|---|---|
ESCPOS_80 (default) | application/octet-stream | 80 mm thermal printer; send the bytes straight to the printer |
ESCPOS_58 | application/octet-stream | 58 mm thermal printer |
TEXTO | text/plain; charset=utf-8 | Plain text |
HTML | text/html; charset=utf-8 | Screen preview or browser printing |
PDF_80 | application/pdf | 80 mm roll PDF, one page per copy; for archiving or sending to the consumer |
The number of copies of an offline invoice receipt is set by the platform and already laid out in the content; print it as is. The local interface outputs with the default print settings, unaffected by the desktop program's receipt settings (see Desktop program settings and maintenance); the POS adapts it to its own printer.
Download the authorized XML:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
| Endpoint | Returns | When unavailable |
|---|---|---|
GET …/xml | The authorized XML as is, application/xml; charset=utf-8 | Not yet authorized, or not on the machine and could not be fetched from the platform: 409 and 10029841 |
GET …/xml-cancelamento | The cancellation XML as is, application/xml; charset=utf-8 | Not yet cancelled, or not on the machine and could not be fetched from the platform: 409 and 10029843 |
- When the invoice is authorized (or cancelled) but the matching XML is not on the machine, the Assistant fetches it from the platform on the spot before returning, taking up to about 30 seconds; callers should not set too short a timeout.
- At most 3 fetches run at the same time; beyond that it returns 429 and
10029918; retry later.
Cancellation
Just submit the cancellation reason:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cancelar HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{ "justificativa": "Cliente desistiu da compra no caixa" }
justificativa is required, 15 to 255 characters. Once accepted it returns HTTP 200 with no body, and the X-Tffiscal-Cancelamento response header tells what happens next:
| Value | Meaning |
|---|---|
Solicitado | Sent to the platform; the result comes by callback or query |
Agendado | The offline invoice has been uploaded but is not authorized yet; the cancellation is held by the platform and fired automatically at the moment of authorization |
EnfileiradoLocal | Queued locally: offline, or the offline / substitute invoice has not been uploaded yet; submitted in the same round right after the upload |
The cancellation deadline is the same as in the cloud, see Cancel NFC-e; a status that does not allow cancellation returns 400 and 10029822.
Cancellation by substitution
Use it when two invoices were issued for the same sale: for example PDV01-000130 was issued online, the POS did not get the result and treated it as failed, then after the network went down it issued offline invoice PDV01-000131 on this device for the same sale, and both are valid. Cancellation by substitution cancels the original invoice issued online and points to the offline invoice that replaces it:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cancelar-substituicao HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{"chaveAcessoSubstituta": "35261111222333000181650020000004219123456783","justificativa": "Venda registrada em contingencia off-line"}
| Field | How to fill |
|---|---|
nfceId (path) | Original invoice number. The invoice issued online that is to be cancelled |
chaveAcessoSubstituta | Substitute invoice access key. Required, 44 digits, the offline invoice that replaces the original |
justificativa | Cancellation reason. Required; same rules as cloud Cancel by substitution |
Preconditions:
- The original is a normal invoice issued online and authorized; an offline invoice, an already cancelled invoice or one with a pending cancellation returns 400 and
10029822. - The substitute is an offline invoice issued by this device for this company and not refused by the platform; a key that is not 44 digits, a model other than 65, a wrong check digit, a CNPJ different from the original or a key equal to the original key all return 400 and
10029845. - Missing
chaveAcessoSubstitutareturns 400 and10029909.
Once accepted it returns HTTP 200 with no body:
HTTP/1.1 200 OKX-Tffiscal-Cancelamento: EnfileiradoLocal
- The response header values are the same as in Cancellation. When the substitute invoice has not been uploaded yet or the network is down, it is
EnfileiradoLocal: the cancellation is queued locally and submitted only after the substitute invoice is uploaded successfully. - The result comes through the
nfce.canceledornfce.cancel_rejectedcallback, or by querying the original invoice. The deadline is the same as in the cloud.
Assistant status
GET /openapi/local/v1/situacao returns the status of the companies accessible to the token, useful to show hints such as "offline" or "N invoices to upload" on the POS screen:
{"versaoNucleo": "1.0.0","empresas": [{"empresaId": "1934811222334455","dispositivoId": "1900000000000000001","situacao": "Ativo","conectado": false,"ultimoContato": "2026-11-11T14:55:00Z","licencaExpiraEm": "2026-11-14T13:10:00Z","offlineAte": "2026-11-14T13:10:00Z","pendentesTransmissao": 3,"pendenteMaisAntigaEm": "2026-11-11T13:02:00Z","prazoTransmissaoAte": "2026-11-12T13:02:00Z","certificadoValidoAte": "2027-03-01T00:00:00Z","ultimoErro": null,"numerosNaoUtilizadosPendentes": 0,"restauradoPendenteSincronizacao": false}],"avisos": []}
| Field | Description |
|---|---|
versaoNucleo | Core version |
empresaId / dispositivoId | Company ID and device ID |
situacao | Device status. Values in Device status values |
conectado | Platform connection flag. true means the platform can be reached right now |
ultimoContato | Last contact time. Time of the last successful connection to the platform |
licencaExpiraEm | License expiry time |
offlineAte | Offline deadline. Past this time no more offline issuing is possible |
pendentesTransmissao | Invoices pending upload |
pendenteMaisAntigaEm | Oldest pending time. Issue time of the oldest invoice pending upload |
prazoTransmissaoAte | Upload deadline. Upload limit of the oldest invoice pending upload; past it the device can no longer issue offline |
certificadoValidoAte | Certificate expiry time |
ultimoErro | Latest error. Description of the latest error, null when there is none |
numerosNaoUtilizadosPendentes | Unused number ranges pending. Ranges of unused numbers still to be reported to the platform for voiding; if above 0 and not going down for a long time, contact the platform to check |
restauradoPendenteSincronizacao | Restore pending sync flag. true after a backup restore until a new license arrives; meanwhile offline issuing is refused and online issuing first syncs with the platform; false once aligned |
avisos | Runtime warnings. Runtime environment issues that need a technician, with text in Portuguese, an empty array when there are none; also shown at the top of the desktop program's overview page. For example, proxy authentication is configured but the Assistant service's startup parameters are wrong, so proxy authentication may not work; reinstalling the Assistant fixes it |
Error handling
Business errors are an array:
[{ "codigo": "10029817", "mensagem": "itens: obrigatório" },{ "codigo": "10029817", "mensagem": "pedido.pagamento: obrigatório" }]
Missing token (HTTP 401) is a platform envelope:
{ "success": false, "errorType": 1, "code": 10029900, "message": "Token de caixa ausente (Authorization: Bearer tfl_...)" }
| HTTP | Code | Case | Action |
|---|---|---|---|
| 401 | 10029900 / 10029901 | Missing token / token invalid or revoked | Check the Authorization header; if the token was revoked, ask the store manager for a new one |
| 403 | 10029902 | The token has no access to this company | The store manager generates a new token including that company under "POS integration" |
| 403 | 10029903 | Source address outside the allowed local network ranges | Check the local network mode settings |
| 404 | 10029801 | The company is not paired on this Assistant | Check empresaId, or add the company in the setup wizard |
| 404 | 10029819 | This invoice is not on this machine | Check nfceId |
| 400 | 10029817 | Request validation failed, one entry per field, including missing required fields and fields not in the contract (never silently ignored) | Fix as described in mensagem |
| 400 | 10029780 | An item line references a tax class, but the platform cannot be reached to expand it; no invoice number was used | Resend once the connection is back; when offline, send impostos on the item lines |
| 400 | 10029909 | Invalid request, such as a cancellation by substitution without the substitute key | Fix as described in mensagem |
| 400 | 10029818 | The same id was already used for an invoice with different content | Use a new id for a new sale; retry with the original request; for rejections see Handling rejections |
| 400 | 10029820 / 10029821 | Status does not allow correction / the correction changes amounts or taxes | Only Rejeitada can be corrected, and only non-amount content may change |
| 400 | 10029822 | Status does not allow cancellation (including when the local status is not synchronized yet and the platform refuses); for cancellation by substitution, the original is not a normal invoice issued online | Do not retry |
| 400 | 10029845 | The substitute key is invalid, or is not a non-refused offline invoice of this company on this device | Check the substitute invoice key |
| 400 | 10029804 / 10029807 | Offline and license expired / offline deadline passed | Restore the network; it recovers by itself after renewal |
| 400 | 10029808 | Device series numbers used up to 999999999 | Deactivate the device and pair it again with a new pairing code that sets a new series in serie; the platform does not change the series by itself |
| 400 | 10029810 | The oldest pending invoice is past the upload deadline | Restore the network and upload |
| 400 | 10029811 | The company or the state does not allow offline issuing | Only online issuing is possible |
| 400 | 10029816 | Device deactivated | Contact the integrator |
| 400 | 10029424 | The platform reports the number as taken; the core dropped it, retried once and still conflicts | Export the diagnostic package and contact the platform |
| 400 | 10029426 | The same id already has a non-rejected invoice on the platform, for example issued by the cloud API | Check the original invoice; use a new id for a new sale |
| 409 | 10029841 | Authorized XML unavailable | Fetch it after authorization; if it could not be fetched, retry later |
| 409 | 10029843 | Cancellation XML unavailable | Fetch it after the cancellation succeeds; if it could not be fetched, retry later |
| 429 | 10029918 | Too many XML fetches in progress | Retry later |
| 500 | 10029912 / 10029836 | Internal error of the Assistant or the core | Export the diagnostics package in "About & diagnostics" and contact technical support |
| 503 | 10029842 | Downgrade protection: the data directory was used by a newer version | Install a package no older than the version shown and do not delete the data directory, see Downgrade protection |
The full list is in Error codes. Platform and SEFAZ error codes are passed through as is.
6 Pre-launch checklist
Installation and pairing:
- The pairing code's
formaPermitidaisAssistenteorQualquer; the pairing code is valid for 72 hours and can only be used once. - The CNPJ of the chosen certificate matches the company; certificates in the certificate store have private key access granted to the background service account.
- The manager PIN is set and kept by the store manager; on computers shared by several people, turning on "Require PIN to issue" in "Settings" is recommended.
POS integration:
- Each till has its own cashier token, and the token and callback secret were stored safely when generated (they are shown only once).
- The interface address is
http://127.0.0.1:8765, or the Assistant computer's local network address in local network mode; every request carriesAuthorization: Bearer tfl_…. - Each sale uses a unique
id, and a retry of the same sale uses the sameid;ambienteEmissaomatches the environment the device was paired in. - The POS handles HTTP 202 with
AguardandoAutorizacao,ContingenciaPendente, and the three kinds of rejection told apart bysituacaoLocal, see Handling rejections. - When an offline invoice is returned, the receipt is printed right away and handed to the consumer, printed as is.
- The XML download timeout is no shorter than about 30 seconds; on 429 with
10029918, retry later.
Getting the results:
- With local callbacks: check the signature with the callback secret
whsec_…, deduplicate byX-Tffiscal-Event-Idand return 2xx within 5 seconds. - Without callbacks: periodically query invoices whose status is not final until it is.
- The POS screen can call
GET /openapi/local/v1/situacaoto show the number of invoices pending upload, watchingprazoTransmissaoAteandavisos.
Runtime environment:
- If the store reaches the internet through a proxy, the outbound proxy is configured in "Settings".
- In local network mode, an administrator has run the firewall script.
- The store manager knows that the data directory
%ProgramData%\TFFiscal\Assistente\holds the legal originals of offline invoices not yet uploaded, which must not be deleted or copied to another computer; when needed, use "Export pending package" and "Backup".
7 Deployment and operations
Bulk deployment
Several computers can be installed and paired at once with a silent MSI install; if pairing fails, the install is rolled back. The PFX password and the manager PIN do not go on the command line (any user on the same machine can see command lines in the process list); they go into a secrets file first.
Step one: an administrator generates the secrets file in an elevated PowerShell. The script asks for the PIN and the PFX password through secure input; when using a certificate already in the certificate store instead, add -SemPfx and it only asks for the PIN:
& "C:\Program Files\TFFiscal\Assistente\scripts\preparar-segredos.ps1"
- The secrets file is always created in the protected directory
%ProgramData%\TFFiscal\deploy, with the default file namesegredos.json, i.e.C:\ProgramData\TFFiscal\deploy\segredos.json; use-Nometo choose another file name. - The script first creates or tightens this directory so that only SYSTEM and Administrators can access it, then creates the file directly with restricted permissions. The file content is UTF-8 JSON
{"pin":"…","pfxSenha":"…"}. - Pairing checks the owner and access permissions of the secrets file and of its directory, and fails if they are not right: the secrets file must stay in this directory; a copy in another directory (for example
C:\deploy) is refused. - The secrets file is overwritten and deleted right after being read, whether pairing succeeds or not, so it must be generated again every time the install is rerun.
Step two: silent install:
msiexec /i TfFiscalAssistente-{versao}-x64.msi /qn /l*v instalar.log ^TFA_FILE="C:\deploy\loja.tfa" PFX_FILE="C:\deploy\certificado.pfx" SECRETS_FILE="C:\ProgramData\TFFiscal\deploy\segredos.json"
| Property | Required | Description |
|---|---|---|
TFA_FILE | Required to pair | Pairing code file path. Omitted means a plain install, and the store manager goes through the setup wizard later |
PFX_FILE | One of this or the next row | PFX certificate file path. The password is taken from pfxSenha in the secrets file |
CERT_THUMBPRINT | One of this or the previous row | Thumbprint of an existing certificate. CERT_STORE can also be sent, default LOCAL_MACHINE; the private key access script must be run first |
SECRETS_FILE | Required to pair | Secrets file path. Must be under %ProgramData%\TFFiscal\deploy; contains pin (6 to 8 digits), plus pfxSenha when using a PFX |
- The old properties
PFX_PASSWORDandADMIN_PINare no longer supported; passing them makes the install fail. - The silent install requires the WebView2 runtime to be on the computer already.
- If pairing fails because the platform cannot be reached, run the install again with the same parameters (generating the secrets file again); do not change the pairing code.
Silent pairing works in one of two ways depending on whether the computer has already been set up; this applies both to the silent MSI install and to the pairing command below:
| Case | When it happens | What pairing does | pin in the secrets file |
|---|---|---|---|
| First install | The computer has never completed setup | Pairs directly; the pin becomes the manager PIN | The new manager PIN, 6 to 8 digits |
| Adding a company after setup | Run after setup is complete: reinstalling after an uninstall (the data directory is kept), installing a newer version over the old one, or running the pairing command on a computer already set up | First signs in to the manager session with the pin, then pairs, which adds a company; companies already paired are not affected | Must be the current manager PIN; if it is wrong, the exit code is 1 and the manager PIN is not changed |
In both cases, when using a PFX certificate the secrets file must also contain pfxSenha. Running "Repair" or "Change" on the MSI of the same version does not trigger silent pairing; to add a company on a computer that is already set up, use the pairing command below directly.
On a computer where the Assistant is already installed, an administrator can also run the pairing command directly (the service must be running):
"C:\Program Files\TFFiscal\Assistente\runtime\bin\java.exe" -cp "C:\Program Files\TFFiscal\Assistente\app\*" ^com.tffiscal.nfce.assistant.AssistantMain ativar --arquivo C:\deploy\loja.tfa --pfx C:\deploy\certificado.pfx --segredos C:\ProgramData\TFFiscal\deploy\segredos.json
- To use a certificate from the certificate store, replace
--pfxwith--thumbprint {thumbprint}, optionally adding--store LOCAL_MACHINEor--store CURRENT_USER. --segredos -reads the secrets JSON from standard input without writing it to disk.- Run on a computer that is already set up, it adds a company, and the
pinin the secrets file must be the current manager PIN; the company can also be added through the setup wizard in the desktop program.
| Exit code | Meaning | What the deployment script does |
|---|---|---|
0 | Pairing succeeded | None |
1 | Pairing refused | Handle according to the error code in standard output |
2 | Invalid parameters, invalid secrets file or service unreachable | Fix the parameters and the secrets file, then rerun |
3 | Can be retried with the same pairing code | Rerun the same command unchanged; do not change the pairing code |
Upgrade, uninstall and data directory
- Upgrade: install the new version over the old one; local data is kept automatically.
- Data directory:
%ProgramData%\TFFiscal\Assistente\. Until upload, the signed files of offline invoices exist only here and are the only legal originals; the data directory is kept on uninstall; do not delete it by hand and do not copy it to another computer. - After renewing the certificate, use "Replace certificate" in "Settings" with the manager PIN; the device identity does not change.
- When the minimum version required by the platform is higher than the local version, the Overview page prompts for an upgrade; until the upgrade the device status is
VersaoBloqueadaand no new invoices can be issued.
Downgrade protection
After the data directory has been used by a newer version of the Assistant, if an older version is installed again, the older version does not start the issuing core, so as not to damage local data. The Assistant then enters startup failure mode:
- The background service does not exit and listens only on the loopback address; restarting the computer or the service does not recover it.
- The desktop interface shows a blocking page stating the minimum version to install and the current version.
- Every local interface call returns HTTP 503:
[ { "codigo": "10029842", "mensagem": "… Instale o Assistente Fiscal na versão 1.4.0 ou superior …" } ]
What to do: install a package no older than the version shown. Never delete the data directory; it may hold offline invoices not yet uploaded.
Local network mode
When one Assistant serves several tills in the same store, the store manager turns on local network mode in "Settings":
- When on, the Assistant listens on all network interfaces of the machine and only accepts sources inside the "Allowed networks" (by default the /24 range of the machine); sources outside return 403 and
10029903. - The installer does not open the firewall automatically: an administrator must run
scripts\abrir-firewall-rede-local.ps1 -RedesPermitidas {redesPermitidas}from the installation folder, where{redesPermitidas}is the allowed network range, for example192.168.0.0/24. - Whether it is on or not, every request must carry the cashier token.
- With local network mode off, callback URLs can only be loopback addresses; local network addresses are only allowed once it is on.
Several tills in one store
When a store has several tills, install a single Invoice Assistant for the whole store, on a back-office computer or on one of the tills; the other tills call it over the local network:
- Install and pair one Assistant: complete the setup wizard as in Installation and pairing. The whole store uses one pairing code and one device slot.
- Turn on local network mode: the manager turns it on in "Settings" on the Assistant computer. It is off by default, and then the Assistant only listens on the local computer, so other computers on the network cannot connect; once on, it listens on all network cards and only accepts sources in the allowed networks, by default the /24 network of the Assistant computer. For the firewall and network settings see Local network mode.
- One cashier token per till: on the "POS integration" page the manager generates a separate token for each till (starting with
tfl_), named after the till, for examplePDV 01,PDV 02; this name is the till identifierterminalon the invoices that till issues, shown in local interface responses, the cloud query and webhooks. For callbacks, the callback URL is that till's own local network address. When a till is lost or retired, revoke only its token; the other tills are not affected. - Point the POS software at the Assistant's network address: change the interface address from
http://127.0.0.1:8765to the Assistant computer's local network address, for examplehttp://192.168.0.10:8765, with that till's cashier token in the header. The interface and the calls are exactly the same as in a single-computer setup, see Endpoint list.
Result:
- The whole store shares the device series of this one device; invoices from all tills are numbered continuously, taken in order by the Assistant, with no clashes.
- When the internet is down but the local network still works, every till keeps issuing: the Assistant signs offline and uploads automatically once back online.
- The desktop program (manager PIN, quick issuing, export and backup, etc.) only opens on the Assistant computer itself; the other tills only use the local interface.
Points to watch:
- The Assistant computer is a single point of failure: if it is switched off, loses power or leaves the network, no till can issue, and offline invoices already issued wait for it to come back before upload. Keep it running and never switch it off; a UPS is recommended.
- The local network must work: if the network or switch between a till and the Assistant computer fails, that till cannot reach the Assistant and cannot issue.
- Backup option: install another Assistant on a second computer and pair it with a new pairing code. It is another device, with its own device series and numbers, and needs its own cashier tokens. If the main computer fails, the POS software switches to the backup's address and tokens and keeps issuing; invoices already issued on the main computer are still queried and uploaded there, and if it cannot be repaired, export the pending upload package as described under "Export and backup" in Desktop program settings and maintenance and hand it to the platform.
Compared with the embedded SDK: with the embedded SDK each till is by default paired as its own device with its own device series, numbered continuously within each series and independent of the others. The rules only require continuous numbering within one series, so several series in one store are equally compliant. The SDK has no single point of failure, but every till needs the certificate and takes a device slot. The SDK can also share one series across the store in primary/secondary mode, see Multiple tills (primary/secondary mode).
Desktop program settings and maintenance
All of the following are done in the desktop program on the Assistant computer itself.
Invoice details
The invoice details page shows the invoice, the QR code and the status timeline (offline signing, upload, authorization or rejection, correction), and offers:
- "Download XML" (authorized XML) and "Cancellation XML". When they are not on the machine the Assistant fetches them from the platform, taking up to about 30 seconds; wait for loading to finish and do not click repeatedly.
- "Receipt PDF" and "Download image" for the QR code.
- Cancellation by substitution: shown when the original is a normal invoice issued online and authorized; needs the manager PIN; pick the substitute invoice among today's offline invoices; same rules as Cancellation by substitution.
Outbound proxy
When the store network can only reach the internet through a proxy, the store manager configures it under outbound proxy in "Settings"; the Assistant uses it for connections to both the platform and SEFAZ:
| Item | Description |
|---|---|
| Internet connection | Direct (default), Manual proxy or Windows proxy. Windows proxy follows the Windows system proxy settings; PAC automatic configuration scripts are not supported, and in that case it connects directly |
| Address | Proxy server address. Format host:port, required in manual mode; port 8080 when the port is missing |
| User | Proxy authentication user. Leave empty for no authentication, which also clears the saved password |
| Password | Proxy authentication password. Write-only: not shown again after saving, and empty means unchanged; stored encrypted, kept out of logs and the diagnostics package |
| Bypass proxy for | Proxy bypass hosts. Separated by ;, supporting *.domain and <local> |
- After saving, the Assistant restarts the issuing core with the new proxy for it to take effect, which takes a few seconds; issuing requests arriving in the meantime wait in a queue and are not lost; if the core cannot start with the new proxy it falls back to the previous settings automatically.
- Changing the mode, address or user name requires entering the password again.
- Invalid settings are flagged in the interface with error code
10029919, and the settings stay unchanged. - If an export, backup or XML download is in progress and does not finish within 15 seconds, error code
10029920is shown and the settings stay unchanged; save again once those operations have finished.
Printed receipt
The "Printed receipt" section in "Settings" only applies to receipts printed by the Assistant itself (quick issuing, reprint, details page preview), not to receipts the POS gets through the local interface:
| Item | Values |
|---|---|
| Columns per line | 48, 42, 32, or the default for the paper width |
| Printer code page | CP1252 (default), CP860, CP850, CP437; characters missing from the code page are printed without accents |
| QR Code | Printer command: uses the printer's built-in QR code command (default); Image: printed as a bitmap, for older printers that do not understand the QR code command |
| Cut the paper after printing | Whether to cut the paper after printing |
| Copies | Number of copies per print, or by state rule; offline invoices use the number of copies set by the platform |
Export and backup
The "About & diagnostics" page offers three downloads plus restoring from a backup, all needing the manager PIN; downloaded files are saved to a local location chosen by the store manager. Only one export or backup can run at a time; while one is in progress the interface asks to try again later (error code 10029918). When the disk holding the Assistant's data directory has less than 256 MB free, exports, backups and backup file uploads are all refused (error code 10029922); free up disk space first.
| Function | Content | Use |
|---|---|---|
| Export XML | Pick the company and an issue date range (up to 31 days) to get a zip: authorized XMLs, cancellation XMLs, and a list of invoices that could not be fetched with the reason; you can tick "Only this computer" to export only the XMLs already on the machine, without fetching from the platform | Hand to the accountant every month |
| Export pending package | All signed offline invoices of every company not yet uploaded, in zip format; folders by device inside, at most 500 invoices per package, ready for the platform to import directly | When the computer is broken and there is no time to upload, hand it to the platform to upload on your behalf |
| Backup | An encrypted full copy of the issuing core's local database; the store manager must set a backup passphrase of at least 8 characters (entered twice) | Data recovery on the same computer |
| Restore backup | Upload a backup file (up to 4 GB), then enter the backup passphrase to replace the current local database with the backup | Recovery after the local database is lost or corrupted |
Export:
- When exporting XML, XMLs not on the machine are fetched from the platform one by one; with many invoices this takes several minutes, so wait for it to finish; if the platform cannot be reached, the remaining invoices are not waited for and go straight to the list of invoices that could not be fetched.
- The pending upload package holds the signed legal originals; keep it safe. Exporting does not stop the machine from continuing to upload.
Backup:
- The backup passphrase is not stored anywhere; if the passphrase is lost, the backup cannot be restored, so keep it separate from the backup file. Issuing continues as normal during a backup.
- A backup can only be restored on the same computer (the device keys are bound to the machine); a new computer must be paired again, and invoices not yet uploaded are handled with "Export pending package".
Restore from backup:
- Restoring from a backup needs the manager PIN. Restoring replaces the current local database, and the original database is saved automatically in the data directory; a wrong passphrase or an altered or corrupted backup file shows error code
10029846, the original database stays unchanged and the Assistant keeps running normally. The uploaded backup file is deleted whether the restore succeeds or not; to try again, select the file again. - During the restore the Assistant restarts the issuing core, which takes a few seconds; issuing requests arriving meanwhile wait in a queue. If an export, backup or XML download is still in progress, the Assistant waits up to 15 seconds; if it has not finished by then, the restore is not performed and error code
10029920is shown; click restore again once those operations have finished. - Offline invoices issued after the backup are not in it: if the Assistant still runs normally before restoring, first export the pending upload package and hand it to the platform.
- After a restore, each company first realigns with the platform: until then it cannot issue offline, and online issuing syncs once before taking a number; once a new license arrives, the device series numbering skips ahead 50 numbers and reports them for voiding automatically, and online and offline issuing resume as usual, so numbers do not clash with invoices issued after the backup. Until the realignment finishes, no invoice can be issued without reaching the platform.
8 No POS system: quick issuing
Small stores without a POS can use the "Issue" page of the desktop program directly:
- Scan product barcodes with a barcode scanner, or search "Products" by code or name; a "Quick product" takes just a description and an amount, with the tax data taken from the default tax group in the settings.
- The shopping list allows changing quantity, line discount and removing lines, with the total computed live.
- Payment supports cash (change computed automatically), debit card, credit card, PIX and other methods; above the state identification threshold the consumer CPF or CNPJ is mandatory.
- After confirming, the result is shown (authorized or offline pending upload) and printed automatically; offline invoices print the number of copies set by the platform.
- Shortcuts:
F2new sale,F4go to payment,F8issue and print,Escback / cancel the sale; the whole page can be operated with the keyboard only.
The "Products" page keeps product code, name, barcode, NCM, CFOP, unit, unit price and tax group; the product tax data has the same structure as itens[].impostos in the issuing request.
The issuing page runs in cashier mode by default, with no PIN; "Require PIN to issue" in "Settings" makes it require the manager PIN. While that is off, anyone on the same computer can issue and see today's invoices; turning it on is recommended for computers shared by several people.
Sale numbers of quick issuing are listed in "Today's invoices" together with the invoices issued by the POS:
- The issuing page generates a sale number in the format
PDV-{yyyyMMdd}-{8 alphanumeric characters}for each sale; a retry of the same sale keeps the original sale number, and the Assistant returns the original invoice without issuing again. - When a request carries no sale number, the Assistant generates one as
PDV-{yyyyMMdd}-{sequence}, skipping sale numbers already taken.
When issuing is rejected, click "Back to sale"; there are two paths depending on the kind of rejection:
- Upload rejected (
Rejeitada): the number is taken; use same-number correction, which needs the manager PIN. - Rejected online or refused by the platform (
Negada/Recusada): the number did not take effect; after fixing, issue it again as a new sale with a new sale number.
"Today's invoices" filters by date and status; each invoice offers "View", "Print", "Cancel" and "Correct" (the last only after an upload rejection); click it to open the invoice details, see Desktop program settings and maintenance.
FAQ
The setup wizard says the pairing code is invalid or expired?
The pairing code is valid for 72 hours and can only be used once. Expired, used or revoked codes cannot be used again; ask the integrator to generate a new pairing code.
Pairing says the certificate CNPJ does not match the company?
The CNPJ of the chosen certificate must match the company. When one computer serves several CNPJs, generate one pairing code per company and pick the matching certificate for each in the setup wizard.
The POS gets 401 from the local interface?
The header must be Authorization: Bearer tfl_…. The token is shown only once; if lost or revoked, the store manager generates a new one under "POS integration".
While offline it says the license expired?
Offline issuing has a time limit, renewed automatically once online. Being offline for too long triggers it; restoring the network is enough.
Offline invoices are never uploaded?
Upload needs the Assistant service running and able to reach the platform. Check the connection status and the "Oldest to upload" time on the Overview page; if the store reaches the internet through a proxy, check the outbound proxy settings (see Desktop program settings and maintenance); you can also run a query from the POS or click "Sync now" in the desktop program.
What about replacing the store computer?
First let the old computer go online and upload all offline invoices ("To upload" at 0 on the Overview page), then have the integrator deactivate the old device and generate a new pairing code for the new computer. Do not copy the data directory to the new computer: the device keys are bound to the machine and will not work there.
If the old computer is broken and there is no time to upload: as long as the Assistant still opens, export the pending upload package in "About & diagnostics" (see Desktop program settings and maintenance) and hand the resulting zip file as is (no need to unzip it) to platform operations, which imports and uploads it on your behalf; the package is already split into folders by device with at most 500 invoices per package, so no further splitting is needed, and it can still be imported after the old device is deactivated.
Locked out after wrong PINs?
Every 5 wrong attempts in total cause a lockout: the first lasts 5 minutes, and each later lockout doubles in length, up to 24 hours. During a lockout even the correct PIN is refused; the wrong attempt count is not reset when the lockout ends, only by entering the PIN correctly once.
What should I send to technical support?
Export the diagnostics package in "About & diagnostics". It contains status and logs, without private keys, tokens, callback secrets or the PIN.
Device status values
situacao | Meaning | Action |
|---|---|---|
Ativo | Can issue | None |
Desativado | Device deactivated by the integrator | Cannot be undone; to keep using the same computer, pair again |
Revogado | Device revoked by the platform | Contact the platform |
EmpresaDesativada | Offline issuing for the company disabled | Contact the platform |
AplicativoBloqueado | POS software blocked by the platform | Contact the platform |
VersaoBloqueada | POS version blocked or below the minimum | Upgrade the Invoice Assistant |
Any value other than Ativo stops new invoices; offline invoices already issued are still uploaded.
Invoice status values
situacaoLocal and status in local interface responses. status uses the cloud values; situacaoLocal keeps the full local status.
situacaoLocal | status | Meaning | Appears in |
|---|---|---|---|
Autorizada | Autorizada | Authorized by SEFAZ, online or after the offline invoice upload | Issue, query |
ContingenciaPendente | ContingenciaPendente | Signed offline on this computer, waiting for upload | Issue, query, correction |
AguardandoAutorizacao | AguardandoAutorizacao | Accepted online, SEFAZ has not answered, and offline signing was not possible at the time; issuing returns HTTP 202 | Issue, query |
Negada | Negada | Online issuing rejected by SEFAZ, including after a pending online result; cannot be corrected with the same number | Issue, query |
Rejeitada | Negada | Offline invoice upload rejected by SEFAZ; correct it with the same number, see Handling rejections | Query, correction |
Recusada | Negada | The platform refused this offline invoice; needs manual handling | Query |
Cancelada | Cancelada | Cancelled, including by substitution | Query |
