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 endpoints | Forma de éxito |
|---|---|
| Registro de empresa, registro de webhook | Objeto simple ({ "empresaId": ... }, { "webHookId": ... }) |
| Vinculación de certificado, emisión y cancelación de NF-e / CT-e / DC-e | HTTP 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 eventos | Objeto simple: el documento, el protocolo o la lista de eventos |
| Verificación por XML, consulta por chave | Objeto simple: la factura interpretada (la verificación por XML añade el bloque validation) |
| Consulta de CNPJ, consulta de CPF | Objeto 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:
[{ "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:
{ "code": 10015004, "message": "Invoice not found" }
| Campo | Tipo | Descripción |
|---|---|---|
code | integer | Código de error de la plataforma |
message | string | Explicació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:
{ "success": true, "message": "OK", "data": { } }
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
| Campo | Tipo | Presencia | Descripción |
|---|---|---|---|
success | boolean | siempre | false en todo error |
errorType | integer | en error | Clase del error, vea Tipificación de errores |
code | integer | en error | Código de error de la plataforma, vea Códigos de error |
message | string | siempre | Explicación legible, localizada |
data | object | null | en éxito | Carga 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:
- Trate HTTP 400 o superior como fallo y, además,
success: falsecuando el cuerpo sea un sobre. - Interprete el cuerpo como JSON. Si es un array, lea
codigode cada entrada; si es un objeto, leacode. - 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:
| errorType | Clase | Significado |
|---|---|---|
| 1 | Error de API | Rechazo de autenticación, autorización o de negocio por TF Fiscal |
| 2 | Rechazo de la SEFAZ | La autoridad fiscal brasileña rechazó la operación |
| 3 | Fallo del sistema | Fallo inesperado de la plataforma; es seguro reintentar con backoff |
| 4 | Fallo de validación | La validación de los campos de la solicitud falló |
Referencia rápida de estados HTTP
| HTTP | Escenario | Forma del cuerpo |
|---|---|---|
| 200 | Solicitud aceptada; en la verificación por XML esto incluye una validación fallida (revise el bloque validation) | Datos simples, o sin cuerpo |
| 400 | Solicitud inválida o regla de negocio violada | [{codigo, mensagem}] (emisión) o {code, message} (verificación / consulta de registro) |
| 404 | empresaId / id del documento no encontrado (familia de emisión) | [{codigo, mensagem}] |
| 401 | Fallo de autenticación (token / sign / timestamp), o enlace de descarga inválido o vencido | Sobre de la plataforma |
| 403 | Aplicación deshabilitada / no vigente / integrador deshabilitado / no suscrito | Sobre de la plataforma |
| 422 / 428 / 451 | Consulta 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 |
| 429 | Lí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 backoff | Sobre de la plataforma |
| 503 | Fuente 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 |
| 5xx | Fallo del lado de la plataforma | Reintente 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
idde la solicitud que usted genera: reenviar el mismoidreutiliza la tarea original. Si el intento anterior fue denegado (Negada), reenviar el mismoidcon 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 concodigo10004032. - 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 mismoidse rechaza (10017030para CT-e,10019030para 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 cabeceraforceRevalidate: trueen 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. UnREJECTEDdel 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:
| Nivel | Alcance | Si no se fija |
|---|---|---|
| Aplicación | Todas las llamadas de la aplicación | Sin límite |
| Grupo de endpoints | Las 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, vale2 × 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:
| Cabecera | Significado |
|---|---|
X-RateLimit-Limit | El rate del nivel vigente (solicitudes por segundo) |
X-RateLimit-Remaining | Tokens que quedan en ese nivel (redondeado hacia abajo) |
X-RateLimit-Burst | El burst (capacidad del cubo) de ese nivel |
X-RateLimit-Reset | Segundos hasta que haya un nuevo token (redondeado hacia arriba, mínimo 1); durante un bloqueo temporal, los segundos que faltan para que termine |
Retry-After | Solo 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), donderatees 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-AfteryX-RateLimit-Resetllevan 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
- Al recibir 429, espere
Retry-Aftersegundos y reintente; - 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; - Regule el ritmo: use
X-RateLimit-Remainingpara ajustar su tasa de envío y no siga enviando por encima de su cuota; - Una solicitud respondida con 429 no se procesó y debe enviarse de nuevo (con
timestampysignnuevos).
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
codigo10004002; reintente más tarde. - Ventana del timestamp: las solicitudes con
timestampfuera 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.
| Valor | Idioma | Observación |
|---|---|---|
pt | Portugués | Idioma por defecto; también se aceptan subetiquetas como pt-BR |
en | Inglés | También se aceptan subetiquetas como en-US |
zh | Chino | También se aceptan subetiquetas como zh-CN |
es | Español | Tambié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,dataAutorizacaode los documentos emitidos,occurred_atde webhook,verifiedAt,serverTimedel echo) son ISO-8601 UTC con el sufijoZ, 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 ejemplo2026-07-23T11:20:05-03:00. - La cabecera
timestampde 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; elidde 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,cpfychaveson cadenas solo de dígitos sin caracteres de formato; la fecha de nacimiento del CPF (nascimento) esDDMMYYYY.
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:
| Posiciones | Longitud | Campo | Significado |
|---|---|---|---|
| 1 a 2 | 2 | cUF | Código IBGE del estado emisor (p. ej. 35 = SP) |
| 3 a 6 | 4 | AAMM | Año y mes de emisión (AAMM) |
| 7 a 20 | 14 | CNPJ | CNPJ del emisor |
| 21 a 22 | 2 | mod | Modelo del documento fiscal (55 = NF-e) |
| 23 a 25 | 3 | serie | Serie de la factura |
| 26 a 34 | 9 | nNF | Número de la factura |
| 35 | 1 | tpEmis | Tipo de emisión |
| 36 a 43 | 8 | cNF | Código numérico aleatorio |
| 44 | 1 | cDV | Dí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.
