通用约定

TF Fiscal 开放 API 各端点共用的约定。

响应形状

API 有两种响应形状，收到哪一种取决于端点以及产生响应的层。

裸响应（标准端点）

全部标准端点（开票主体、NF-e、CT-e、DC-e、验证、身份核验、Webhook 注册）都不带信封响应：

标准端点的业务与请求级错误按端点族分为两种错误形状。

开票族（开票主体、NF-e、CT-e、DC-e、Webhook 注册；HTTP 400 / 404）：错误数组，每项含 codigo 与 mensagem。请求体字段校验失败时每个字段一条：

[
  { "codigo": "NFe0001", "mensagem": "A Nota fiscal nao foi encontrada. Por favor, verifique se o id foi informado corretamente" }
]

codigo 为字符串：GW001（城市 / 州不合法）、CER0005（证书密码不符）、NFe0001（发票不存在）三个原码沿用字母数字取值，DC-e 族的 DCe* 码也是如此；其余各项均为平台错误码数字串。

验证族与身份核验族（HTTP 400，身份核验另有 422 / 428 / 451 / 503）：含 code 与 message 的裸对象：

{ "code": 10015004, "message": "Invoice not found" }

平台信封

用于联调回显端点（POST /openapi/demo/echo）的全部响应、文件下载端点的失败响应，以及平台网关在任意端点上产出的鉴权层错误（HTTP 401 / 403 / 429），后者在请求到达端点之前产生：

{ "success": true, "message": "OK", "data": { } }

{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }

兼容两种形状

错误处理必须同时接受信封与裸错误形状。稳妥做法：

1. 把 HTTP 400 及以上视为失败；响应体是信封时，success: false 也视为失败。
2. 把响应体按 JSON 解析。是数组则逐项读取 codigo；是对象则读取 code。
3. 按错误码分支，永远不要按 message / mensagem 文案分支（它们会本地化）。

错误分类（errorType）

信封错误带 errorType 字段，标明失败来源：

HTTP 状态速查

幂等

• NF-e 开票以你生成的请求 id 为幂等键：同一 id 重复提交复用原任务。若上一次开票被驳回（Negada），同一 id 修正字段后重提会按新报文重新开票，无需换 id。上一次仍在处理或已授权时改动收件人等关键字段重提，则以 codigo 10004032 拒绝。
• CT-e 与 DC-e 开票同样以 id 为幂等键：报文相同复用原任务，同一 id 报文不同则拒绝（CT-e 为 10017030，DC-e 为 10019030），终态失败（Falha）后重提会用新报文重开任务。
• XML 验证以访问密钥（chave）为幂等键：验证进行中重复提交返回当前进度，终态结论 24 小时内复用。需强制重验时，在 XML 端点加请求头 forceRevalidate: true（该头不参与签名）。chave 查询为固定 GET，无重验通道；需强制重验请走 XML 端点重新提交。一级 REJECTED 无二级记录，重验须重新提交 XML。
• Webhook 投递以 event_id 为幂等键：同一事件的所有重试与多目标扇出共用同值，接收方据此去重。见 Webhooks。

限流与退避

• 应用级配额：超出返回 HTTP 429 与错误码 10009006。限流按应用与接口组两级实施。退避重试（初始 1 秒，倍增至 30 秒上限，加抖动）并平滑调用频率。
• CNPJ 级防洪：主体待处理开票任务积压过多时，新提交以 codigo 10004002 拒绝，直到队列消化；稍后重试。
• 时间戳窗口：timestamp 与服务器时钟偏差超 ±300 秒的请求被拒绝（10009001），这也限制了被截获请求的重放。
• 401 与 403 属配置错误，不修复就重试只会消耗配额。
• 文件下载计入应用总闸并单列接口组，不计费。

响应本地化

message、mensagem 与 *Description 字段随请求语言返回：Language 头（zh / en / pt / es）优先，其次 Accept-Language（支持 pt-BR 与 q 值）。未提供语言头时默认葡语（pt）。语言头不参与签名。

Webhook 载荷只携带语言无关的枚举值，其中没有 *Description 字段。程序判断一律使用错误码与枚举字段（code、codigo、status、validationStatus、errors[].code、situacao.codigo），永远不要匹配描述文案。

时间与数据类型

• 平台产生的时间（已开凭证的 dataCriacao、dataAutorizacao，Webhook 的 occurred_at、verifiedAt，echo 的 serverTime）均为带 Z 后缀的 ISO-8601 UTC，与环境无关。
• 验证 API 从第三方凭证解析出的时间（dataEmissao、dataAutorizacao）原样返回并保留凭证自带的时区偏移，例如 2026-07-23T11:20:05-03:00。
• 请求头 timestamp 是 Unix 秒级时间，不是毫秒。
• 标识符即使是数字也一律为字符串（empresaId、webHookId、event_id），以避免 JavaScript 数字精度丢失。把所有 id 当作不透明字符串；你生成的凭证 id 同样是字符串。
• 凭证号（numero）与系列（serie）为字符串。金额与数量为 JSON 数字。
• cnpj、cpf、chave 等路径变量为纯数字字符串，不含格式符；CPF 出生日期（nascimento）为 DDMMYYYY。

NF-e 访问密钥（chave）

chave de acesso 是 NF-e 全国唯一的 44 位标识。它在查询与验证响应中以 chaveAcesso 出现，也是 chave 查询的路径变量。结构如下：

说明：

• 始终以 44 字符的字符串存储与传输 chave（前导零有意义）。
• chave 查询在发起任何查询之前先本地校验长度、字符与校验位；chave 非法返回 HTTP 400 与错误码 10015104。
• CT-e（模型 57）与 DC-e（模型 99）的密钥沿用同样的 44 位布局，只是 mod 取值不同。

文件下载链接

查询响应与回调载荷中的下载链接（linkDanfe、linkDownloadXml、linkDacce 及其 CT-e / DC-e 对应字段）形如 https://api.v2.tffiscal.com/openapi/files/{kind}/{ref}?token=...。它们不需要签名头：直接 GET 并跟随 302 跳转即可。令牌与路径、集成商、应用绑定，请原样使用返回的链接。链接默认 7 天有效，每次查询都重新签发；过期链接返回 401 与 10009036。详见文件下载。