NFC-e offline
Generar código de emparejamiento
Genera el código de un solo uso con el que una caja se empareja; la primera llamada habilita la emisión offline de la empresa.
/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacaotoken, timestamp y sign, vea Autenticación.Un código por caja. El código ya lleva la dirección de la plataforma, la empresa y el ambiente; en la tienda basta informarlo junto con el certificado A1. La empresa debe estar activa y con NFC-e habilitada en el ambiente (bloque emissaoNFeConsumidor del registro); Producao exige además certificado A1 válido. No hay límite de dispositivos por empresa: mientras haya una serie disponible, se pueden agregar más cajas. Cada dispositivo tiene una serie NFC-e propia, usada en línea y offline con numeración continua; serie y numeroInicial fijan esa serie y el primer número, y omitidos la plataforma asigna la serie y empieza en 1. La NFC-e emitida por la API en la nube sigue usando la serie del perfil de la empresa.
Parámetros de ruta
empresaId* | string | Identificador de la empresa |
* Campo obligatorio
Cuerpo de la petición
nomeDispositivo | string | Nombre del dispositivo |
ambiente | string | Ambiente de emisión |
formaPermitida | string | Forma permitida |
serie | int | Serie del dispositivo |
numeroInicial | int | Número inicial |
* Campo obligatorio
codigoAtivacao a la tienda.success | bool | Resultado de la llamada |
message | string | Texto del resultado |
| object | Código de emparejamiento generado |
Los errores de negocio vuelven con HTTP 200 y success = false; un recurso inexistente vuelve con HTTP 404 y la validación de campo con HTTP 400. Decida siempre por el code.
Entregue el código a la tienda como texto o como archivo .tfa: el archivo es el propio texto del código, en UTF-8 y en una sola línea. El código vale una vez y vence en 72 horas; si se pierde, genere otro. Una empresa acepta como máximo 20 códigos pendientes (no usados y no vencidos).
Primer código, sin cuerpo
Cuerpo vacío {} (o sin cuerpo): nombre predeterminado, ambiente actual de la empresa y cualquier forma. La primera llamada habilita la emisión offline de la empresa; no hay etapa separada. nomeDispositivo, ambiente y formaPermitida no enviados.
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Dispositivo 1","ambiente": "Homologacao","formaPermitida": "Qualquer","serie": null,"numeroInicial": null}}
Caja con SDK, con nombre
Código solo para el PDV con SDK embebido. nomeDispositivo y formaPermitida = Sdk opcionales y enviados; ambiente no enviado, vale el ambiente actual de la empresa. La solicitud es el ejemplo del inicio de la página.
nomeDispositivo | string | Nombre del dispositivo |
formaPermitida | string | Forma permitida |
* Campo obligatorio
Respuesta: código para el SDK
Guarde o entregue codigoAtivacao ahora; no vuelve en ninguna otra consulta.
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Caixa 01","ambiente": "Homologacao","formaPermitida": "Sdk","serie": null,"numeroInicial": null}}
Serie y número inicial definidos
Para que la caja use una serie acordada con la tienda. serie y numeroInicial opcionales y enviados; la primera nota del dispositivo, en línea u offline, sale con el número 1 de la serie 21, y las siguientes siguen en secuencia. La serie se verifica de nuevo en el emparejamiento; si en ese intervalo dejó de estar libre, el emparejamiento devuelve el mismo código de error y hay que generar otro código.
{"nomeDispositivo": "Caixa 03","serie": 21,"numeroInicial": 1}
serie | int | Serie del dispositivo |
numeroInicial | int | Número inicial |
* Campo obligatorio
Cambiar la computadora manteniendo la serie
La caja antigua fue desactivada y ya transmitió todas las notas offline (pendentesTransmissao = 0). Envíe la misma serie sin numeroInicial: la plataforma continúa después del mayor número ya conocido en la serie y devuelve el número efectivo en numeroInicial. Si la caja antigua aún tiene notas por transmitir, la respuesta es 10029225.
{"success": true,"message": "OK","data": {"codigoAtivacaoId": "1950000000000000101","codigoAtivacao": "TFA1.eyJhbWIiOjIsImV4cCI6MTc2MzA0NjAwMCwiZm9ybWEiOjB9.Mx3K9qVbT2nWc8yLr0aZpE4sHdUfGj7i","expiraEm": "2026-11-14T13:10:00Z","nomeDispositivo": "Caixa 01","ambiente": "Homologacao","formaPermitida": "Qualquer","serie": 2,"numeroInicial": 422}}
ambienteAmbiente
| Valores | Significado |
|---|---|
| Homologacao | Homologación: notas sin valor fiscal, para pruebas de integración |
| Producao | Producción: notas con valor fiscal; exige certificado A1 válido de la empresa |
formaPermitidaForma permitida
Omitido vale Qualquer.
| Valores | Significado |
|---|---|
| Qualquer | Lo puede emparejar el Asistente Fiscal o un PDV con SDK |
| Assistente | Solo el Asistente Fiscal lo empareja; el PDV con SDK recibe 10029209 |
| Sdk | Solo un PDV con SDK lo empareja; el Asistente rechaza el código |
| Código | HTTP | |
|---|---|---|
| 10029100 | 404 | Empresa inexistente o de otro integrador. |
| 10029101 | 200 | La empresa no puede emitir NFC-e: inactiva, sin NFC-e en el ambiente o, en Producao, sin certificado A1 válido; message indica el motivo. |
| 10029219 | 200 | ambiente distinto del ambiente actual de la empresa. |
| 10029104 | 200 | Emisión offline de la empresa desactivada por la plataforma; contacte a la plataforma. |
| 10029201 | 200 | Ya hay 20 códigos pendientes en esta empresa; úselos o espere a que venzan. |
| 10029221 | 200 | serie entre 890 y 999; la NFC-e de emisor CNPJ solo usa las series 0 a 889. |
| 10029222 | 200 | serie es la serie NFC-e del perfil de la empresa en alguno de los ambientes; elija otra. |
| 10029223 | 200 | serie ya la tiene otro dispositivo activo o un código pendiente de la empresa; message dice cuál. |
| 10029224 | 200 | numeroInicial no es mayor que el mayor número ya conocido en la serie; message trae ese número. |
| 10029225 | 200 | serie pertenece a un dispositivo desactivado o revocado que aún tiene notas offline por transmitir; espere a que termine la transmisión. |
| 10029001 | 200 | ambiente o formaPermitida fuera de los valores; message dice cuál. |
| 10001001 | 400 | Validación de campo, incluida serie fuera de 0 a 999 o numeroInicial fuera de 1 a 999999999; message indica el campo. |
