TF Fiscal
Documentación

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.

text
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

ÍtemDetalle
ComputadoraWindows, la misma del PDV; para que un asistente atienda varias cajas vea Modo red local
PermisosLa instalación requiere permisos de administrador
InstaladorTfFiscalAssistente-{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 emparejamientoLo genera el integrador con Generar código de emparejamiento, con formaPermitida Assistente o Qualquer; sirve como texto o archivo .tfa
CertificadoEl 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.

PasoContenido
1 BienvenidaElija 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 emparejamientoPegue 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 CertificadoLista 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 gerenteDefina un PIN de gerente de 6 a 8 dígitos, que se usa para cancelar, corregir, administrar tokens, exportar, respaldar, etc.
5 EmparejarEmpareja 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 ListoMuestra 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 callback whsec_…, 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

ÍtemValor
Direcciónhttp://127.0.0.1:8765; en modo red local, la dirección de red local de la computadora del asistente
AutenticaciónCabecera Authorization: Bearer tfl_…; sin token / timestamp / sign de la nube
Tipo de contenidoContent-Type: application/json

Lista de rutas

MétodoRutaUsoEquivalente en la nube
POST/openapi/v2/empresas/{empresaId}/nfceEmitirEmitir NFC-e
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}ConsultarConsultar NFC-e
POST/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelarCancelarCancelar NFC-e
POST/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar-substituicaoCancelación por sustituciónCancelación por sustitución
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cupom?formato=ESCPOS_80Cupón, incluido el formato PDFSolo local
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xmlDescarga del XML autorizadoSolo local
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml-cancelamentoDescarga del XML de cancelaciónSolo local
POST/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/correcaoCorrección con el mismo número tras un rechazo en la transmisiónSolo local
GET/openapi/local/v1/situacaoEstado del asistenteSolo local

Diferencias con los endpoints en la nube

  • Autenticación: con el token de caja, vea Dirección y autenticación.
  • modoResposta no 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 con AguardandoAutorizacao. 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 con 10029780, con la indicación de enviar impostos, sin consumir número. El asistente no guarda clases de impuesto, así que para la contingencia el programa de caja debe guardar los impostos expandidos, 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 con 10029801, sin acceso del token 403 con 10029902.
  • Enlaces del cupón y del XML: linkDanfe apunta al cupón local (formato HTML); linkDownloadXml apunta a la ruta local del XML cuando el XML autorizado ya se descargó al equipo, si no es null.
  • Campos locales adicionales: además de los campos de la nube, la respuesta trae los de la tabla siguiente.
CampoDetalle
situacaoLocalEstado 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 / xMotivoCódigo y mensaje de resultado de la SEFAZ. Vienen juntos; son null en notas offline pendientes y en rechazos de la plataforma
tentativaOnlineIndicador 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
transmitidaIndicador de transmitida. Solo en la consulta
cancelamentoPendenteIndicador de cancelación pendiente. Solo en la consulta; true para la cancelación pedida antes de autorizar una nota offline
correcoesCantidad de correcciones. Solo en la consulta
xmlAutorizadoDisponivelIndicador de XML autorizado disponible. Solo en la consulta; true significa que ya se descargó al equipo
terminalIdentificació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

CasoHTTPCuerpo
Emisión, consulta o corrección exitosa200; pendiente en línea 202Objeto plano con la misma estructura de la consulta en la nube, más los campos locales
Cancelación o cancelación por sustitución aceptada200Sin cuerpo; el destino viene en la cabecera X-Tffiscal-Cancelamento
Descarga exitosa del cupón o del XML200El archivo original; tipos en Cupón y descarga de XML
Error de negocio400; nota o empresa inexistente 404; XML no disponible 409; asistente ocupado 429; error interno 500; protección contra downgrade 503Array [{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 origen401 / 403Sobre 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:

http
POST /openapi/v2/empresas/1934811222334455/nfce HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-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" } }
}
]
}
CampoCómo llenar
idNú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
ambienteEmissaoAmbiente de emisión. Obligatorio, igual al ambiente con que se emparejó el dispositivo
pedido, itensPedido y productos. Obligatorios, mismas reglas que Emitir NFC-e
clienteConsumidor. Opcional, no se envía con consumidor no identificado
modoRespostaModo 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:

