术语对照表

接口文档难免要用一些行业术语。这一页把本站出现过的术语都翻译成大白话， 拿不准某个词的意思时，回到这里查一眼即可。

流程相关

术语	大白话	在本文档里的意思
回调（Callback / Webhook）	平台主动「打电话」通知你	采集有结果时，平台向你提供的 callback_url 发一个 HTTP POST，你不用反复来问
轮询	每隔一段时间来问一次	定时调用状态查询接口看结果出来没有；间隔不得低于 15 秒
兜底	备用手段、保险措施	回调是主要方式，轮询只在没收到回调时顶上
终态	不会再变的最终状态	订单到了 SUCCESS / ERROR、产品到了 SUCCEEDED / FAILED / SKIPPED，就不会再变了；「终态回调」就是宣告最终结果的那条通知
授权轮次（代次）	用户第几次完成授权	每次用户重新登录税局授权，都会产生一个新的 authorization_code；同一轮里平台自己的重试不算新轮次
端到端	从头到尾完整走一遍	从创建授权链接一直做到取回数据，中间不跳过任何环节

防重复与重试

术语	大白话	在本文档里的意思
幂等	同一件事做多少遍，效果都只算一次	同一个请求因为超时、重试被发了好几遍，平台也只创建一笔授权、你也只入库一条记录
幂等键 / 去重键	用来认出「这是同一件事」的字段	创建授权看 external_order_id，回调看 event_id，发票分页看 orderNo + pageNum
去重	重复来的只处理第一次	收到重复回调时直接确认返回，不再改业务状态
重放	把截获到的请求原样再发一遍（一种攻击）	平台用 Nonce 挡住：同一个 Nonce 十分钟内只认一次
Nonce	一次性随机串	每个签名请求都要现生成一个新的（推荐 UUID），用过即作废
指数退避	失败后越等越久再重试	第一次等 2 秒，之后 4 秒、8 秒……避免把对方打垮

报文与数据

术语	大白话	在本文档里的意思
业务码信封	HTTP 层永远说 200，成败写在包裹里	/api/channel/data/* 的响应外层固定 HTTP 200，真正结果看 success 与 code
验签（验证签名）	核对暗号，确认消息真是对方发的、没被改过	用 Callback Secret 对报文原始字节算 HMAC-SHA256，和请求头里的签名比对
HMAC 签名	用共享密钥算出来的防伪校验码	双方各自计算、结果一致才放行；密钥不在网络上传输
游标（cursor）	书签，记着「上次拉到哪了」	每批响应给出 nextCursor，下次带上它接着拉，不重不漏
分片	大文件切成的小块	PACKAGE 模式把全部发票切成若干 gzip 块，逐块下载、校验、合并
快照	某一时刻定格的数据副本	采集完成时定格一份数据，之后分页、游标都基于它，翻页途中数据不会变
断点续传	下载中断后从断的地方继续	下载接口支持 Accept-Ranges: bytes，不必从头再下
入库 / 落库	把数据保存进自己的数据库	本站已尽量写作「保存」「入库」
透传	原样传递，不加工	发票 ALL 把税局源表的列原样保留给你
artifacts（制品）	采集产出的文件	Worker 原始表格等文件在响应的 artifacts 清单里，含下载地址与校验值
SHA-256 校验	给文件算「指纹」核对完整性	下载后自己算一遍哈希，与平台给的值一致才算下载完好

安全相关

术语	大白话	在本文档里的意思
鉴权	确认「你是谁、有没有资格调这个接口」	API Key 证明渠道身份；HMAC 签名证明请求没被篡改
国密 SM4	中国国家标准的对称加密算法	开启 output_encryption=SM4 后，成功响应与回调整体加密成固定的「信封」结构
信封（加密信封）	装着密文和解密所需参数的固定 JSON 结构	含 iv、ciphertext、tag 等字段，见 SM4 输出加密
密钥派生	从一个秘密算出另一个密钥	SM4 密钥取 SHA-256(Callback Secret) 的前 16 字节，不用另发一把钥匙
签名链接	自带「通行证」的下载地址	链接里带 expires 与 signature，有效期内拿到链接就能下载，不需要再带请求头

还有看不懂的词？

如果正文里还有让你卡住的表述，请反馈给平台对接人，我们会继续把它改得更直白。