TF Fiscal
开发文档

快速开始

通用约定

两种响应格式(无包装响应与平台统一响应体)、错误格式、错误分类、HTTP 状态速查、幂等、限流、本地化、数据类型、NF-e 访问密钥结构与文件下载链接。

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

响应格式

API 有两种响应格式,收到哪一种取决于端点以及产生响应的层。

无包装响应(标准端点)

全部标准端点(开票主体、NF-e、CT-e、DC-e、验证、身份核验、Webhook 注册)的响应都不带统一响应体包装:

端点组成功响应格式
主体注册、Webhook 注册无包装对象({ "empresaId": ... }、{ "webHookId": ... })
证书关联、NF-e / CT-e / DC-e 开票与取消HTTP 200 无响应体;结果异步到达
NF-e / CT-e / DC-e 查询、更正函与事件登记无包装对象:凭证、协议号或事件列表
XML 验证、chave 查询无包装对象:解析后的票面(XML 验证额外带 validation 块)
CNPJ 查询、CPF 查询无包装对象:登记记录

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

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

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

codigo 为字符串,内容是平台错误码的数字,例如城市 / 州不合法为 10003004、证书密码不符为 10003008、发票不存在为 10004001。

验证族与身份核验族(HTTP 400,身份核验另有 422 / 428 / 451 / 503):含 code 与 message 的无包装 JSON 对象:

json
{ "code": 10015004, "message": "Invoice not found" }
字段类型说明
codeinteger平台错误码
messagestring人类可读说明,已本地化

平台统一响应体

用于联调回显端点(POST /openapi/demo/echo)的全部响应、NFC-e 离线开票开放接口(/openapi/v2/empresas/{empresaId}/nfce-offline 及其下级路径)的全部响应、文件下载端点的失败响应,以及平台网关在任意端点上产出的鉴权层错误(HTTP 401 / 403 / 429),后者在请求到达端点之前产生:

json
{ "success": true, "message": "OK", "data": { } }
json
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
字段类型出现性说明
successboolean恒有所有错误恒为 false
errorTypeinteger错误时错误分类,见错误分类
codeinteger错误时平台错误码,见错误码
messagestring恒有人类可读说明,已本地化
dataobject | null成功时端点载荷;错误时不填充

NFC-e 离线开票开放接口的业务错误同样返回 HTTP 200,success 为 false;资源不存在返回 404,字段校验失败返回 400。调用这组接口时须检查 success,不能只看 HTTP 状态。

兼容两种格式

错误处理必须同时接受统一响应体与无包装的错误格式。稳妥做法:

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

错误分类(errorType)

统一响应体的错误带 errorType 字段,标明失败来源:

errorType分类含义
1API 错误TF Fiscal 的鉴权、授权或业务拒绝
2SEFAZ 驳回巴西税务机关拒绝了该操作
3系统异常平台意外故障;可退避重试
4字段校验失败请求字段校验未通过

HTTP 状态速查

HTTP场景响应格式
200请求已受理;XML 验证时含校验不通过(看 validation 块)业务数据(无包装),或无响应体
400请求非法或违反业务规则[{codigo, mensagem}](开票)或 {code, message}(验证 / 身份核验)
404empresaId / 凭证 id 不存在(开票族)[{codigo, mensagem}]
401鉴权失败(token / sign / timestamp),或下载链接无效 / 过期平台统一响应体
403应用停用 / 未生效 / 集成商停用 / 未订阅平台统一响应体
422 / 428 / 451CPF 查询依法拦截(持有人 16 到 17 岁 / 年龄无法核实 / 持有人小于 16 岁);勿重试{code, message},无人员字段
429超出限流额度或应用处于冷却期;带 Retry-After 与 X-RateLimit-* 响应头,见限流与退避平台统一响应体
503上游数据源不可用(身份核验,10016020)或文件尚未生成(下载,10009037);按 Retry-After 重试{code, message} 或平台统一响应体
5xx平台侧故障退避重试;持续失败请携带失败请求的 timestamp 与路径联系平台

幂等

  • NF-e 开票以你生成的请求 id 为幂等键:同一 id 重复提交复用原任务。若上一次开票被驳回(Negada),同一 id 修正字段后重提会按新报文重新开票,无需换 id。上一次仍在处理或已授权时改动收件人等关键字段重提,则以 codigo 10004032 拒绝。
  • CT-e 与 DC-e 开票同样以 id 为幂等键:报文相同复用原任务,同一 id 报文不同则拒绝(CT-e 为 10017030,DC-e 为 10019030),终态失败(Falha)后重提会用新报文重开任务。
  • XML 验证以访问密钥(chave)为幂等键:验证进行中重复提交返回当前进度;终态结论按类别复用:已取消 / 已否决 / 已作废与 SEFAZ 不受理查询的结论在平台保留验证记录期间一直复用,其他结论自得出之时起 24 小时内复用,见 幂等与重验。复用只针对内容完全相同的重复提交:同一 chave 提交的 XML 内容与上一次不同时,自动完整重新验证(已取消 / 已否决 / 已作废的结论除外)。需强制重验时,在 XML 端点加请求头 forceRevalidate: true(该头不参与签名),已取消 / 已否决 / 已作废的结论带该头也照样复用。chave 查询为固定 GET,无重验通道;需强制重验请走 XML 端点重新提交。一级 REJECTED 无二级记录,重验须重新提交 XML。
  • Webhook 投递以 event_id 为幂等键:同一事件的所有重试与多目标扇出共用同值,接收方据此去重。见 Webhooks。