json
{
"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:

json
{
"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"
}
  • serie es 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 = true significa 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, es false.
  • 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_issued y luego nfce.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:

http
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131 HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t

Tras la transmisión y la autorización:

json
{
"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"
}
  • emitidaEmContingencia sigue en true tras la autorización.
  • El asistente descarga solo el XML autorizado después de la transmisión; aunque xmlAutorizadoDisponivel sea false, 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-EventDisparonfeStatus
nfce.contingency_issuedNota firmada offline en el equipoContingenciaPendente
nfce.authorizedAutorizada tras la transmisión, tras una corrección o tras quedar pendiente en líneaAutorizada
nfce.rejectedNota offline rechazada por la SEFAZ en la transmisión, o nota pendiente en línea rechazada después por la SEFAZNegada, nfeMotivoStatus con código y motivo
nfce.canceledCancelación exitosa, incluida la cancelación por sustituciónCancelada
nfce.cancel_rejectedCancelación rechazadaCancelamentoNegado
nfce.intake_rejectedSolo local: la plataforma rechazó esta nota offlineRecusada, nfeMotivoStatus con código de error de la plataforma y motivo; contacte a la plataforma
nfce.device.deactivatedSolo local: dispositivo desactivado o revocadoPayload 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

http
POST {callbackUrl}
Content-Type: application/json; charset=utf-8
X-Tffiscal-Event: nfce.contingency_issued
X-Tffiscal-Event-Id: 7b0c1d9e-2a52-4e0f-9a3e-5d2f1c0b8a77
X-Tffiscal-Delivery-Id: 0f5f8d0c-9a4b-4b3d-8c0e-61f2b7d4a913
X-Tffiscal-Timestamp: 1762786800
X-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:

EntradaValor
Clave del callbackwhsec_testsecret
X-Tffiscal-Timestamp1762790400
Cuerpo{"tipo":"NFC-e","nfeId":"PDV-1"}
Firma esperada415bce74a6740037c540f3839e69a08bd3026c8337dd49c73e8a4877889de0a4

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:

json
{
"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:

json
{
"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ónCómo se haceDetalle
Tratar una nota rechazadaSegún situacaoLocal: Rejeitada se corrige con el mismo número; Negada / Recusada se emite de nuevo con un id nuevoQué hacer tras un rechazo
Imprimir el cupón, descargar el XMLGET …/cupom?formato=…, GET …/xml, GET …/xml-cancelamentoCupón y descarga de XML
Cancelar una notaPOST …/cancelar y leer la cabecera X-Tffiscal-CancelamentoCancelación
Se emitieron dos notas para la misma ventaPOST …/cancelar-substituicao: cancela la nota original en línea y la vincula a la nota offline sustitutaCancelación por sustitución
Mostrar en la caja que está sin conexión o con notas por transmitirGET /openapi/local/v1/situacaoEstado del asistente
Tratar erroresSegún el estado HTTP y el código de errorManejo de errores

Qué hacer tras un rechazo

Toda nota rechazada tiene status Negada; el tratamiento depende de situacaoLocal:

situacaoLocalSignificadoQué hacer
RejeitadaNota offline rechazada por la SEFAZ en la transmisión. La nota ya se entregó al consumidor y el número está ocupadoCorrija con el mismo número y reenvíe; no se puede emitir otra, vea abajo
NegadaRechazada en línea por la SEFAZ, incluido el rechazo tras quedar pendiente en línea. La plataforma inutiliza el número; no se reutilizaCorrija la solicitud y emita de nuevo con un id nuevo
RecusadaLa plataforma rechazó esta nota offline. El número no tuvo efectoContacte 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):

json
{
"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:

http
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/correcao HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-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 es Rejeitada, 10029820.
  • Si funciona devuelve HTTP 200 con la misma estructura de la respuesta de Emisión sin red, situacaoLocal vuelve a ContingenciaPendente y espera una nueva transmisión.

Cupón y descarga de XML

Al pedir el cupón, elija el formato con formato:

http
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=ESCPOS_80 HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
formatoTipo de respuestaUso
ESCPOS_80 (por defecto)application/octet-streamImpresora térmica de 80 mm; los bytes van directo a la impresora
ESCPOS_58application/octet-streamImpresora térmica de 58 mm
TEXTOtext/plain; charset=utf-8Texto plano
HTMLtext/html; charset=utf-8Vista en pantalla o impresión desde el navegador
PDF_80application/pdfPDF 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:

http
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
RutaDevuelveSi no está disponible
GET …/xmlXML autorizado original, application/xml; charset=utf-8Aún no autorizada, o no está en el equipo y no se pudo recuperar de la plataforma: 409 con 10029841
GET …/xml-cancelamentoXML de cancelación original, application/xml; charset=utf-8Aú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:

http
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cancelar HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-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:

ValorSignificado
SolicitadoEnviada a la plataforma; el resultado llega por callback o consulta
AgendadoLa 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
EnfileiradoLocalCola 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:

http
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cancelar-substituicao HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-Type: application/json
{
"chaveAcessoSubstituta": "35261111222333000181650020000004219123456783",
"justificativa": "Venda registrada em contingencia off-line"
}
CampoCómo llenar
nfceId (ruta)Número de la nota original. La nota emitida en línea que se va a cancelar
chaveAcessoSubstitutaClave de acceso de la nota sustituta. Obligatoria, 44 dígitos, de la nota offline que sustituye a la original
justificativaMotivo 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 chaveAcessoSubstituta devuelve 400 con 10029909.

Al aceptarla devuelve HTTP 200 sin cuerpo:

http
HTTP/1.1 200 OK
X-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.canceled o nfce.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»:

json
{
"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": []
}
CampoDetalle
versaoNucleoVersión del núcleo
empresaId / dispositivoIdIdentificador de la empresa e identificador del dispositivo
situacaoEstado del dispositivo. Valores en Valores del estado del dispositivo
conectadoIndicador 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
licencaExpiraEmVencimiento de la licencia
offlineAtePlazo offline. Pasado ese momento ya no se puede emitir offline
pendentesTransmissaoNotas por transmitir
pendenteMaisAntigaEmPendiente más antigua. Fecha de emisión de la nota por transmitir más antigua
prazoTransmissaoAtePlazo 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
certificadoValidoAteVencimiento del certificado
ultimoErroÚltimo error. Descripción del último error; null si no hay
numerosNaoUtilizadosPendentesRangos 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
restauradoPendenteSincronizacaoRestauració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
avisosAvisos 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:

json
[
{ "codigo": "10029817", "mensagem": "itens: obrigatório" },
{ "codigo": "10029817", "mensagem": "pedido.pagamento: obrigatório" }
]

Falta de token (HTTP 401), en sobre de la plataforma:

json
{ "success": false, "errorType": 1, "code": 10029900, "message": "Token de caixa ausente (Authorization: Bearer tfl_...)" }
HTTPCódigoCasoQué hacer
40110029900 / 10029901Falta el token / token inválido o revocadoRevise la cabecera Authorization; si el token fue revocado, el gerente genera otro
40310029902El token no tiene acceso a esa empresaEl gerente genera en «Integración con PDV» un token que incluya esa empresa
40310029903Dirección de origen fuera de la red permitida del modo red localRevise la configuración del modo red local
40410029801La empresa no está emparejada en este asistenteRevise el empresaId, o agregue la empresa en el asistente de instalación
40410029819La nota no existe en este equipoRevise el nfceId
40010029817Validació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
40010029780Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún númeroReenvíe cuando vuelva la red; sin red, envíe impostos en los ítems
40010029909Solicitud inválida, por ejemplo una cancelación por sustitución sin la clave de la nota sustitutaCorrija según mensagem
40010029818El mismo id ya se usó para una nota con contenido distintoVenta nueva, id nuevo; para reintentar use la solicitud original; tras un rechazo vea Qué hacer tras un rechazo
40010029820 / 10029821El estado actual no permite corregir / la corrección cambió valores o impuestosSolo Rejeitada admite corrección, y solo de lo que no afecta valores
40010029822El 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íneaNo reintente
40010029845Clave de la nota sustituta inválida, o no es una nota offline no rechazada de este dispositivo y esta empresaRevise la clave de la nota sustituta
40010029804 / 10029807Sin red y licencia vencida / pasó el plazo offlineRestablezca la red; tras renovar vuelve solo
40010029808La serie del dispositivo llegó al número 999999999Desactive 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
40010029810La nota pendiente más antigua superó el plazo de transmisiónRestablezca la red para transmitir
40010029811La empresa o el estado no permite offlineSolo se puede emitir en línea
40010029816Dispositivo desactivadoContacte al integrador
40010029424La plataforma informa el número como ya usado; el núcleo lo descartó, reintentó una vez y el conflicto sigueExporte el paquete de diagnóstico y contacte a la plataforma
40010029426El mismo id ya tiene una nota no rechazada en la plataforma, por ejemplo emitida por la API en la nubeVerifique la nota original; use un id nuevo para una venta nueva
40910029841XML autorizado no disponiblePídalo de nuevo tras la autorización; si no se pudo recuperar, reintente más tarde
40910029843XML de cancelación no disponiblePídalo de nuevo tras la cancelación exitosa; si no se pudo recuperar, reintente más tarde
42910029918Límite de recuperaciones simultáneas de XML alcanzadoReintente más tarde
50010029912 / 10029836Error interno del asistente o del núcleoExporte el paquete de diagnóstico en «Acerca y diagnóstico» y contacte al soporte técnico
50310029842Protección contra downgrade: el directorio de datos fue usado por una versión más recienteInstale 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 formaPermitida en Assistente o Qualquer; 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:8765 o, en modo red local, la dirección de red local de la computadora del asistente; cada solicitud lleva Authorization: Bearer tfl_….
  • Cada venta usa un id único y el reintento de la misma venta usa el mismo id; ambienteEmissao es igual al ambiente con que se emparejó el dispositivo.
  • El PDV trata HTTP 202 con AguardandoAutorizacao, ContingenciaPendente y los tres tipos de rechazo según situacaoLocal, 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 10029918 se reintenta más tarde.

Recepción de resultados:

  • Con callback local: verificar la firma con la clave del callback whsec_…, deduplicar por X-Tffiscal-Event-Id y 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/situacao para mostrar las notas por transmitir y vigilar prazoTransmissaoAte y avisos.

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:

powershell
& "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 predeterminado segredos.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:

bat
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"
PropiedadObligatoriaDetalle
TFA_FILEPara emparejarRuta 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_FILEUna de esta fila o la siguienteRuta del archivo del certificado PFX. La contraseña sale de pfxSenha del archivo de secretos
CERT_THUMBPRINTUna de esta fila o la anteriorHuella de un certificado existente. Admite CERT_STORE, por defecto LOCAL_MACHINE; antes debe ejecutarse el script de acceso a la clave privada
SECRETS_FILEPara emparejarRuta 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_PASSWORD y ADMIN_PIN ya 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:

CasoCuándo ocurreQué hace el emparejamientopin del archivo de secretos
Primera instalaciónLa computadora todavía no completó ninguna instalaciónEmpareja directamente; el pin pasa a ser el PIN del gerenteEl nuevo PIN del gerente, de 6 a 8 dígitos
Agregar empresa ya instaladaSe 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 instaladaPrimero inicia la sesión del gerente con el pin y luego empareja, es decir, agrega una empresa; las empresas ya emparejadas no se ven afectadasDebe 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):

bat
"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 --pfx por --thumbprint {thumbprint} y, si quiere, agregue --store LOCAL_MACHINE o --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 pin del 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 salidaSignificadoQué hace el script de despliegue
0Emparejamiento exitosoNada
1Emparejamiento rechazadoActúe según el código de error de la salida estándar
2Parámetros incorrectos, archivo de secretos inválido o servicio inaccesibleCorrija los parámetros y el archivo de secretos y vuelva a ejecutar
3Se puede reintentar con el mismo código de emparejamientoVuelva 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 VersaoBloqueada y 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:
json
[ { "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 ejemplo 192.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:

  1. 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.
  2. 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.
  3. 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 ejemplo PDV 01, PDV 02; ese nombre es la identificación de la caja terminal en 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.
  4. 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:8765 por la dirección de red local de la computadora del asistente, por ejemplo http://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:

ÍtemDetalle
Conexión a internetDirecta (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ónDirección del servidor proxy. Formato host:puerto, obligatoria en modo manual; sin puerto se usa 8080
UsuarioUsuario de autenticación del proxy. Vacío significa sin autenticación y además borra la contraseña guardada
ContraseñaContraseñ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 paraHosts 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 10029919 y 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:

ÍtemValores
Columnas por línea48, 42, 32, o según el ancho del papel por defecto
Página de códigos de la impresoraCP1252 (por defecto), CP860, CP850, CP437; los caracteres que no existen en la página de códigos se imprimen sin acento
Código QRComando 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 imprimirSi se corta el papel tras imprimir
CopiasCopias 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ónContenidoUso
Exportar XMLSe 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 plataformaEntregar al contador cada mes
Exportar paquete de pendientesTodas 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 directamenteEntregar a la plataforma para que transmita en su nombre cuando la computadora se dañó y no alcanzó a transmitir
Copia de seguridadCopia 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 copiaSe 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 actualRecuperar 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: F2 nueva venta, F4 ir al pago, F8 emitir e imprimir, Esc volver / 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

situacaoSignificadoAcción
AtivoPuede emitirNada
DesativadoEl integrador desactivó el dispositivoIrreversible; para seguir usando la misma computadora hay que emparejarla de nuevo
RevogadoLa plataforma revocó el dispositivoContacte a la plataforma
EmpresaDesativadaLa emisión offline de la empresa está desactivadaContacte a la plataforma
AplicativoBloqueadoEl software de caja fue bloqueado por la plataformaContacte a la plataforma
VersaoBloqueadaLa versión del PDV está bloqueada o por debajo de la mínimaActualice 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.

situacaoLocalstatusSignificadoAparece en
AutorizadaAutorizadaAutorizada por la SEFAZ, en línea o tras la transmisión de la nota offlineEmisión, consulta
ContingenciaPendenteContingenciaPendenteFirmada offline en esta computadora, pendiente de transmisiónEmisión, consulta, corrección
AguardandoAutorizacaoAguardandoAutorizacaoAceptada en línea, la SEFAZ aún no respondió y no fue posible firmar offline en ese momento; la emisión devuelve HTTP 202Emisión, consulta
NegadaNegadaEmisión en línea rechazada por la SEFAZ, incluso tras un resultado en línea pendiente; no se puede corregir con el mismo númeroEmisión, consulta
RejeitadaNegadaTransmisión de la nota offline rechazada por la SEFAZ; corríjala con el mismo número, vea Qué hacer tras un rechazoConsulta, corrección
RecusadaNegadaLa plataforma rechazó esta nota offline; requiere intervención manualConsulta
CanceladaCanceladaCancelada, incluida la cancelación por sustituciónConsulta