TF Fiscal
Documentación

Primeros pasos

Convenciones generales

Las dos formas de respuesta (respuestas simples vs. sobre de la plataforma), formas de error, tipificación de errores, referencia de estados HTTP, idempotencia, límites de tasa, localización, tipos de datos, la estructura de la clave de acceso de la NF-e y los enlaces de descarga de archivos.

Convenciones compartidas por los endpoints de la Open API de TF Fiscal.

Formas de respuesta

La API tiene dos formas de respuesta, y cuál recibe depende del endpoint y de la capa que produjo la respuesta.

Respuestas simples (endpoints estándar)

Todos los endpoints estándar (empresas, NF-e, CT-e, DC-e, verificación, consulta de registro, registro de webhook) responden sin sobre:

Grupo de endpointsForma de éxito
Registro de empresa, registro de webhookObjeto simple ({ "empresaId": ... }, { "webHookId": ... })
Vinculación de certificado, emisión y cancelación de NF-e / CT-e / DC-eHTTP 200 sin cuerpo; el resultado llega de forma asíncrona
Consulta de NF-e / CT-e / DC-e, registro de carta de corrección y de eventosObjeto simple: el documento, el protocolo o la lista de eventos
Verificación por XML, consulta por chaveObjeto simple: la factura interpretada (la verificación por XML añade el bloque validation)
Consulta de CNPJ, consulta de CPFObjeto simple: el registro

Los errores de negocio y de solicitud de los endpoints estándar vienen en dos formas de error, según la familia del endpoint.

Familia de emisión (empresas, NF-e, CT-e, DC-e, registro de webhook; HTTP 400 / 404): un array de errores, cada uno con codigo y mensagem. Los fallos de validación del cuerpo producen una entrada por campo:

json
[
{ "codigo": "10004001", "mensagem": "Nota fiscal não encontrada" }
]

codigo es una cadena con el código de error de la plataforma en dígitos, por ejemplo 10003004 para ciudad / estado inválido, 10003008 para contraseña del certificado incorrecta y 10004001 para factura no encontrada.

Familias de verificación y consulta de registro (HTTP 400, y 422 / 428 / 451 / 503 en la consulta de registro): un objeto simple con code y message:

json
{ "code": 10015004, "message": "Invoice not found" }
CampoTipoDescripción
codeintegerCódigo de error de la plataforma
messagestringExplicación legible, localizada

Sobre de la plataforma

Lo usan el endpoint de echo (POST /openapi/demo/echo) en toda respuesta, los endpoints abiertos de NFC-e offline (/openapi/v2/empresas/{empresaId}/nfce-offline y sus rutas hijas) en toda respuesta, el endpoint de descarga de archivos en sus fallos y el gateway de la plataforma para los errores de la capa de autenticación en cualquier endpoint (HTTP 401 / 403 / 429), producidos antes de que la solicitud llegue al endpoint:

json
{ "success": true, "message": "OK", "data": { } }
json
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
CampoTipoPresenciaDescripción
successbooleansiemprefalse en todo error
errorTypeintegeren errorClase del error, vea Tipificación de errores
codeintegeren errorCódigo de error de la plataforma, vea Códigos de error
messagestringsiempreExplicación legible, localizada
dataobject | nullen éxitoCarga del endpoint; no se rellena en errores

En los endpoints abiertos de NFC-e offline los errores de negocio también vuelven con HTTP 200 y success = false; un recurso inexistente vuelve con 404 y la validación de campo con 400. En este grupo verifique siempre success, no solo el estado HTTP.

Manejar ambas formas

Su manejador de errores debe aceptar el sobre y las formas de error simples. Una regla robusta:

  1. Trate HTTP 400 o superior como fallo y, además, success: false cuando el cuerpo sea un sobre.
  2. Interprete el cuerpo como JSON. Si es un array, lea codigo de cada entrada; si es un objeto, lea code.
  3. Ramifique por el código, nunca por el texto de message / mensagem (están localizados).

Tipificación de errores (errorType)

Los errores en sobre llevan un campo errorType que clasifica el origen del fallo:

