NFC-e offline
Punto de entrada de la emisión offline de NFC-e: cuándo se necesita, cómo elegir entre el SDK embebido y el Asistente Fiscal, el flujo de integración, las reglas de números y transmisión, y cómo llegan los resultados.
Esta página es el punto de entrada de la emisión offline de NFC-e: explica cuándo se necesita, cómo elegir entre las dos opciones de integración y qué pasos hay que seguir. Al terminar podrá elegir la opción y sabrá en qué página se hace cada paso. El requisito es que la empresa ya esté integrada según lo que exige la NFC-e en la nube.
Cuándo necesita la emisión offline
Cuando la tienda se queda sin red y no alcanza la plataforma, la caja igual tiene que emitir la nota y entregarla al consumidor en el momento. La emisión offline permite que la caja emita en la propia computadora una nota de contingencia offline (una NFC-e firmada en el equipo sin red, pendiente de transmisión y autorización) e imprima el cupón en el momento; cuando la red vuelve, la nota se transmite sola (va a la plataforma y de ahí a la SEFAZ para autorización) y el resultado le llega como siempre.
Con la red normal, la emisión se autoriza en línea como de costumbre, con el mismo resultado que la NFC-e en la nube.
Qué opción elegir
| Opción 1: SDK embebido en el PDV | Opción 2: integrar el Asistente Fiscal | |
|---|---|---|
| Qué es | El software de caja integra el paquete de desarrollo y el núcleo de emisión offline corre junto con él | La computadora de la tienda instala TF Fiscal Asistente Fiscal (programa Windows) y el software de caja llama su interfaz local |
| Para quién | Software de caja propio en Java que no quiere que la tienda instale otro programa | Integradores que no quieren tocar el interior del software de caja, o tiendas sin sistema de caja que usan la emisión simple del asistente |
| Qué hay que hacer | Incorporar el SDK, distribuir el runtime con el instalador, llamar el método de emisión y tratar eventos | La tienda instala el asistente; el software de caja cambia la dirección de emisión por la local, con el mismo cuerpo del endpoint de emisión en la nube |
| Esfuerzo | Medio: escribir el código de inicialización, emparejamiento y tratamiento de eventos | Bajo: solo cambiar la dirección y la cabecera de autenticación |
| Clases de impuesto | Soportadas con conexión; sin red, envíe impostos | Soportadas con conexión; sin red, envíe impostos |
Recomendación: si el software de caja es un programa propio en Java, elija el SDK embebido; si no, elija el Asistente Fiscal. El SDK embebido solo existe en versión Java. Elija una de las dos opciones; dentro de una misma empresa, cajas distintas también pueden usar una cada una.
Flujo de integración
Antes de empezar, la empresa ya debe estar registrada con la NFC-e habilitada y con el certificado asociado.
- Generar el código de emparejamiento: para cada caja, llame Generar código de emparejamiento y entregue a la tienda el código de emparejamiento devuelto (la credencial de un solo uso que vincula una caja a la empresa). La primera llamada habilita la emisión offline de la empresa.
- Instalar y emparejar en la tienda: para el SDK embebido, vea las secciones de preparación y emparejamiento del Tutorial del SDK embebido; para el Asistente Fiscal, la sección de instalación y emparejamiento del Tutorial del Asistente Fiscal. Basta emparejar cada caja una vez.
- Emitir: con el SDK embebido se llama el método de emisión, vea Emitir la primera nota; con el Asistente Fiscal se llama el endpoint local de emisión, vea Emisión, consulta y transmisión. Con red y sin red se usa la misma llamada.
- Recibir los resultados: el software de caja los recibe en el propio equipo y el servidor del integrador recibe los webhooks como siempre, vea Cómo llegan los resultados.
La validez del código de emparejamiento y el tiempo máximo offline los controla la plataforma. El ambiente de pruebas permite probar todo el flujo; las notas emitidas en pruebas no tienen valor fiscal. Si la empresa cambia de ambiente, hay que generar nuevos códigos de emparejamiento en el nuevo ambiente y emparejar de nuevo las cajas.
Números y serie
- Serie del dispositivo: una serie NFC-e propia de cada caja. La emisión en línea y la offline la usan las dos: la caja toma los números en una única secuencia y firma en el propio equipo; con red entrega la nota firmada a la plataforma, que la envía a la SEFAZ; sin red sigue emitiendo notas offline en la misma secuencia. Por eso las notas en línea y offline de una caja tienen numeración continua. Por la misma razón la emisión en línea también necesita el certificado y los datos tributarios locales, que se sincronizan solos después del emparejamiento.
- Serie y número inicial a elección: al generar el código de emparejamiento, la serie del dispositivo se fija con
seriey el número de la primera nota connumeroInicial; si se omiten, la plataforma asigna la serie y empieza en 1.serieOfflineen Listar dispositivos es la serie del dispositivo. - Separada de la serie en la nube: la NFC-e emitida por la API de emisión en la nube sigue usando la serie del perfil de la empresa, que nunca coincide con una serie de dispositivo. Si el mismo CNPJ emite a través de varios integradores, cada uno debe usar series que no se superpongan (incluidas las series de los dispositivos); de lo contrario la SEFAZ las rechaza.
- Varias cajas con una sola serie: varias cajas también pueden compartir una sola serie de dispositivo, con los números tomados en un solo lugar y continuos. El Asistente Fiscal en modo red local atiende a toda la tienda, vea Varias cajas en la misma tienda; el SDK embebido usa el modo principal y secundario, vea Varias cajas (modo principal y secundario).
- Números que gestiona la plataforma: cuando un envío en línea queda con resultado incierto, una nota en línea es rechazada o algún estado no acepta la inutilización, la plataforma cierra el número por su cuenta; ni el software de caja ni el integrador tienen que hacer nada. Los detalles están en el Apéndice.
Notas offline y transmisión
- La nota emitida sin red queda en
ContingenciaPendente; el cupón sale con la marca de contingencia offline y se entrega al consumidor como siempre. - Cuando la red vuelve, la transmisión es automática, sin ninguna acción; tras la autorización de la SEFAZ el estado pasa a
Autorizada. - Una nota offline rechazada por la SEFAZ se corrige con el mismo número y se reenvía; solo se puede cambiar lo que no afecta valores ni impuestos (por ejemplo NCM, CFOP, documento del consumidor).
- La nota offline debe transmitirse dentro del plazo del estado, según la configuración de la plataforma; cerca del plazo hay un aviso, y pasado el plazo esa caja ya no emite offline.
- La cancelación pedida antes de la autorización de una nota offline queda en espera en la plataforma y se envía en el momento de la autorización.
- Las notas con combustible no se emiten offline.
- Los ítems que referencian una clase de impuesto (
classeImposto) requieren conexión; sin red, envíeimpostos, vea Clases de impuesto y conexión.
Clases de impuesto y conexión
Los ítems pueden referenciar una clase de impuesto con classeImposto, igual que en la emisión en la nube; así se pueden omitir cfop e impostos. Las clases de impuesto se guardan solo en la plataforma: al emitir, el Asistente Fiscal y el SDK embebido envían primero la solicitud a la plataforma, que la expande en impostos completos; luego el cálculo, la firma y la emisión se hacen en el dispositivo. La expansión es la misma que en la emisión en la nube.
- Requiere conexión: sin red o sin acceso a la plataforma, la solicitud que referencia una clase de impuesto se rechaza con
10029780, con la indicación de enviarimpostos. La solicitud rechazada no consume número y la nota siguiente mantiene la secuencia. - El programa de caja se encarga de la contingencia: el Asistente Fiscal y el SDK embebido no guardan clases de impuesto. Para seguir emitiendo sin red, el programa de caja debe guardar los
impostosexpandidos y, sin red, enviarimpostosen los ítems. Con el SDK embebido, elPedidoque devuelveConsultarde una nota emitida con red ya es la solicitud expandida. - Clase de impuesto rechazada: una clase inexistente, incompatible con el régimen actual de la empresa (
IncompativelComRegime) y casos similares devuelven los mismos códigos y mensajes que la emisión en la nube, como10005202y10005220; los mensajes siguen el idioma de la interfaz del Asistente Fiscal o elidiomadel SDK embebido. - Clase de impuesto registrada: cada nota registra el código y la versión de la clase de impuesto usada en cada ítem y los informa a la plataforma junto con la nota.
Cómo llegan los resultados
| Canal | Contenido |
|---|---|
| Software de caja | El SDK embebido usa los eventos del SDK; el Asistente Fiscal, el callback local o la consulta del asistente |
| Servidor del integrador | Recibe los webhooks de NFC-e de siempre: transmisión aceptada nfce.contingency_issued, autorizada nfce.authorized, rechazada nfce.rejected, cancelación nfce.canceled / nfce.cancel_rejected |
| Eventos de dispositivo | nfce.device.activated (emparejamiento), nfce.device.deactivated (desactivación), nfce.device.upload_overdue (transmisión cerca del plazo); data es el objeto dispositivo |
- Notas emitidas por una caja: la carga del webhook trae al final un
dispositivoId; cuando el dispositivo informó la caja, a continuación viene además la identificación de la cajaterminal, que indica qué caja emitió la nota. En el Asistente Fiscal es el nombre del token de caja; en el modo principal y secundario del SDK embebido, el nombre del terminal secundario. - Notas sin identificación de la caja: cuando el dispositivo no informó la caja, por ejemplo una nota emitida por el propio principal del SDK embebido o en modo independiente, la consulta y el webhook no traen la clave
terminal; no se devuelvenull. - Suscripción: qué eventos se entregan y cómo suscribirse solo a algunos, vea las reglas de suscripción en Webhooks.
Endpoints
| Endpoint | Para qué |
|---|---|
| Generar código de emparejamiento | Uno por caja, válido 72 horas y de un solo uso |
| Listar dispositivos | Conexión y notas por transmitir de cada caja |
| Desactivar dispositivo | Al cambiar o retirar una caja, sin vuelta atrás; las notas offline ya emitidas se siguen transmitiendo |
Apéndice: números que la plataforma gestiona por usted
En todos estos casos actúa la plataforma; ni el software de caja ni el integrador tienen que hacer nada.
| Caso | Qué hace la plataforma |
|---|---|
| Un envío en línea queda con resultado incierto, por ejemplo tiempo agotado, caída de red o la plataforma no respondió a tiempo | Ese número no se vuelve a usar: la caja emite una nota offline con el número siguiente y la entrega al consumidor. Después la plataforma revisa el número original: si la SEFAZ lo autorizó, la plataforma lo cancela por sustitución; si no, la plataforma inutiliza el número en la SEFAZ |
| La SEFAZ rechaza una nota en línea | La plataforma inutiliza su número y no se reutiliza |
| La plataforma rechaza la nota en el momento, sin enviarla | El número pasa a la nota siguiente |
| AC, BA y SP, o cuando otro estado desactiva su servicio de inutilización | Los números que arriba se inutilizarían no se declaran y la numeración simplemente continúa tras el salto. Esos números cuentan como usados y no se vuelven a emitir |