限流与退避

两级额度与令牌桶

额度按应用、按接口组设置,两级都满足才受理:

级约束范围未设置时
应用总闸该应用的全部对外调用不限
接口组该应用对某一组接口的调用(如 NF-e 验证的两个端点同属「发票验证」组)只受应用总闸约束

两级都是令牌桶:

  • rate:每秒补充的令牌数,即长期平均每秒可受理的请求数;
  • burst:桶容量,即短时间内最多能连发的请求数(闲置一段时间后可一次用掉),未单独设置时为 2 × rate;
  • 每受理一个请求消耗 1 枚令牌;令牌不够即返回 HTTP 429(错误码 10009006),被拒的请求不消耗令牌。

具体额度在开通应用时与平台约定。文件下载计入应用总闸并单列接口组,不计费。

限流响应头

设置了额度的应用,每个响应(200 与 429 都有)都带:

响应头含义
X-RateLimit-Limit生效那一级的 rate(个/秒)
X-RateLimit-Remaining生效那一级当前剩余的令牌数(向下取整)
X-RateLimit-Burst生效那一级的 burst(桶容量)
X-RateLimit-Reset还要多少秒才有下一枚令牌(向上取整,最小 1);冷却期内为冷却剩余秒数
Retry-After只在 429 时出现:建议至少等待的秒数。令牌不够时为 1;冷却期内为冷却剩余秒数

两级都有额度时,放行响应取剩余令牌更少的那一级,429 取拒绝的那一级。没有设置任何额度的应用不带这些头。

冷却

不理会 429、持续高频重发的应用会被暂时冷却:

  • 规则:同一应用最近 10 秒内被拒的次数达到阈值,即进入 30 秒冷却。阈值为 max(100, 10 × rate),rate 取应用总闸与接口组里较小的那个。例如额度 100/s 的应用,10 秒内被拒 1,000 次进入冷却,相当于持续以额度两倍以上的速度调用 10 秒;偶尔超出一下不会触发。
  • 冷却期内,该应用设有额度的调用一律直接返回 429(错误码 10009006),请求不会被处理;Retry-After 与 X-RateLimit-Reset 为冷却剩余秒数,随时间递减。
  • 冷却到期自动恢复,重新按令牌桶判定;再次持续超额会再次冷却。
  • 以上为缺省参数,平台可能调整。

客户端处理

  1. 收到 429 先按 Retry-After 等待,再重试;
  2. 重试仍是 429 时,在 Retry-After 的基础上做指数退避(例如 1、2、4 秒……封顶 30 秒)并加随机抖动,避免多个线程同时醒来再撞一次;
  3. 平滑调用:参考 X-RateLimit-Remaining 控制发送节奏,不要以超过额度的速率持续发送;
  4. 被 429 的请求没有被处理,需要重新提交(重新生成 timestamp 与 sign)。

429 不计费:被限流的调用(含冷却期内)不计费。

其他限制

  • CNPJ 级防洪:主体待处理开票任务积压过多时,新提交以 codigo 10004002 拒绝;稍后重试。
  • 时间戳窗口:timestamp 与服务器时钟偏差超 ±300 秒的请求被拒绝(10009001)。
  • 401 与 403 属配置错误,不修复就重试只会消耗配额。

响应本地化

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

取值语言说明
pt葡萄牙语缺省语言;pt-BR 等子标签同样认
en英语en-US 等子标签同样认
zh中文zh-CN 等子标签同样认
es西班牙语es-ES 等子标签与 spa 同样认

不区分大小写。Language 头取值无法识别时改看 Accept-Language,仍无法识别则按葡语返回,不报错。

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 查询的路径变量。结构如下:

位置长度字段含义
1 至 22cUF开票州的 IBGE 代码(如 35 = SP)
3 至 64AAMM开票年月(YYMM)
7 至 2014CNPJ开票方 CNPJ
21 至 222mod税务凭证模型(55 = NF-e)
23 至 253serie发票系列
26 至 349nNF发票号
351tpEmis开票方式
36 至 438cNF随机数字码
441cDV校验位(模 11)

说明:

  • 始终以 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。详见文件下载。