errorTypeClaseSignificado
1Error de APIRechazo de autenticación, autorización o de negocio por TF Fiscal
2Rechazo de la SEFAZLa autoridad fiscal brasileña rechazó la operación
3Fallo del sistemaFallo inesperado de la plataforma; es seguro reintentar con backoff
4Fallo de validaciónLa validación de los campos de la solicitud falló

Referencia rápida de estados HTTP

HTTPEscenarioForma del cuerpo
200Solicitud aceptada; en la verificación por XML esto incluye una validación fallida (revise el bloque validation)Datos simples, o sin cuerpo
400Solicitud inválida o regla de negocio violada[{codigo, mensagem}] (emisión) o {code, message} (verificación / consulta de registro)
404empresaId / id del documento no encontrado (familia de emisión)[{codigo, mensagem}]
401Fallo de autenticación (token / sign / timestamp), o enlace de descarga inválido o vencidoSobre de la plataforma
403Aplicación deshabilitada / no vigente / integrador deshabilitado / no suscritoSobre de la plataforma
422 / 428 / 451Consulta de CPF retenida por ley (titular de 16 a 17 años / edad no verificable / titular menor de 16); no reintente{code, message}, sin campos personales
429Límite de tasa excedido, o la aplicación está en bloqueo temporal; lleva las cabeceras Retry-After y X-RateLimit-*, vea Límite de tasa y backoffSobre de la plataforma
503Fuente de datos upstream no disponible (consulta de registro, 10016020) o archivo aún no renderizado (descarga, 10009037); reintente tras Retry-After{code, message} o sobre de la plataforma
5xxFallo del lado de la plataformaReintente con backoff; si persiste, contacte a la plataforma con el timestamp y la ruta del fallo

Idempotencia

  • La emisión de NF-e es idempotente por el id de la solicitud que usted genera: reenviar el mismo id reutiliza la tarea original. Si el intento anterior fue denegado (Negada), reenviar el mismo id con los campos corregidos emite de nuevo con la nueva carga, sin necesidad de un nuevo id. Cambiar campos clave como el destinatario mientras el intento anterior sigue en proceso o ya fue autorizado se rechaza con codigo 10004032.
  • La emisión de CT-e y DC-e también es idempotente por id: un mensaje idéntico reutiliza la tarea original, un mensaje distinto bajo el mismo id se rechaza (10017030 para CT-e, 10019030 para DC-e), y un fallo terminal (Falha) reabre la tarea con el nuevo mensaje.
  • La verificación por XML es idempotente por la clave de acceso (chave): reenviar mientras una verificación está en curso devuelve el progreso actual, y los veredictos terminales se reutilizan según su tipo: los de factura cancelada / denegada / inutilizada y aquellos en que la SEFAZ no acepta consultas de la factura se reutilizan mientras la plataforma conserve el registro de la verificación, y los demás durante 24 horas desde el momento en que se obtuvieron; vea Idempotencia y nueva verificación. La reutilización solo aplica a reenvíos con contenido idéntico: si el XML enviado para una chave difiere del anterior, se verifica de nuevo por completo automáticamente (salvo los veredictos de factura cancelada / denegada / inutilizada). Para forzar una nueva verificación, envíe la cabecera forceRevalidate: true en el endpoint de XML (la cabecera no forma parte de la firma); los veredictos de factura cancelada / denegada / inutilizada se reutilizan incluso con esa cabecera. La consulta por chave es un GET fijo y no tiene canal de reverificación; para forzar una nueva verificación, reenvíe por el endpoint de XML. Un REJECTED del nivel 1 no tiene registro de nivel 2; la reverificación exige reenviar el XML.
  • Las entregas de webhook son idempotentes por event_id: cada reintento y cada destino de un mismo evento llevan el mismo valor, así que deduplique por él. Vea Webhooks.

Límite de tasa y backoff

Cuotas en dos niveles y token bucket

Las cuotas se fijan por aplicación y por grupo de endpoints. Una solicitud solo se acepta cuando ambos niveles lo permiten:

NivelAlcanceSi no se fija
AplicaciónTodas las llamadas de la aplicaciónSin límite
Grupo de endpointsLas llamadas de la aplicación a un grupo de endpoints (por ejemplo, los dos endpoints de verificación de NF-e pertenecen al grupo "verificación de facturas")Solo rige el nivel de aplicación

