快速开始
通用约定
两种响应格式(无包装响应与平台统一响应体)、错误格式、错误分类、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。请求体字段校验失败时每个字段一条:
[{ "codigo": "10004001", "mensagem": "Nota fiscal não encontrada" }]
codigo 为字符串,内容是平台错误码的数字,例如城市 / 州不合法为 10003004、证书密码不符为 10003008、发票不存在为 10004001。
验证族与身份核验族(HTTP 400,身份核验另有 422 / 428 / 451 / 503):含 code 与 message 的无包装 JSON 对象:
{ "code": 10015004, "message": "Invoice not found" }
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 平台错误码 |
message | string | 人类可读说明,已本地化 |
平台统一响应体
用于联调回显端点(POST /openapi/demo/echo)的全部响应、NFC-e 离线开票开放接口(/openapi/v2/empresas/{empresaId}/nfce-offline 及其下级路径)的全部响应、文件下载端点的失败响应,以及平台网关在任意端点上产出的鉴权层错误(HTTP 401 / 403 / 429),后者在请求到达端点之前产生:
{ "success": true, "message": "OK", "data": { } }
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
| 字段 | 类型 | 出现性 | 说明 |
|---|---|---|---|
success | boolean | 恒有 | 所有错误恒为 false |
errorType | integer | 错误时 | 错误分类,见错误分类 |
code | integer | 错误时 | 平台错误码,见错误码 |
message | string | 恒有 | 人类可读说明,已本地化 |
data | object | null | 成功时 | 端点载荷;错误时不填充 |
NFC-e 离线开票开放接口的业务错误同样返回 HTTP 200,success 为 false;资源不存在返回 404,字段校验失败返回 400。调用这组接口时须检查 success,不能只看 HTTP 状态。
兼容两种格式
错误处理必须同时接受统一响应体与无包装的错误格式。稳妥做法:
- 把 HTTP 400 及以上视为失败;响应为统一响应体时,
success: false也视为失败。 - 把响应体按 JSON 解析。是数组则逐项读取
codigo;是对象则读取code。 - 按错误码分支,永远不要按
message/mensagem文案分支(它们会本地化)。
错误分类(errorType)
统一响应体的错误带 errorType 字段,标明失败来源:
| errorType | 分类 | 含义 |
|---|---|---|
| 1 | API 错误 | TF Fiscal 的鉴权、授权或业务拒绝 |
| 2 | SEFAZ 驳回 | 巴西税务机关拒绝了该操作 |
| 3 | 系统异常 | 平台意外故障;可退避重试 |
| 4 | 字段校验失败 | 请求字段校验未通过 |
HTTP 状态速查
| HTTP | 场景 | 响应格式 |
|---|---|---|
| 200 | 请求已受理;XML 验证时含校验不通过(看 validation 块) | 业务数据(无包装),或无响应体 |
| 400 | 请求非法或违反业务规则 | [{codigo, mensagem}](开票)或 {code, message}(验证 / 身份核验) |
| 404 | empresaId / 凭证 id 不存在(开票族) | [{codigo, mensagem}] |
| 401 | 鉴权失败(token / sign / timestamp),或下载链接无效 / 过期 | 平台统一响应体 |
| 403 | 应用停用 / 未生效 / 集成商停用 / 未订阅 | 平台统一响应体 |
| 422 / 428 / 451 | CPF 查询依法拦截(持有人 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。上一次仍在处理或已授权时改动收件人等关键字段重提,则以codigo10004032拒绝。 - 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为冷却剩余秒数,随时间递减。 - 冷却到期自动恢复,重新按令牌桶判定;再次持续超额会再次冷却。
- 以上为缺省参数,平台可能调整。
客户端处理
- 收到 429 先按
Retry-After等待,再重试; - 重试仍是 429 时,在
Retry-After的基础上做指数退避(例如 1、2、4 秒……封顶 30 秒)并加随机抖动,避免多个线程同时醒来再撞一次; - 平滑调用:参考
X-RateLimit-Remaining控制发送节奏,不要以超过额度的速率持续发送; - 被 429 的请求没有被处理,需要重新提交(重新生成
timestamp与sign)。
429 不计费:被限流的调用(含冷却期内)不计费。
其他限制
- CNPJ 级防洪:主体待处理开票任务积压过多时,新提交以
codigo10004002拒绝;稍后重试。 - 时间戳窗口:
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 至 2 | 2 | cUF | 开票州的 IBGE 代码(如 35 = SP) |
| 3 至 6 | 4 | AAMM | 开票年月(YYMM) |
| 7 至 20 | 14 | CNPJ | 开票方 CNPJ |
| 21 至 22 | 2 | mod | 税务凭证模型(55 = NF-e) |
| 23 至 25 | 3 | serie | 发票系列 |
| 26 至 34 | 9 | nNF | 发票号 |
| 35 | 1 | tpEmis | 开票方式 |
| 36 至 43 | 8 | cNF | 随机数字码 |
| 44 | 1 | cDV | 校验位(模 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。详见文件下载。
