NFC-e offline
Tutorial del Asistente Fiscal
Tutorial del Asistente Fiscal: instalar y emparejar el asistente en la computadora Windows de la tienda, emitir con red o sin red desde el PDV con la interfaz local (misma ruta que los endpoints de NFC-e en la nube), recibir los resultados por callback local o consulta periódica, y despliegue, operación, emisión simple y preguntas frecuentes.
TF Fiscal Asistente Fiscal (en adelante, Asistente Fiscal) es un programa que se instala en una computadora Windows de la tienda, formado por un servicio en segundo plano y una interfaz de escritorio. El servicio trae el núcleo de emisión offline y ofrece en el propio equipo una interfaz con la misma ruta y la misma estructura de cuerpo que el endpoint de emisión de NFC-e en la nube (las clases de impuesto requieren conexión); al PDV le basta cambiar la dirección de llamada a la local para emitir en línea y también offline cuando no hay red. Al terminar esta página habrá completado la instalación, la integración y la recepción de resultados. Antes de empezar, el integrador llama Generar código de emparejamiento para esta computadora de caja (formaPermitida en Assistente o Qualquer) y entrega el código de emparejamiento a la tienda.
1 Instalar el asistente y emparejar ──► 2 El PDV emite por la interfaz local ──► 3 Recibir los resultados (callback local o consulta periódica)
1 Instalación y emparejamiento
Preparación
| Ítem | Detalle |
|---|---|
| Computadora | Windows, la misma del PDV; para que un asistente atienda varias cajas vea Modo red local |
| Permisos | La instalación requiere permisos de administrador |
| Instalador | TfFiscalAssistente-{versao}-Setup.exe ({versao} es el número de versión), disponible en la pestaña "Descargas" de la página "Emisión offline → Emisión offline" del menú lateral de la consola (basta con haber iniciado sesión; la tabla muestra el tamaño y el SHA-256 del archivo); si a la computadora le falta el runtime WebView2 se instala solo, y en ese caso hace falta conexión |
| Código de emparejamiento | Lo genera el integrador con Generar código de emparejamiento, con formaPermitida Assistente o Qualquer; sirve como texto o archivo .tfa |
| Certificado | El A1 de la empresa: ya en el almacén de certificados de Windows, o archivo PFX con contraseña |
Tras instalar aparece el acceso directo «Assistente Fiscal» en el menú Inicio «TF Fiscal» y en el escritorio, y el servicio en segundo plano arranca solo con Windows. La interfaz de escritorio es para el gerente y los cajeros: Resumen, Emitir, Notas del día, Detalle de la nota, Productos, Integración con PDV, Configuración y Acerca y diagnóstico. Cerrar la interfaz o que falle no afecta la emisión del servicio.
Para instalar en varias computadoras a la vez, use la instalación silenciosa del MSI, vea Despliegue en lote.
Asistente de instalación
La primera vez que se abre la interfaz de escritorio entra el asistente de instalación, que solo pregunta el código de emparejamiento y el certificado; la dirección de la plataforma, el ambiente, la empresa y la serie del dispositivo vienen del código y del resultado del emparejamiento.
| Paso | Contenido |
|---|---|
| 1 Bienvenida | Elija el idioma de la interfaz, portugués por defecto; los mensajes de error que devuelve la plataforma también usan este idioma, y un cambio posterior en la configuración se aplica de inmediato |
| 2 Código de emparejamiento | Pegue el código, importe el archivo .tfa o léalo con la cámara. El asistente lo verifica primero en el equipo y muestra el ambiente (producción / pruebas), el vencimiento y la serie del dispositivo y el número inicial definidos por el integrador, o que la plataforma los asigna empezando en 1 cuando no se definieron; si el código está limitado a la forma SDK, se detiene en este paso |
| 3 Certificado | Lista los certificados del almacén con CNPJ, vigentes y con clave privada; o importe un PFX. La clave privada importada queda no exportable y la contraseña del PFX no se guarda |
| 4 PIN del gerente | Defina un PIN de gerente de 6 a 8 dígitos, que se usa para cancelar, corregir, administrar tokens, exportar, respaldar, etc. |
| 5 Emparejar | Empareja en línea; si funciona muestra el nombre de la empresa, el CNPJ, el nombre del dispositivo, la serie del dispositivo y el número de la primera nota de este dispositivo; si falla muestra el código de error y qué hacer |
| 6 Listo | Muestra la dirección de la interfaz local y lleva a «Integración con PDV» para generar el token de caja, o directo a «Emitir» |
Emparejamiento
- Si el emparejamiento falla porque no llega a la plataforma, basta con volver a hacer clic en emparejar con el mismo código de emparejamiento; no genere un código nuevo: cada código nuevo ocupa un cupo de dispositivo más.
- Los certificados de la lista con el aviso «El servicio no tiene acceso a la clave» están en el almacén de la máquina y la cuenta del servicio todavía no puede usarlos: ejecute como administrador
scripts\conceder-acesso-chave.ps1 -Thumbprint {thumbprint}({thumbprint}es la huella del certificado), en el directorio de instalación, y haga clic en «Actualizar». - Si la misma computadora atiende varias empresas (varios CNPJ), volver a abrir el asistente de instalación es «Agregar empresa»; pide el PIN del gerente y el flujo es el mismo.
2 Integración del software de caja
Generar el token de caja
El gerente genera el token de caja en la página «Integración con PDV» del programa de escritorio:
- Indique el nombre (por ejemplo
PDV 01), las empresas a las que tiene acceso (al haber varios CNPJ) y, opcionalmente, una dirección de callback. - El token tiene la forma
tfl_seguido de 43 caracteres y solo se muestra al generarlo; si se informó una dirección de callback, se muestra también la clave del callbackwhsec_…, igualmente una sola vez. - El token se revoca en la misma página con un clic, con efecto inmediato.
El token de caja solo llama al asistente de esa computadora: una filtración afecta solo a ese asistente y puede revocarse por separado; la clave de la aplicación del integrador en la nube no necesita ir a la tienda.
El software de caja solo usa la interfaz local que se describe abajo. La interfaz de administración que usa el propio programa de escritorio (rutas que empiezan con /assistente/api/) no está abierta al software de caja: solo acepta origen local, requiere una sesión de gerente o de cajero, y las solicitudes con sesión además deben llevar el token anti-CSRF entregado al iniciar sesión, de modo que otras páginas web u otros programas no pueden falsificarlas.
Dirección y autenticación
| Ítem | Valor |
|---|---|
| Dirección | http://127.0.0.1:8765; en modo red local, la dirección de red local de la computadora del asistente |
| Autenticación | Cabecera Authorization: Bearer tfl_…; sin token / timestamp / sign de la nube |
| Tipo de contenido | Content-Type: application/json |
Lista de rutas
| Método | Ruta | Uso | Equivalente en la nube |
|---|---|---|---|
| POST | /openapi/v2/empresas/{empresaId}/nfce | Emitir | Emitir NFC-e |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId} | Consultar | Consultar NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar | Cancelar | Cancelar NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar-substituicao | Cancelación por sustitución | Cancelación por sustitución |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cupom?formato=ESCPOS_80 | Cupón, incluido el formato PDF | Solo local |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml | Descarga del XML autorizado | Solo local |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml-cancelamento | Descarga del XML de cancelación | Solo local |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/correcao | Corrección con el mismo número tras un rechazo en la transmisión | Solo local |
| GET | /openapi/local/v1/situacao | Estado del asistente | Solo local |
Diferencias con los endpoints en la nube
- Autenticación: con el token de caja, vea Dirección y autenticación.
modoRespostano tiene efecto: el equipo siempre espera el resultado. Si el resultado en línea es incierto, el núcleo abandona ese número y firma offline con el siguiente, y la plataforma resuelve el número original tras revisarlo; solo cuando en ese momento no se puede firmar offline devuelve HTTP 202 conAguardandoAutorizacao. Los demás éxitos devuelven 200.- Las clases de impuesto requieren conexión: los ítems pueden referenciar una clase de impuesto con
classeImposto, que la plataforma expande antes de emitir; sin red o sin acceso a la plataforma, devuelve 400 con10029780, con la indicación de enviarimpostos, sin consumir número. El asistente no guarda clases de impuesto, así que para la contingencia el programa de caja debe guardar losimpostosexpandidos, vea Clases de impuesto y conexión. empresaId: debe ser una empresa emparejada en este asistente y a la que el token tenga acceso; no emparejada devuelve 404 con10029801, sin acceso del token 403 con10029902.- Enlaces del cupón y del XML:
linkDanfeapunta al cupón local (formato HTML);linkDownloadXmlapunta a la ruta local del XML cuando el XML autorizado ya se descargó al equipo, si no esnull. - Campos locales adicionales: además de los campos de la nube, la respuesta trae los de la tabla siguiente.
| Campo | Detalle |
|---|---|
situacaoLocal | Estado local. Tiene dos valores más que status: Rejeitada (nota offline rechazada por la SEFAZ en la transmisión, se puede corregir con el mismo número) y Recusada (rechazada por la plataforma); en estos dos casos status muestra Negada. Si el propio situacaoLocal es Negada, la nota fue rechazada en línea y no admite corrección con el mismo número. Todos los valores en Valores del estado de la nota |
cStat / xMotivo | Código y mensaje de resultado de la SEFAZ. Vienen juntos; son null en notas offline pendientes y en rechazos de la plataforma |
tentativaOnline | Indicador de intento en línea. true significa que primero intentó en línea y, sin resultado claro, pasó a offline; false para notas autorizadas en línea y para notas firmadas offline directamente tras una falla de conexión reciente |
transmitida | Indicador de transmitida. Solo en la consulta |
cancelamentoPendente | Indicador de cancelación pendiente. Solo en la consulta; true para la cancelación pedida antes de autorizar una nota offline |
correcoes | Cantidad de correcciones. Solo en la consulta |
xmlAutorizadoDisponivel | Indicador de XML autorizado disponible. Solo en la consulta; true significa que ya se descargó al equipo |
terminal | Identificación de la caja. Nombre del token de caja que emitió la nota; null en las notas de la emisión simple del programa. Se envía a la plataforma junto con la nota; mismo valor que terminal en la consulta en la nube y en los webhooks |
Formato de las respuestas
| Caso | HTTP | Cuerpo |
|---|---|---|
| Emisión, consulta o corrección exitosa | 200; pendiente en línea 202 | Objeto plano con la misma estructura de la consulta en la nube, más los campos locales |
| Cancelación o cancelación por sustitución aceptada | 200 | Sin cuerpo; el destino viene en la cabecera X-Tffiscal-Cancelamento |
| Descarga exitosa del cupón o del XML | 200 | El archivo original; tipos en Cupón y descarga de XML |
| Error de negocio | 400; nota o empresa inexistente 404; XML no disponible 409; asistente ocupado 429; error interno 500; protección contra downgrade 503 | Array [{codigo, mensagem}], con codigo como cadena numérica del código de error; en la validación de campos, una entrada por campo |
| Fallo de autenticación del token o del origen | 401 / 403 | Sobre de la plataforma {success, errorType, code, message} |
Los ejemplos de error y qué hacer con cada código están en Manejo de errores.
3 Emisión, consulta y transmisión
Emisión con red
El cuerpo es el mismo de la emisión en la nube; los ítems que referencian una clase de impuesto (classeImposto) requieren conexión, vea Diferencias con los endpoints en la nube. Con red, el asistente toma el número de la serie del dispositivo, firma la nota y la entrega a la plataforma, que la envía a la SEFAZ; el resultado es el mismo de la emisión síncrona en la nube. Sin red sigue la misma secuencia para las notas offline, así que los números en línea y offline son continuos, vea Números y serie.
El ejemplo es una venta en la tienda con consumidor no identificado:
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" } }}]}
| Campo | Cómo llenar |
|---|---|
id | Número de la venta en el PDV. Obligatorio, es la clave de idempotencia; al reintentar la misma venta use el mismo id y el asistente devuelve la nota original, sin emitir de nuevo |
ambienteEmissao | Ambiente de emisión. Obligatorio, igual al ambiente con que se emparejó el dispositivo |
pedido, itens | Pedido y productos. Obligatorios, mismas reglas que Emitir NFC-e |
cliente | Consumidor. Opcional, no se envía con consumidor no identificado |
modoResposta | Modo de respuesta. No se envía, el equipo lo ignora |
Con la autorización de la SEFAZ vuelve HTTP 200. Primero vienen todos los campos de la consulta en la nube (aquí se omiten los ecos de pedido e itens) y después los campos locales:
{"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}
Emisión sin red
La solicitud es la misma de la emisión con red. Si no llega a la plataforma, el asistente firma en el equipo la nota de contingencia offline y devuelve HTTP 200 con 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"}
seriees la serie de este dispositivo, compartida con sus notas en línea y con numeración continua, distinta de la serie del perfil de la empresa que usa la emisión en la nube; el dígito 35 de la clave de acceso es 9.- No hay
protocolo: imprima el cupón y entréguelo al consumidor. Obtenga los bytes ESC/POS con la ruta del cupón y envíelos a la impresora; el cupón ya lleva la marca de contingencia offline y la cantidad de copias que configura la plataforma. tentativaOnline=truesignifica que primero intentó en línea con resultado incierto; esta nota usa el número siguiente al del intento en línea, y la plataforma resuelve ese número original tras revisarlo; si la última conexión acababa de fallar y firmó offline directamente, esfalse.- Al volver la red se transmite sola; las reglas de transmisión están en Notas offline y transmisión. El servidor del integrador recibe
nfce.contingency_issuedy luegonfce.authorized, vea Cómo llegan los resultados; el PDV se entera del resultado por el callback local o por la consulta.
Consulta y resultado de la transmisión
Consulte la nota con el id usado al emitir:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Tras la transmisión y la autorización:
{"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"}
emitidaEmContingenciasigue entruetras la autorización.- El asistente descarga solo el XML autorizado después de la transmisión; aunque
xmlAutorizadoDisponivelseafalse, se puede llamar directamente la ruta del XML y el asistente lo recupera de la plataforma, vea Cupón y descarga de XML.
4 Recibir los resultados
El PDV tiene dos formas de obtener los resultados posteriores, como transmisión y cancelación: configurar el callback local para que el asistente los envíe, o hacer una consulta periódica. Se pueden usar las dos a la vez.
Consulta periódica
Si no quiere recibir callbacks, el PDV llama periódicamente la consulta para las notas con estado aún no definido (ContingenciaPendente, AguardandoAutorizacao o situacaoLocal en Rejeitada), por ejemplo una vez por minuto, hasta que el estado quede definido; cuando pendentesTransmissao de GET /openapi/local/v1/situacao es 0, todas las notas offline ya se transmitieron.
Callback local
Si se informó una dirección de callback al generar el token de caja, el asistente envía al PDV los resultados de las notas de ese asistente. Las cabeceras, el algoritmo de firma y la estructura del payload son los mismos del webhook en la nube, así que puede reutilizar el código de verificación de la nube; solo cambia la clave: use la clave del callback whsec_… completa que se mostró al generar el token, y no el app_secret del integrador.
Eventos
Cabecera X-Tffiscal-Event | Disparo | nfeStatus |
|---|---|---|
nfce.contingency_issued | Nota firmada offline en el equipo | ContingenciaPendente |
nfce.authorized | Autorizada tras la transmisión, tras una corrección o tras quedar pendiente en línea | Autorizada |
nfce.rejected | Nota offline rechazada por la SEFAZ en la transmisión, o nota pendiente en línea rechazada después por la SEFAZ | Negada, nfeMotivoStatus con código y motivo |
nfce.canceled | Cancelación exitosa, incluida la cancelación por sustitución | Cancelada |
nfce.cancel_rejected | Cancelación rechazada | CancelamentoNegado |
nfce.intake_rejected | Solo local: la plataforma rechazó esta nota offline | Recusada, nfeMotivoStatus con código de error de la plataforma y motivo; contacte a la plataforma |
nfce.device.deactivated | Solo local: dispositivo desactivado o revocado | Payload en Payload |
El payload de nfce.rejected no distingue los dos tipos de rechazo: al recibirlo, consulte la nota y actúe según situacaoLocal. Rejeitada es un rechazo en la transmisión y sigue la corrección con el mismo número; Negada es un rechazo en línea, no admite corrección con el mismo número: corrija y emita de nuevo con un id nuevo.
Los avisos de operación (licencia, certificado, estado de conexión, declaración de números no utilizados) no se envían al PDV; los muestra la página Resumen del programa de escritorio.
Cabeceras y verificación de la firma
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}es la dirección de callback indicada al generar el token.- La firma es
hex(HMAC-SHA256(clave del callback, timestamp + "." + cuerpo original)), 64 caracteres hexadecimales en minúscula, calculada sobre los bytes originales recibidos. - Deduplique por
X-Tffiscal-Event-Id: no cambia en reintentos ni reenvíos.
Pruebe la verificación de la firma con este vector fijo:
| Entrada | Valor |
|---|---|
| Clave del callback | whsec_testsecret |
X-Tffiscal-Timestamp | 1762790400 |
| Cuerpo | {"tipo":"NFC-e","nfeId":"PDV-1"} |
| Firma esperada | 415bce74a6740037c540f3839e69a08bd3026c8337dd49c73e8a4877889de0a4 |
Payload
Los eventos de nota tienen los mismos campos, en el mismo orden, que el callback de NFC-e en la nube, con dispositivoId al final. El equipo no tiene los enlaces de archivos de la nube: nfeLinkDanfe y nfeLinkXml siempre son null; obtenga el cupón con la ruta local del cupón:
{"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 del evento de dispositivo desactivado nfce.device.deactivated:
{"tipo": "NFC-e","empresaId": "1934811222334455","dispositivoId": "1900000000000000001","situacao": "Desativado","motivo": "Caixa substituido","ocorridoEm": "2026-11-20T18:00:00Z"}
situacao es Desativado (desactivado por el integrador), Revogado (revocado por la plataforma), EmpresaDesativada (emisión offline de la empresa desactivada por la plataforma), AplicativoBloqueado (software de caja bloqueado por la plataforma) o VersaoBloqueada (versión del PDV bloqueada o por debajo de la mínima); vea Valores del estado del dispositivo.
Reintentos
- Cualquier 2xx cuenta como entregado; un código no 2xx, un fallo de conexión o la falta de respuesta en 5 segundos cuentan como fallo.
- Tras un fallo reintenta a los 10 segundos, 30 segundos, 2 minutos, 10 minutos y 30 minutos, y luego una vez por hora; si a las 24 horas desde que entró en cola no se entregó, se detiene.
- En la página «Integración con PDV» se ve el historial de entregas (guardado 7 días) y se puede reenviar a mano.
- Un fallo del callback no afecta la emisión ni la transmisión.
5 Operaciones comunes
| Operación | Cómo se hace | Detalle |
|---|---|---|
| Tratar una nota rechazada | Según situacaoLocal: Rejeitada se corrige con el mismo número; Negada / Recusada se emite de nuevo con un id nuevo | Qué hacer tras un rechazo |
| Imprimir el cupón, descargar el XML | GET …/cupom?formato=…, GET …/xml, GET …/xml-cancelamento | Cupón y descarga de XML |
| Cancelar una nota | POST …/cancelar y leer la cabecera X-Tffiscal-Cancelamento | Cancelación |
| Se emitieron dos notas para la misma venta | POST …/cancelar-substituicao: cancela la nota original en línea y la vincula a la nota offline sustituta | Cancelación por sustitución |
| Mostrar en la caja que está sin conexión o con notas por transmitir | GET /openapi/local/v1/situacao | Estado del asistente |
| Tratar errores | Según el estado HTTP y el código de error | Manejo de errores |
Qué hacer tras un rechazo
Toda nota rechazada tiene status Negada; el tratamiento depende de situacaoLocal:
situacaoLocal | Significado | Qué hacer |
|---|---|---|
Rejeitada | Nota offline rechazada por la SEFAZ en la transmisión. La nota ya se entregó al consumidor y el número está ocupado | Corrija con el mismo número y reenvíe; no se puede emitir otra, vea abajo |
Negada | Rechazada en línea por la SEFAZ, incluido el rechazo tras quedar pendiente en línea. La plataforma inutiliza el número; no se reutiliza | Corrija la solicitud y emita de nuevo con un id nuevo |
Recusada | La plataforma rechazó esta nota offline. El número no tuvo efecto | Contacte a la plataforma para investigar la causa; tras corregir, emita de nuevo con un id nuevo |
Enviar una solicitud de emisión con contenido modificado y el id original devuelve 400 con 10029818.
Ejemplo de consulta de una nota rechazada en la transmisión (omite los campos iguales a Consulta y resultado de la transmisión):
{"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}
Para la corrección con el mismo número, envíe la solicitud de emisión completa ya corregida, con el mismo id de la original. En el ejemplo, ... indica contenido igual al de la solicitud original; solo cambia el ncm de la línea de producto:
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", "...": "..." } ] }
- Solo se puede cambiar lo que no afecta valores ni impuestos, como el NCM o el CFOP del producto o el documento del consumidor; número, serie, clave de acceso y fecha de emisión no cambian.
- Si cambia el total o el impuesto de cualquier línea devuelve 400 con
10029821; si el estado actual no esRejeitada,10029820. - Si funciona devuelve HTTP 200 con la misma estructura de la respuesta de Emisión sin red,
situacaoLocalvuelve aContingenciaPendentey espera una nueva transmisión.
Cupón y descarga de XML
Al pedir el cupón, elija el formato con 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 | Tipo de respuesta | Uso |
|---|---|---|
ESCPOS_80 (por defecto) | application/octet-stream | Impresora térmica de 80 mm; los bytes van directo a la impresora |
ESCPOS_58 | application/octet-stream | Impresora térmica de 58 mm |
TEXTO | text/plain; charset=utf-8 | Texto plano |
HTML | text/html; charset=utf-8 | Vista en pantalla o impresión desde el navegador |
PDF_80 | application/pdf | PDF en rollo de 80 mm, una página por copia; para archivar o enviar al consumidor |
La cantidad de copias del cupón de la nota offline la configura la plataforma y ya viene compuesta en el contenido; imprímalo tal cual. La interfaz local genera el cupón con los parámetros de impresión por defecto, sin que la afecten los parámetros del cupón del programa de escritorio (vea Configuración y mantenimiento del programa de escritorio); el software de caja lo adapta a su propia impresora.
Descarga del XML autorizado:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
| Ruta | Devuelve | Si no está disponible |
|---|---|---|
GET …/xml | XML autorizado original, application/xml; charset=utf-8 | Aún no autorizada, o no está en el equipo y no se pudo recuperar de la plataforma: 409 con 10029841 |
GET …/xml-cancelamento | XML de cancelación original, application/xml; charset=utf-8 | Aún no cancelada, o no está en el equipo y no se pudo recuperar de la plataforma: 409 con 10029843 |
- Si la nota ya está autorizada (o cancelada) pero el XML correspondiente no está en el equipo, el asistente lo recupera de la plataforma en el momento y luego responde, en hasta unos 30 segundos; quien llama no debe usar un tiempo de espera demasiado corto.
- Hay como máximo 3 recuperaciones simultáneas; por encima devuelve 429 con
10029918; reintente más tarde.
Cancelación
Basta con enviar el motivo de la cancelación:
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 es obligatoria, de 15 a 255 caracteres. Al aceptarla devuelve HTTP 200 sin cuerpo y la cabecera X-Tffiscal-Cancelamento indica el destino:
| Valor | Significado |
|---|---|
Solicitado | Enviada a la plataforma; el resultado llega por callback o consulta |
Agendado | La nota offline ya se transmitió, pero aún no está autorizada; la cancelación queda en espera en la plataforma y la plataforma la envía sola en el momento de la autorización |
EnfileiradoLocal | Cola local: sin red, o la nota offline / sustituta aún no se transmitió; se envía en la misma ronda justo después de la transmisión |
El plazo de cancelación es el mismo de la nube, vea Cancelar NFC-e; si el estado actual no permite cancelar devuelve 400 con 10029822.
Cancelación por sustitución
Se usa cuando se emitieron dos notas para la misma venta: por ejemplo, PDV01-000130 se emitió en línea, el software de caja no recibió el resultado y lo tomó como fallo, y sin red emitió en este dispositivo la nota offline PDV01-000131 para la misma venta, de modo que las dos son válidas. La cancelación por sustitución cancela la nota original emitida en línea y la vincula a la nota offline que la sustituye:
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"}
| Campo | Cómo llenar |
|---|---|
nfceId (ruta) | Número de la nota original. La nota emitida en línea que se va a cancelar |
chaveAcessoSubstituta | Clave de acceso de la nota sustituta. Obligatoria, 44 dígitos, de la nota offline que sustituye a la original |
justificativa | Motivo de la cancelación. Obligatorio, mismas reglas que la cancelación por sustitución en la nube |
Requisitos:
- La nota original es una nota normal emitida en línea y autorizada; una nota offline, ya cancelada o con una cancelación pendiente devuelve 400 con
10029822. - La nota sustituta es una nota offline emitida por este dispositivo y esta empresa y no rechazada por la plataforma; si la clave no tiene 44 dígitos, el modelo no es 65, el dígito verificador está mal, el CNPJ difiere del de la original o es igual a la clave original, devuelve 400 con
10029845. - Sin
chaveAcessoSubstitutadevuelve 400 con10029909.
Al aceptarla devuelve HTTP 200 sin cuerpo:
HTTP/1.1 200 OKX-Tffiscal-Cancelamento: EnfileiradoLocal
- Los valores de la cabecera son los mismos de Cancelación. Si la nota sustituta aún no se transmitió o no hay red ahora, es
EnfileiradoLocal: la cancelación queda en cola en el equipo y solo se envía después de transmitir con éxito la nota sustituta. - El resultado llega por los callbacks
nfce.canceledonfce.cancel_rejected, o consultando la nota original. El plazo es el mismo de la nube.
Estado del asistente
GET /openapi/local/v1/situacao devuelve el estado de las empresas a las que el token tiene acceso; sirve para mostrar en la caja avisos como «sin conexión» o «N notas por transmitir»:
{"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": []}
| Campo | Detalle |
|---|---|
versaoNucleo | Versión del núcleo |
empresaId / dispositivoId | Identificador de la empresa e identificador del dispositivo |
situacao | Estado del dispositivo. Valores en Valores del estado del dispositivo |
conectado | Indicador de conexión con la plataforma. true significa que en este momento llega a la plataforma |
ultimoContato | Último contacto. Momento de la última conexión exitosa con la plataforma |
licencaExpiraEm | Vencimiento de la licencia |
offlineAte | Plazo offline. Pasado ese momento ya no se puede emitir offline |
pendentesTransmissao | Notas por transmitir |
pendenteMaisAntigaEm | Pendiente más antigua. Fecha de emisión de la nota por transmitir más antigua |
prazoTransmissaoAte | Plazo de transmisión. Límite de transmisión de la nota pendiente más antigua; pasado ese momento el dispositivo no puede seguir emitiendo offline |
certificadoValidoAte | Vencimiento del certificado |
ultimoErro | Último error. Descripción del último error; null si no hay |
numerosNaoUtilizadosPendentes | Rangos no utilizados por declarar. Cantidad de rangos de números no utilizados pendientes de declarar como inutilizados ante la plataforma; si es mayor que 0 y no baja durante mucho tiempo, contacte a la plataforma para verificarlo |
restauradoPendenteSincronizacao | Restauración pendiente de alineación. true tras restaurar una copia de seguridad y hasta recibir una licencia nueva; mientras tanto la emisión offline se rechaza y la en línea sincroniza antes con la plataforma; false tras la alineación |
avisos | Avisos de funcionamiento. Problemas del entorno de ejecución que requieren atención técnica; el texto está en portugués y, si no hay, es un arreglo vacío; también se muestran en la parte superior de la página de resumen del programa de escritorio. Por ejemplo, se configuró autenticación en el proxy pero los parámetros de inicio del servicio del asistente no son correctos y la autenticación del proxy puede no funcionar; en ese caso basta con reinstalar el asistente |
Manejo de errores
Los errores de negocio son un array:
[{ "codigo": "10029817", "mensagem": "itens: obrigatório" },{ "codigo": "10029817", "mensagem": "pedido.pagamento: obrigatório" }]
Falta de token (HTTP 401), en sobre de la plataforma:
{ "success": false, "errorType": 1, "code": 10029900, "message": "Token de caixa ausente (Authorization: Bearer tfl_...)" }
| HTTP | Código | Caso | Qué hacer |
|---|---|---|---|
| 401 | 10029900 / 10029901 | Falta el token / token inválido o revocado | Revise la cabecera Authorization; si el token fue revocado, el gerente genera otro |
| 403 | 10029902 | El token no tiene acceso a esa empresa | El gerente genera en «Integración con PDV» un token que incluya esa empresa |
| 403 | 10029903 | Dirección de origen fuera de la red permitida del modo red local | Revise la configuración del modo red local |
| 404 | 10029801 | La empresa no está emparejada en este asistente | Revise el empresaId, o agregue la empresa en el asistente de instalación |
| 404 | 10029819 | La nota no existe en este equipo | Revise el nfceId |
| 400 | 10029817 | Validación de la solicitud fallida, una entrada por campo, incluido campo obligatorio ausente y campo que no existe en el contrato (nunca se ignora en silencio) | Corrija según mensagem |
| 400 | 10029780 | Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún número | Reenvíe cuando vuelva la red; sin red, envíe impostos en los ítems |
| 400 | 10029909 | Solicitud inválida, por ejemplo una cancelación por sustitución sin la clave de la nota sustituta | Corrija según mensagem |
| 400 | 10029818 | El mismo id ya se usó para una nota con contenido distinto | Venta nueva, id nuevo; para reintentar use la solicitud original; tras un rechazo vea Qué hacer tras un rechazo |
| 400 | 10029820 / 10029821 | El estado actual no permite corregir / la corrección cambió valores o impuestos | Solo Rejeitada admite corrección, y solo de lo que no afecta valores |
| 400 | 10029822 | El estado actual no permite cancelar (incluso cuando el estado local aún no se sincronizó y la plataforma lo rechaza); en la cancelación por sustitución, la nota original no es una nota normal emitida en línea | No reintente |
| 400 | 10029845 | Clave de la nota sustituta inválida, o no es una nota offline no rechazada de este dispositivo y esta empresa | Revise la clave de la nota sustituta |
| 400 | 10029804 / 10029807 | Sin red y licencia vencida / pasó el plazo offline | Restablezca la red; tras renovar vuelve solo |
| 400 | 10029808 | La serie del dispositivo llegó al número 999999999 | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
| 400 | 10029810 | La nota pendiente más antigua superó el plazo de transmisión | Restablezca la red para transmitir |
| 400 | 10029811 | La empresa o el estado no permite offline | Solo se puede emitir en línea |
| 400 | 10029816 | Dispositivo desactivado | Contacte al integrador |
| 400 | 10029424 | La plataforma informa el número como ya usado; el núcleo lo descartó, reintentó una vez y el conflicto sigue | Exporte el paquete de diagnóstico y contacte a la plataforma |
| 400 | 10029426 | El mismo id ya tiene una nota no rechazada en la plataforma, por ejemplo emitida por la API en la nube | Verifique la nota original; use un id nuevo para una venta nueva |
| 409 | 10029841 | XML autorizado no disponible | Pídalo de nuevo tras la autorización; si no se pudo recuperar, reintente más tarde |
| 409 | 10029843 | XML de cancelación no disponible | Pídalo de nuevo tras la cancelación exitosa; si no se pudo recuperar, reintente más tarde |
| 429 | 10029918 | Límite de recuperaciones simultáneas de XML alcanzado | Reintente más tarde |
| 500 | 10029912 / 10029836 | Error interno del asistente o del núcleo | Exporte el paquete de diagnóstico en «Acerca y diagnóstico» y contacte al soporte técnico |
| 503 | 10029842 | Protección contra downgrade: el directorio de datos fue usado por una versión más reciente | Instale un instalador de versión no inferior a la indicada, sin borrar el directorio de datos; vea Protección contra downgrade |
La lista completa está en Códigos de error. Los códigos de error de la plataforma y de la SEFAZ llegan tal cual.
6 Checklist antes de producción
Instalación y emparejamiento:
- El código de emparejamiento tiene
formaPermitidaenAssistenteoQualquer; vale 72 horas y una sola vez. - El CNPJ del certificado elegido coincide con el de la empresa; si el certificado está en el almacén, la cuenta del servicio ya tiene acceso a la clave privada.
- El PIN del gerente está definido y lo guarda el gerente; en computadoras compartidas se recomienda activar «Exigir PIN para emitir» en «Configuración».
Integración del software de caja:
- Cada caja tiene su propio token de caja, y el token y la clave del callback se guardaron bien al generarlos (solo se muestran una vez).
- La dirección de la interfaz es
http://127.0.0.1:8765o, en modo red local, la dirección de red local de la computadora del asistente; cada solicitud llevaAuthorization: Bearer tfl_…. - Cada venta usa un
idúnico y el reintento de la misma venta usa el mismoid;ambienteEmissaoes igual al ambiente con que se emparejó el dispositivo. - El PDV trata HTTP 202 con
AguardandoAutorizacao,ContingenciaPendentey los tres tipos de rechazo segúnsituacaoLocal, vea Qué hacer tras un rechazo. - Cuando vuelve una nota offline, el cupón se imprime enseguida y se entrega al consumidor, tal cual.
- El tiempo de espera de la descarga de XML no es menor a unos 30 segundos; ante 429 con
10029918se reintenta más tarde.
Recepción de resultados:
- Con callback local: verificar la firma con la clave del callback
whsec_…, deduplicar porX-Tffiscal-Event-Idy responder 2xx en menos de 5 segundos. - Sin callback: consultar periódicamente las notas con estado aún no definido hasta que quede definido.
- La caja puede llamar
GET /openapi/local/v1/situacaopara mostrar las notas por transmitir y vigilarprazoTransmissaoAteyavisos.
Entorno de ejecución:
- Si la tienda sale a internet por un proxy, el proxy de salida está configurado en «Configuración».
- En modo red local, un administrador ya ejecutó el script que abre el firewall.
- El gerente sabe que el directorio de datos
%ProgramData%\TFFiscal\Assistente\contiene los originales legales de las notas offline no transmitidas, que no se deben borrar ni copiar a otra computadora; cuando haga falta, use «Exportar paquete de pendientes» y «Copia de seguridad».
7 Despliegue y operación
Despliegue en lote
Para varias computadoras se puede instalar el MSI en modo silencioso y emparejar en el mismo paso; si el emparejamiento falla, la instalación se revierte. La contraseña del PFX y el PIN del gerente no van en la línea de comandos (cualquier usuario del mismo equipo puede verla en la lista de procesos), sino antes en un archivo de secretos.
Paso 1: un administrador genera el archivo de secretos en un PowerShell con privilegios elevados. El script pide el PIN y la contraseña del PFX con entrada segura; si el certificado es uno ya presente en el almacén, agregue -SemPfx y solo pedirá el PIN:
& "C:\Program Files\TFFiscal\Assistente\scripts\preparar-segredos.ps1"
- El archivo de secretos se genera siempre en el directorio protegido
%ProgramData%\TFFiscal\deploy, con el nombre predeterminadosegredos.json, es decir,C:\ProgramData\TFFiscal\deploy\segredos.json; para usar otro nombre de archivo use-Nome. - El script primero crea o restringe ese directorio, con acceso solo para SYSTEM y Administrators, y luego crea el archivo directamente con permisos restringidos. El contenido del archivo es un JSON UTF-8
{"pin":"…","pfxSenha":"…"}. - Al emparejar se verifican el propietario y los permisos de acceso del archivo de secretos y de su directorio, y si no cumplen el emparejamiento falla: el archivo de secretos debe quedarse en ese directorio; si se copia a otro (por ejemplo
C:\deploy), se rechaza. - El archivo de secretos se sobrescribe y se borra apenas se lee, tenga éxito o no el emparejamiento, así que hay que generarlo de nuevo cada vez que se repite la instalación.
Paso 2: instalación silenciosa:
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"
| Propiedad | Obligatoria | Detalle |
|---|---|---|
TFA_FILE | Para emparejar | Ruta del archivo del código de emparejamiento. Sin ella es una instalación normal y el gerente sigue después el asistente de instalación |
PFX_FILE | Una de esta fila o la siguiente | Ruta del archivo del certificado PFX. La contraseña sale de pfxSenha del archivo de secretos |
CERT_THUMBPRINT | Una de esta fila o la anterior | Huella de un certificado existente. Admite CERT_STORE, por defecto LOCAL_MACHINE; antes debe ejecutarse el script de acceso a la clave privada |
SECRETS_FILE | Para emparejar | Ruta del archivo de secretos. Debe estar en %ProgramData%\TFFiscal\deploy; contiene pin (de 6 a 8 dígitos) y, si se usa PFX, también pfxSenha |
- Las propiedades antiguas
PFX_PASSWORDyADMIN_PINya no se admiten; si se envían, la instalación falla. - La instalación silenciosa requiere que la computadora ya tenga el runtime WebView2.
- Si el emparejamiento falla porque no llega a la plataforma, basta con ejecutar otra vez la instalación con los mismos parámetros (generando de nuevo el archivo de secretos); no cambie el código de emparejamiento.
El emparejamiento silencioso tiene dos casos, según la computadora ya haya completado la instalación o no; vale tanto para la instalación silenciosa del MSI como para el comando de emparejamiento de abajo:
| Caso | Cuándo ocurre | Qué hace el emparejamiento | pin del archivo de secretos |
|---|---|---|---|
| Primera instalación | La computadora todavía no completó ninguna instalación | Empareja directamente; el pin pasa a ser el PIN del gerente | El nuevo PIN del gerente, de 6 a 8 dígitos |
| Agregar empresa ya instalada | Se ejecuta con la instalación ya completada: reinstalación después de desinstalar (el directorio de datos se conserva), instalación de una versión nueva encima, o el comando de emparejamiento en una computadora ya instalada | Primero inicia la sesión del gerente con el pin y luego empareja, es decir, agrega una empresa; las empresas ya emparejadas no se ven afectadas | Debe ser el PIN del gerente actual; si es incorrecto, el código de salida es 1 y el PIN del gerente no cambia |
En los dos casos, si se usa un certificado PFX el archivo de secretos también debe contener pfxSenha. «Reparar» o «Cambiar» el MSI de la misma versión no dispara el emparejamiento silencioso; para agregar una empresa en una computadora ya instalada, use directamente el comando de emparejamiento de abajo.
En una computadora con el asistente ya instalado, un administrador también puede ejecutar directamente el comando de emparejamiento (el servicio debe estar en ejecución):
"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
- Para usar un certificado del almacén, cambie
--pfxpor--thumbprint {thumbprint}y, si quiere, agregue--store LOCAL_MACHINEo--store CURRENT_USER. --segredos -lee el JSON de secretos de la entrada estándar, sin escribirlo en disco.- Ejecutado en una computadora con la instalación completada, agrega una empresa, y el
pindel archivo de secretos debe ser el PIN del gerente actual; también se puede agregar con el asistente de instalación del programa de escritorio.
| Código de salida | Significado | Qué hace el script de despliegue |
|---|---|---|
0 | Emparejamiento exitoso | Nada |
1 | Emparejamiento rechazado | Actúe según el código de error de la salida estándar |
2 | Parámetros incorrectos, archivo de secretos inválido o servicio inaccesible | Corrija los parámetros y el archivo de secretos y vuelva a ejecutar |
3 | Se puede reintentar con el mismo código de emparejamiento | Vuelva a ejecutar el mismo comando tal cual, sin cambiar el código de emparejamiento |
Actualización, desinstalación y directorio de datos
- Actualización: instale la versión nueva encima; los datos locales se conservan.
- Directorio de datos:
%ProgramData%\TFFiscal\Assistente\. Antes de la transmisión, los archivos firmados de las notas offline solo existen aquí y son el único original legal; al desinstalar el directorio de datos se conserva: no lo borre a mano ni lo copie para usarlo en otra computadora. - Cuando el certificado se renueve, use «Cambiar certificado» en «Configuración» con el PIN del gerente; la identidad del dispositivo no cambia.
- Si la versión mínima exigida por la plataforma es superior a la del equipo, la página Resumen avisa que hay que actualizar; hasta actualizar, el estado del dispositivo es
VersaoBloqueaday no se pueden emitir notas nuevas.
Protección contra downgrade
Si una versión más reciente del asistente ya usó el directorio de datos y luego se reinstala una versión anterior, la versión anterior no arranca el núcleo de emisión, para no dañar los datos locales. En ese caso el asistente entra en modo de fallo de arranque:
- El servicio en segundo plano no se cierra y solo escucha en la dirección de loopback del equipo; reiniciar la computadora o el servicio no lo resuelve.
- La interfaz de escritorio muestra una página de bloqueo con la versión mínima que debe instalarse y la versión actual.
- Todas las rutas de la interfaz local devuelven HTTP 503:
[ { "codigo": "10029842", "mensagem": "… Instale o Assistente Fiscal na versão 1.4.0 ou superior …" } ]
Qué hacer: instale un instalador de versión no inferior a la indicada. Nunca borre el directorio de datos: puede contener notas offline aún no transmitidas.
Modo red local
Para que un asistente atienda varias cajas de la misma tienda, el gerente activa el modo red local en «Configuración»:
- Activado, el asistente escucha en todas las tarjetas de red del equipo y solo acepta orígenes dentro de las «Redes permitidas» (por defecto, la red /24 del equipo); fuera de ellas devuelve 403 con
10029903. - El instalador no abre el firewall: un administrador debe ejecutar
scripts\abrir-firewall-rede-local.ps1 -RedesPermitidas {redesPermitidas}, en el directorio de instalación;{redesPermitidas}son las redes permitidas, por ejemplo192.168.0.0/24. - Esté o no activado, cada solicitud debe llevar el token de caja.
- Con el modo red local desactivado, la dirección de callback solo puede ser de loopback del propio equipo; solo activado admite direcciones de la red local.
Varias cajas en la misma tienda
Cuando la tienda tiene varias cajas, instale un único Asistente Fiscal para toda la tienda, en una computadora de la oficina o en una de las cajas; las demás cajas lo llaman por la red local:
- Instale y empareje un asistente: complete el asistente de instalación como en Instalación y emparejamiento. Toda la tienda usa un código de emparejamiento y ocupa un cupo de dispositivo.
- Active el modo red local: el gerente lo activa en «Configuración» en la computadora del asistente. Viene desactivado, y entonces el asistente solo escucha en la propia computadora y las demás computadoras de la red no pueden conectarse; activado, escucha en todas las tarjetas de red y solo acepta orígenes de las redes permitidas, por defecto la red /24 de la computadora del asistente. Firewall y redes permitidas en Modo red local.
- Un token de caja por caja: en la página «Integración con PDV» el gerente genera un token para cada caja (empieza con
tfl_), con el nombre de la caja, por ejemploPDV 01,PDV 02; ese nombre es la identificación de la cajaterminalen las notas que emite, presente en las respuestas de la interfaz local, en la consulta en la nube y en los webhooks. Para recibir callbacks, la dirección de callback es la dirección de red local de esa caja. Si una caja se pierde o se retira, revoque solo su token; las demás cajas no se ven afectadas. - Apunte el software de PDV a la dirección de red del asistente: cambie la dirección de la interfaz de
http://127.0.0.1:8765por la dirección de red local de la computadora del asistente, por ejemplohttp://192.168.0.10:8765, con el token de esa caja en la cabecera. La interfaz y las llamadas son las mismas que en una instalación en una sola computadora, vea Lista de rutas.
Resultado:
- Toda la tienda comparte la serie de este único dispositivo; las notas de todas las cajas tienen numeración continua, tomada en orden por el asistente, sin choques.
- Sin internet pero con la red local funcionando, todas las cajas siguen emitiendo: el asistente firma offline y transmite solo cuando vuelve la conexión.
- El programa de escritorio (PIN de gerente, emisión simple, exportación y copia de seguridad, etc.) solo se abre en la propia computadora del asistente; las demás cajas solo usan la interfaz local.
Precauciones:
- La computadora del asistente es un punto único de falla: apagada, sin energía o fuera de la red, ninguna caja emite, y las notas offline ya emitidas esperan a que vuelva para transmitirse. Manténgala siempre encendida; se recomienda un UPS.
- La red local debe funcionar: si falla la red o el switch entre una caja y la computadora del asistente, esa caja no llega al asistente y no emite.
- Alternativa de respaldo: instale otro asistente en una segunda computadora y emparéjelo con un código de emparejamiento nuevo. Es otro dispositivo, con serie y numeración propias, y necesita tokens de caja propios. Si la computadora principal falla, el software de PDV pasa a la dirección y los tokens del respaldo y sigue emitiendo; las notas ya emitidas en la principal se siguen consultando y transmitiendo en ella y, si no tiene arreglo, exporte el paquete de pendientes como se indica en «Exportación y copia de seguridad» de Configuración y mantenimiento del programa de escritorio y entréguelo a la plataforma.
Comparación con el SDK embebido: con el SDK embebido cada caja se empareja por defecto como un dispositivo, con serie propia, numeración continua dentro de cada serie e independiente de las demás. La normativa solo exige numeración continua dentro de una misma serie, así que varias series en la misma tienda son igualmente regulares. El SDK no tiene punto único de falla, pero cada caja necesita el certificado y ocupa un cupo de dispositivo. El SDK también puede compartir una sola serie en toda la tienda con el modo principal y secundario, vea Varias cajas (modo principal y secundario).
Configuración y mantenimiento del programa de escritorio
Todas las funciones siguientes se usan en el programa de escritorio, en la propia computadora del asistente.
Detalle de la nota
La página de detalle de la nota muestra la nota, el código QR y la línea de tiempo del estado (firma offline, transmisión, autorización o rechazo, corrección), y ofrece:
- «Descargar XML» (XML autorizado) y «XML de la anulación». Si no están en el equipo, el asistente los recupera de la plataforma en hasta unos 30 segundos; espere a que termine de cargar y no haga clic repetidas veces.
- «Cupón en PDF» y «Descargar imagen» del código QR.
- Cancelación por sustitución: aparece cuando la nota original es una nota normal emitida en línea y autorizada, y requiere el PIN del gerente; la nota sustituta se elige entre las notas offline del día, con las reglas de Cancelación por sustitución.
Proxy de salida
Si la red de la tienda solo sale a internet por un proxy, el gerente lo configura en el proxy de salida de «Configuración»; el asistente lo usa para conectarse a la plataforma y a la SEFAZ:
| Ítem | Detalle |
|---|---|
| Conexión a internet | Directa (por defecto), Proxy manual o Proxy de Windows. El Proxy de Windows usa la configuración de proxy de Windows; no admite scripts de configuración automática PAC, y en ese caso se conecta directo |
| Dirección | Dirección del servidor proxy. Formato host:puerto, obligatoria en modo manual; sin puerto se usa 8080 |
| Usuario | Usuario de autenticación del proxy. Vacío significa sin autenticación y además borra la contraseña guardada |
| Contraseña | Contraseña de autenticación del proxy. Solo escritura: no se vuelve a mostrar tras guardarla, y vacía significa no cambiarla; se guarda cifrada y no entra en los registros ni en el paquete de diagnóstico |
| No usar proxy para | Hosts que no pasan por el proxy. Separados por ;, admite *.dominio y <local> |
- Al guardar, el asistente reinicia el núcleo de emisión con el nuevo proxy para que tenga efecto, lo que tarda unos segundos; las solicitudes de emisión que lleguen en ese tiempo quedan en cola y no se pierden; si el núcleo no arranca con el nuevo proxy, vuelve solo a la configuración anterior.
- Si cambió el modo, la dirección o el usuario, hay que volver a ingresar la contraseña.
- Si la configuración es inválida, la interfaz lo avisa con el código de error
10029919y la configuración no cambia. - Si hay una exportación, una copia de seguridad o una descarga de XML en curso que no termina en 15 segundos, muestra el código de error
10029920, la configuración no cambia y hay que volver a guardar cuando terminen esas operaciones.
Cupón impreso
La sección «Cupón impreso» de «Configuración» solo se aplica a los cupones que imprime el propio asistente (emisión simple, reimpresión, vista previa del detalle) y no afecta el cupón que el software de caja obtiene por la interfaz local:
| Ítem | Valores |
|---|---|
| Columnas por línea | 48, 42, 32, o según el ancho del papel por defecto |
| Página de códigos de la impresora | CP1252 (por defecto), CP860, CP850, CP437; los caracteres que no existen en la página de códigos se imprimen sin acento |
| Código QR | Comando de la impresora: usa el comando de código QR de la impresora (por defecto); Imagen: lo imprime como mapa de bits, para impresoras antiguas que no reconocen el comando de código QR |
| Cortar el papel después de imprimir | Si se corta el papel tras imprimir |
| Copias | Copias por impresión, o según la regla del estado; la nota offline usa la cantidad de copias que configura la plataforma |
Exportación y copia de seguridad
La página «Acerca y diagnóstico» ofrece tres descargas y la restauración desde una copia de seguridad, todas con PIN del gerente; los archivos descargados se guardan en la ubicación del equipo que elija el gerente. Solo puede haber una exportación o copia de seguridad en curso a la vez; si ya hay otra en curso, la interfaz pide reintentar más tarde (código de error 10029918). Si el disco donde está el directorio de datos del asistente tiene menos de 256 MB libres, se rechazan la exportación, la copia de seguridad y la carga del archivo de copia de seguridad (código de error 10029922); libere espacio en el disco antes de continuar.
| Función | Contenido | Uso |
|---|---|---|
| Exportar XML | Se elige la empresa y el rango de fechas de emisión (hasta 31 días) y se obtiene un zip con los XML autorizados, los XML de cancelación y una lista de las notas que no se pudieron obtener, con el motivo; se puede marcar «Solo de este equipo» para exportar solo los XML que ya están en el equipo, sin recuperarlos de la plataforma | Entregar al contador cada mes |
| Exportar paquete de pendientes | Todas las notas offline firmadas y aún no transmitidas de todas las empresas, en zip; dentro del paquete hay un directorio por dispositivo, con hasta 500 notas por paquete, y la plataforma lo importa directamente | Entregar a la plataforma para que transmita en su nombre cuando la computadora se dañó y no alcanzó a transmitir |
| Copia de seguridad | Copia completa y cifrada de la base local del núcleo de emisión; el gerente debe definir una contraseña de la copia de seguridad de al menos 8 caracteres (se ingresa dos veces) | Recuperar los datos en la misma computadora |
| Restaurar copia | Se elige y se carga el archivo de copia de seguridad (máximo 4 GB) y luego se ingresa su contraseña; la copia de seguridad reemplaza la base local actual | Recuperar la base local perdida o dañada |
Exportación:
- Al exportar XML, los que no están en el equipo se recuperan uno a uno de la plataforma; con muchas notas tarda varios minutos, espere a que termine. Si no se llega a la plataforma, el resto de las notas no espera y pasa directamente a la lista de las que no se pudieron obtener.
- El paquete de pendientes contiene los originales legales firmados; guárdelo con cuidado. Exportarlo no impide que el equipo siga transmitiendo.
Copia de seguridad:
- La contraseña de la copia de seguridad no se guarda en ningún lugar: si se pierde la contraseña, la copia de seguridad no se puede restaurar. Guárdela separada del archivo de copia de seguridad. Durante la copia de seguridad se puede seguir emitiendo con normalidad.
- La copia de seguridad solo se puede restaurar en la misma computadora (la clave del dispositivo está ligada al equipo); al cambiar de computadora hay que emparejar de nuevo, y las notas no transmitidas se resuelven con «Exportar paquete de pendientes».
Restauración desde la copia de seguridad:
- Restaurar desde la copia de seguridad requiere el PIN del gerente. La restauración reemplaza la base local actual y la base original se guarda automáticamente aparte en el directorio de datos; si la contraseña es incorrecta o el archivo de copia de seguridad fue modificado o está dañado, se muestra el código de error
10029846, la base original queda sin cambios y el asistente sigue funcionando con normalidad. El archivo de copia de seguridad cargado se borra tanto si la restauración tiene éxito como si no; para reintentar hay que volver a elegir el archivo. - Durante la restauración el asistente reinicia el núcleo de emisión, lo que tarda unos segundos; las solicitudes de emisión que lleguen en ese lapso quedan en cola. Si todavía hay una exportación, una copia de seguridad o una descarga de XML en curso, el asistente espera como máximo 15 segundos; si no terminan, no restaura y muestra el código de error
10029920; vuelva a pulsar restaurar cuando terminen esas operaciones. - Las notas offline emitidas después de la copia de seguridad no están en ella: si antes de restaurar el asistente todavía funciona con normalidad, exporte primero el paquete de pendientes y entréguelo a la plataforma.
- Después de restaurar, cada empresa primero se realinea con la plataforma: hasta entonces no puede emitir offline y la emisión en línea se sincroniza una vez antes de tomar un número; cuando llega una licencia nueva, la numeración de la serie del dispositivo salta 50 números hacia adelante y los declara inutilizados automáticamente, y la emisión en línea y offline sigue con normalidad, para no repetir números de notas emitidas después de la copia de seguridad. Hasta terminar el realineamiento no se puede emitir sin llegar a la plataforma.
8 Sin sistema de caja: emisión simple
Una tienda pequeña sin sistema de caja puede usar directamente la página «Emitir» del programa de escritorio:
- Lea el código de barras con el lector, o busque en «Productos» por código o nombre; también puede usar «Producto rápido», que solo pide descripción y valor, con los datos tributarios del grupo tributario por defecto de la configuración.
- En la lista de compra se cambian cantidades, descuentos por línea y se eliminan líneas; el total se calcula en tiempo real.
- El pago acepta efectivo (calcula el vuelto), tarjeta de débito, tarjeta de crédito, PIX y otros medios; si el valor supera el límite de identificación del estado, es obligatorio informar el CPF o CNPJ del consumidor.
- Al confirmar, muestra el resultado (autorizada o pendiente de transmisión offline) e imprime solo; la nota offline se imprime con la cantidad de copias que configura la plataforma.
- Atajos:
F2nueva venta,F4ir al pago,F8emitir e imprimir,Escvolver / cancelar la venta; toda la página puede usarse solo con el teclado.
En «Productos» se mantienen código, nombre, código de barras, NCM, CFOP, unidad, precio y grupo tributario de cada producto; los datos tributarios tienen la misma estructura que itens[].impostos de la solicitud de emisión.
La página de emisión está por defecto en modo cajero, sin PIN; en «Configuración», la opción «Exigir PIN para emitir» exige el PIN del gerente. Si no se exige, cualquier persona en la misma computadora puede emitir y ver las notas del día; en computadoras compartidas se recomienda activarlo.
El número de venta de la emisión simple aparece en «Notas del día» junto con las notas emitidas por el PDV:
- La página de emisión genera para cada venta un número con el formato
PDV-{yyyyMMdd}-{8 caracteres alfanuméricos}; al reintentar la misma venta conserva el número original y el asistente devuelve la nota original, sin emitir de nuevo. - Si la solicitud no trae número de venta, el asistente lo genera como
PDV-{yyyyMMdd}-{secuencia}y salta automáticamente los números ya ocupados.
Si la emisión es rechazada, haga clic en «Volver a la venta»; según el tipo de rechazo hay dos caminos:
- Rechazada en la transmisión (
Rejeitada): el número está ocupado; corrección con el mismo número, con PIN del gerente. - Rechazada en línea o por la plataforma (
Negada/Recusada): el número no tuvo efecto; tras corregir se emite como venta nueva, con un número de venta nuevo.
En «Notas del día» se filtra por fecha y estado y, para cada nota, se ofrecen «Ver», «Imprimir», «Anular» y «Corregir» (este solo si fue rechazada en la transmisión); al abrirla se entra en el detalle de la nota, vea Configuración y mantenimiento del programa de escritorio.
Preguntas frecuentes
¿El asistente de instalación dice que el código de emparejamiento es inválido o venció?
El código vale 72 horas y una sola vez. Un código vencido, ya utilizado o anulado no puede reutilizarse; pida al integrador que genere otro código.
¿Al emparejar dice que el CNPJ del certificado no coincide con la empresa?
El CNPJ del certificado elegido debe ser el de la empresa. Si una computadora atiende varios CNPJ, genere un código por empresa y elija en el asistente de instalación el certificado correspondiente a cada una.
¿El PDV recibe 401 al llamar la interfaz local?
La cabecera debe escribirse Authorization: Bearer tfl_…. El token solo se muestra una vez; si se perdió o fue revocado, el gerente genera otro en «Integración con PDV».
¿Sin red avisa que la licencia venció?
La emisión offline tiene límite de tiempo, y se renueva sola al volver la conexión. Un corte muy largo lo provoca; basta con restablecer la red.
¿Una nota offline no se transmite nunca?
La transmisión necesita el servicio del asistente en ejecución y con acceso a la plataforma. Vea en la página Resumen el estado de la conexión y la fecha de «Más antigua por transmitir»; si la tienda sale a internet por un proxy, revise la configuración del proxy de salida (vea Configuración y mantenimiento del programa de escritorio); también puede hacer una consulta desde el PDV o hacer clic en «Sincronizar ahora» en el programa de escritorio.
¿Qué hacer al cambiar la computadora de la tienda?
Primero conecte la computadora vieja para que transmita todas las notas offline («Por transmitir» en 0 en la página Resumen); después el integrador desactiva el dispositivo viejo y genera un código nuevo para la computadora nueva. No copie el directorio de datos a la computadora nueva: la clave del dispositivo está ligada al equipo y no funciona copiada.
Si la computadora vieja se dañó y no alcanzó a transmitir: mientras el asistente todavía abra, exporte el paquete de pendientes en «Acerca y diagnóstico» (vea Configuración y mantenimiento del programa de escritorio) y entregue el zip obtenido tal cual (sin descomprimir) al equipo de operación de la plataforma, que lo importa y transmite en su nombre; el paquete ya viene con un directorio por dispositivo y hasta 500 notas por paquete, no hace falta dividirlo, y se puede importar incluso después de desactivar el dispositivo viejo.
¿El PIN quedó bloqueado por errores?
Cada 5 errores acumulados bloquean el PIN una vez: el primer bloqueo dura 5 minutos y cada bloqueo siguiente dura el doble, hasta 24 horas. Durante el bloqueo incluso el PIN correcto se rechaza; al terminar el bloqueo el contador de errores no vuelve a cero, solo vuelve a cero al acertar el PIN una vez.
¿Qué enviar al soporte técnico?
Exporte el paquete de diagnóstico en «Acerca y diagnóstico». Contiene estado y registros, sin claves privadas, tokens, claves de callback ni PIN.
Valores del estado del dispositivo
situacao | Significado | Acción |
|---|---|---|
Ativo | Puede emitir | Nada |
Desativado | El integrador desactivó el dispositivo | Irreversible; para seguir usando la misma computadora hay que emparejarla de nuevo |
Revogado | La plataforma revocó el dispositivo | Contacte a la plataforma |
EmpresaDesativada | La emisión offline de la empresa está desactivada | Contacte a la plataforma |
AplicativoBloqueado | El software de caja fue bloqueado por la plataforma | Contacte a la plataforma |
VersaoBloqueada | La versión del PDV está bloqueada o por debajo de la mínima | Actualice el Asistente Fiscal |
Salvo Ativo, ningún estado permite emitir notas nuevas; las notas offline ya emitidas se siguen transmitiendo.
Valores del estado de la nota
situacaoLocal y status en las respuestas de la interfaz local. status usa los valores de la nube; situacaoLocal conserva el estado local completo.
situacaoLocal | status | Significado | Aparece en |
|---|---|---|---|
Autorizada | Autorizada | Autorizada por la SEFAZ, en línea o tras la transmisión de la nota offline | Emisión, consulta |
ContingenciaPendente | ContingenciaPendente | Firmada offline en esta computadora, pendiente de transmisión | Emisión, consulta, corrección |
AguardandoAutorizacao | AguardandoAutorizacao | Aceptada en línea, la SEFAZ aún no respondió y no fue posible firmar offline en ese momento; la emisión devuelve HTTP 202 | Emisión, consulta |
Negada | Negada | Emisión en línea rechazada por la SEFAZ, incluso tras un resultado en línea pendiente; no se puede corregir con el mismo número | Emisión, consulta |
Rejeitada | Negada | Transmisión de la nota offline rechazada por la SEFAZ; corríjala con el mismo número, vea Qué hacer tras un rechazo | Consulta, corrección |
Recusada | Negada | La plataforma rechazó esta nota offline; requiere intervención manual | Consulta |
Cancelada | Cancelada | Cancelada, incluida la cancelación por sustitución | Consulta |