Ambos niveles son token buckets (cubos de tokens):

  • rate: tokens añadidos por segundo, es decir, el número sostenido de solicitudes aceptadas por segundo;
  • burst: capacidad del cubo, es decir, el mayor número de solicitudes que puede enviar seguidas (disponible de nuevo tras un periodo de inactividad); si no se fija, vale 2 × rate;
  • cada solicitud aceptada consume 1 token. Cuando no queda ningún token, la solicitud recibe HTTP 429 (código 10009006); las solicitudes rechazadas no consumen tokens.

Las cuotas concretas se acuerdan con la plataforma al configurar la aplicación. Las descargas de archivos cuentan contra el límite de la aplicación en su propio grupo y no se facturan.

Cabeceras de límite de tasa

En una aplicación con cuota, toda respuesta (tanto 200 como 429) lleva:

CabeceraSignificado
X-RateLimit-LimitEl rate del nivel vigente (solicitudes por segundo)
X-RateLimit-RemainingTokens que quedan en ese nivel (redondeado hacia abajo)
X-RateLimit-BurstEl burst (capacidad del cubo) de ese nivel
X-RateLimit-ResetSegundos hasta que haya un nuevo token (redondeado hacia arriba, mínimo 1); durante un bloqueo temporal, los segundos que faltan para que termine
Retry-AfterSolo en 429: el número mínimo de segundos que hay que esperar. 1 cuando el cubo está vacío; durante un bloqueo temporal, los segundos que faltan para que termine

Cuando ambos niveles tienen cuota, una respuesta aceptada informa del nivel con menos tokens restantes, y un 429 informa del nivel que lo rechazó. Las aplicaciones sin ninguna cuota no reciben estas cabeceras.

Bloqueo temporal

Una aplicación que ignora el 429 y sigue reenviando a un ritmo alto entra en un bloqueo temporal (cooldown):

  • Regla: cuando los rechazos de la aplicación en los últimos 10 segundos alcanzan el umbral, entra en un bloqueo de 30 segundos. El umbral es max(100, 10 × rate), donde rate es el menor entre el de la aplicación y el del grupo de endpoints. Por ejemplo, una aplicación con una cuota de 100/s entra en bloqueo tras 1000 rechazos en 10 segundos, lo mismo que llamar a más del doble de la cuota durante 10 segundos seguidos. Un exceso ocasional no lo dispara.
  • Durante el bloqueo, toda llamada de la aplicación sujeta a cuota recibe 429 (código 10009006) de inmediato y no se procesa. Retry-After y X-RateLimit-Reset llevan los segundos que faltan para que termine el bloqueo y van disminuyendo.
  • El bloqueo termina solo y vuelven las comprobaciones del token bucket; un exceso sostenido dispara otro bloqueo.
  • Estos son los parámetros por defecto; la plataforma puede ajustarlos.

Qué debe hacer su cliente

  1. Al recibir 429, espere Retry-After segundos y reintente;
  2. Si el reintento sigue recibiendo 429, aplique backoff exponencial sobre el Retry-After (por ejemplo 1, 2, 4 segundos… hasta 30 segundos) y añada jitter aleatorio, para que los workers en paralelo no despierten a la vez y vuelvan a chocar;
  3. Regule el ritmo: use X-RateLimit-Remaining para ajustar su tasa de envío y no siga enviando por encima de su cuota;
  4. Una solicitud respondida con 429 no se procesó y debe enviarse de nuevo (con timestamp y sign nuevos).

El 429 no se factura: las llamadas limitadas (incluidas las de un bloqueo temporal) no se cobran.

Otros límites

  • Anti-flood por CNPJ: si una empresa acumula demasiadas tareas de emisión pendientes, los nuevos envíos se rechazan con codigo 10004002; reintente más tarde.
  • Ventana del timestamp: las solicitudes con timestamp fuera de ±300 s del reloj del servidor se rechazan (10009001).
  • 401 y 403 son errores de configuración; reintentarlos sin corregir solo consume cuota.

