Convenciones generales

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:

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": "NFe0001", "mensagem": "A Nota fiscal nao foi encontrada. Por favor, verifique se o id foi informado corretamente" }
]

codigo es una cadena: los tres códigos GW001 (ciudad / estado inválido), CER0005 (contraseña del certificado incorrecta) y NFe0001 (factura no encontrada) conservan sus valores alfanuméricos, igual que los códigos DCe* de la familia DC-e; todas las demás entradas llevan el código de error de la plataforma como cadena numérica.

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

Sobre de la plataforma

Lo usan el endpoint de echo (POST /openapi/demo/echo) 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" }

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:

Referencia rápida de estados HTTP

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 durante 24 horas. 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). 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

• Cuota por aplicación: excederla devuelve HTTP 429 con el código 10009006. Los límites se aplican por aplicación y por grupo de endpoints. Retroceda y reintente (empiece en 1 s, duplique hasta 30 s, añada jitter) y suavice su tasa de llamadas.
• Anti-flood por CNPJ: si una empresa acumula demasiadas tareas de emisión pendientes, los nuevos envíos se rechazan con codigo 10004002 hasta que la cola se vacíe; reintente más tarde.
• Ventana del timestamp: las solicitudes con timestamp fuera de ±300 s del reloj del servidor se rechazan (10009001), lo que también limita el replay de solicitudes capturadas.
• 401 y 403 son errores de configuración; reintentarlos sin corregir solo consume cuota.
• Las descargas de archivos cuentan contra el límite de la aplicación en su propio grupo y no se facturan.

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.

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:

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.