TF Fiscal
Documentación

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.

POST/openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao
Requiere las cabeceras de firma token, 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*
stringIdentificador de la empresa

* Campo obligatorio

Cuerpo de la petición

nomeDispositivo
stringNombre del dispositivo
ambiente
stringAmbiente de emisión
formaPermitida
stringForma permitida
serie
intSerie del dispositivo
numeroInicial
intNúmero inicial

* Campo obligatorio

200
Código generado. Entregue codigoAtivacao a la tienda.
success
boolResultado de la llamada
message
stringTexto del resultado
objectCó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.

json
{
"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
stringNombre del dispositivo
formaPermitida
stringForma permitida

* Campo obligatorio

Respuesta: código para el SDK

Guarde o entregue codigoAtivacao ahora; no vuelve en ninguna otra consulta.

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

json
{
"nomeDispositivo": "Caixa 03",
"serie": 21,
"numeroInicial": 1
}
serie
intSerie del dispositivo
numeroInicial
intNú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.

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