Localización de las respuestas

Los campos message, mensagem y *Description siguen el idioma de la solicitud: la cabecera Language (zh / en / pt / es) tiene precedencia, luego Accept-Language (admite pt-BR y valores q). Sin cabecera de idioma, las respuestas usan por defecto portugués (pt). Las cabeceras de idioma no forman parte de la firma.

ValorIdiomaObservación
ptPortuguésIdioma por defecto; también se aceptan subetiquetas como pt-BR
enInglésTambién se aceptan subetiquetas como en-US
zhChinoTambién se aceptan subetiquetas como zh-CN
esEspañolTambién se aceptan subetiquetas como es-ES y spa

Sin distinguir mayúsculas. Un valor de Language no reconocido pasa a Accept-Language; si este tampoco se reconoce, la respuesta sale en portugués, sin error.

Las cargas de webhook solo llevan valores de enumeración independientes del idioma; no hay campos *Description en ellas. Para decisiones programáticas use siempre códigos y campos de enumeración (code, codigo, status, validationStatus, errors[].code, situacao.codigo), nunca texto descriptivo.

Horas y tipos de datos

  • Las horas producidas por la plataforma (dataCriacao, dataAutorizacao de los documentos emitidos, occurred_at de webhook, verifiedAt, serverTime del echo) son ISO-8601 UTC con el sufijo Z, en todos los entornos.
  • Las horas extraídas de un documento de terceros por la API de verificación (dataEmissao, dataAutorizacao) se devuelven tal cual, con el desfase horario del documento, por ejemplo 2026-07-23T11:20:05-03:00.
  • La cabecera timestamp de la solicitud es tiempo Unix en segundos, no milisegundos.
  • Los identificadores son cadenas aunque sean numéricos (empresaId, webHookId, event_id), para evitar pérdida de precisión numérica en JavaScript. Trate todos los ids como cadenas opacas; el id de documento que usted genera también es una cadena.
  • Los números de documento (numero) y las series (serie) son cadenas. Los importes y cantidades son números JSON.
  • Las variables de ruta como cnpj, cpf y chave son cadenas solo de dígitos sin caracteres de formato; la fecha de nacimiento del CPF (nascimento) es DDMMYYYY.

La clave de acceso de la NF-e (chave)

La chave de acesso es el identificador nacionalmente único de 44 dígitos de una NF-e. Aparece como chaveAcesso en las respuestas de consulta y verificación y como variable de ruta de la consulta por chave. Su estructura:

PosicionesLongitudCampoSignificado
1 a 22cUFCódigo IBGE del estado emisor (p. ej. 35 = SP)
3 a 64AAMMAño y mes de emisión (AAMM)
7 a 2014CNPJCNPJ del emisor
21 a 222modModelo del documento fiscal (55 = NF-e)
23 a 253serieSerie de la factura
26 a 349nNFNúmero de la factura
351tpEmisTipo de emisión
36 a 438cNFCódigo numérico aleatorio
441cDVDígito verificador (módulo 11)

Notas:

  • Almacene y transmita siempre la chave como una cadena de 44 caracteres (los ceros a la izquierda son significativos).
  • La consulta por chave valida longitud, caracteres y dígito verificador localmente antes de intentar cualquier consulta; una chave malformada devuelve HTTP 400 con el código 10015104.
  • Las claves de CT-e (modelo 57) y DC-e (modelo 99) comparten el mismo diseño de 44 dígitos con su propio valor de mod.

Enlaces de descarga de archivos

Los enlaces de descarga en las respuestas de consulta y en las cargas de callback (linkDanfe, linkDownloadXml, linkDacce y sus equivalentes de CT-e / DC-e) tienen la forma https://api.v2.tffiscal.com/openapi/files/{kind}/{ref}?token=.... No necesitan cabeceras de firma: basta un GET simple que siga la redirección 302. El token está vinculado a la ruta, al integrador y a la aplicación, así que use el enlace exactamente como se devolvió. Los enlaces son válidos 7 días por defecto y cada consulta emite enlaces nuevos; un enlace vencido devuelve 401 con 10009036. Detalles: Descarga de archivos.