术语对照表

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

流程相关

术语	大白话	在本文档里的意思
回调（Callback / Webhook）	平台主动「打电话」通知你	采集有结果时，平台向你提供的 callback_url 发一个 HTTP POST，你不用反复来问
轮询	每隔一段时间来问一次	定时调用状态查询接口看结果出来没有；间隔不得低于 15 秒
兜底	备用手段、保险措施	回调是主要方式，轮询只在没收到回调时顶上
终态	不会再变的最终状态	这些状态表示当前授权或执行批次结束；后续明确重试可进入新批次，不能把旧批次通知覆盖到新批次
授权轮次（代次）	用户第几次完成授权	只有平台创建新授权代次时 authorization_code 才变化；原页面重新录入凭据可沿用授权和 job_id，仅 attempt_id 变化
端到端	从头到尾完整走一遍	从创建授权链接一直做到取回数据，中间不跳过任何环节

防重复与重试

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

报文与数据

术语	大白话	在本文档里的意思
业务码信封	在 HTTP 200 中继续区分业务成败	先处理非 2xx 的鉴权、权限和交付异常；HTTP 200 再看 success 与 code
验签（验证签名）	核对暗号，确认消息真是对方发的、没被改过	用 Callback Secret 对报文原始字节算 HMAC-SHA256，和请求头里的签名比对
HMAC 签名	用共享密钥算出来的防伪校验码	双方各自计算、结果一致才放行；密钥不在网络上传输
游标（cursor）	书签，记着「上次拉到哪了」	每批响应给出 nextCursor，下次带上它接着拉，不重不漏
分片	大文件切成的小块	PACKAGE 模式把全部发票切成若干 gzip 块，逐块下载、校验、合并
快照	某一批次固定的数据副本	税务分页交付、发票游标和分片包绑定各自快照；普通发票页码分页不接受快照标识，不能假定跨批次或字段版本切换后仍是同一份数据
断点续传	下载中断后从断的地方继续	支持 Accept-Ranges: bytes 的文件可使用 Range；保留在线 HTML 下载返回完整文件，税务 SM4 大记录使用 chunkIndex 分块读取
入库 / 落库	把数据保存进自己的数据库	本站已尽量写作「保存」「入库」
透传	原样传递，不加工	发票 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，有效期内拿到链接就能下载，不需要再带请求头

还有看不懂的词？

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