统一认证与安全

新版开放 API 采用 HTTPS、AccessKey 请求签名和标准 JSON。无需先获取客户 Token，也无需额外对整个报文进行 SM4 加解密。

1. 凭证和请求头

平台为企业签发 AccessKey ID / Secret，并分别授权查验、同步、开票能力及可操作的税号。Secret 仅保存在调用方服务端；创建时只展示一次。轮换时可新建另一组凭证，完成切换后停用旧凭证。

Content-Type: application/json
Host: open.yifeihuilian.com
X-Access-Key-Id: <AccessKey ID>
X-Timestamp: <Unix 时间戳，单位秒>
X-Nonce: <16–128 位随机字符串>
X-Request-Id: <1–128 位请求 ID>
Authorization: YFHL-HMAC-SHA256 Signature=<64 位小写十六进制签名>

• AccessKey ID 最长 64 位。随机数和请求 ID 仅允许英文字母、数字、下划线及连字符。时间戳与服务端偏差不得超过 300 秒。
• 同一 AccessKey 的随机数在验签窗口内不得重复。网络重试需使用新的时间戳、随机数和签名。
• Idempotency-Key 与 X-YFHL-Channel 是可选签名头，是否使用由接口业务规则决定。查验中心的幂等键使用 1–128 位英文字母、数字、下划线或连字符；请求防重放不等于业务幂等。
• JSON 使用 UTF-8，Content-Type 为 application/json 或 application/json; charset=utf-8，不支持压缩请求体；最大请求体为 16 MiB。
• 必须使用 HTTPS。请求签名保护身份与报文完整性，HTTPS 保护传输内容。

2. 签名规范

建议使用 Node / Python 服务端 SDK 与固定测试向量。JSON 仅序列化一次，签名后发送相同字节；不要重新排版、改变空格或字段顺序。签名算法为 HMAC-SHA256，密钥为 Secret 的 UTF-8 字节，结果编码为小写十六进制。

YFHL-HMAC-SHA256
<METHOD>
<canonical path>
<canonical query>
content-type:application/json
host:open.yifeihuilian.com
idempotency-key:<可选，缺省为空>
x-access-key-id:<AccessKey ID>
x-nonce:<随机数>
x-request-id:<请求 ID>
x-timestamp:<Unix 秒>
x-yfhl-channel:<可选，缺省为空>

content-type;host;idempotency-key;x-access-key-id;x-nonce;x-request-id;x-timestamp;x-yfhl-channel
<SHA256(实际发送的请求体字节)，小写 hex>

上述 8 个头名称固定、小写且按展示顺序排列。每行是“名称:去除首尾空格的值”并以换行结束；可选头缺失时值为空。头区末尾的换行必须保留，因此签名头名单前有一个空行。禁止重复头和控制字符。

• 路径：按斜杠分段，严格 UTF-8 解码后按 RFC3986 编码；仅保留字母、数字与 -._~，百分号编码使用大写十六进制。保留空段与末尾斜杠。
• 拒绝点路径段、编码后的斜杠或反斜杠、控制字符、无效百分号编码和非法 UTF-8。URL 不得包含片段。
• 业务 JSON 地址不使用查询参数；签名算法仍保留通用查询串规范，以兼容历史调用和固定向量：+ 解码为空格，键和值分别按 RFC3986 编码，再按编码后的键、值排序，保留重复项与空值。空格编码为 %20。
• Host 使用实际访问的公网域名，包含非默认端口；反向代理必须保留该值。业务参数与响应字段保持接口自己的定义。

3. 响应与错误

{
  "code": "OK",
  "message": "成功",
  "request_id": "req_example_001",
  "data": {}
}

HTTP 状态码表达处理结果的大类；稳定的英文 code 用于程序判断；message 用于展示；request_id 用于定位问题。错误响应的 data 为 null，不返回内部堆栈。详情见 错误码。

二维码图片是连接接口返回的短期资源，按返回地址直接获取 PNG，不套 JSON 信封，也不向浏览器提供企业 Secret。