税号匹配

API接入说明

先在本页生成调用密钥，再由你的程序后端发送商品资料。无需提供网站密码或GPT密钥。

1. 请求地址

POST https://ppsh.surilegeyongdewangzhansheiheiwosheishabi.com/api/tax-match

Authorization: Bearer tax_你的调用密钥
Content-Type: application/json

规则选择（每次请求必填）

接口地址固定，使用哪套规则由JSON里的 rule_set 决定，API密钥不代表规则。顺丰国际必须传 sf-international。每次请求只适用一套规则，不同路线请拆开调用。

缺少、留空或填写未开通的规则，返回HTTP 400，不自动切换或使用默认规则。新增路线后请按文档选择对应标识。

收到HTTP 200后，必须核对响应头 X-Rule-Set 与请求的 rule_set 完全一致，不一致时停止使用结果。X-Rule-Version 是本次基础规则版本；人工修正实时共享，不单独改变该版本号。保存修正或发布基础规则后，后续调用自动使用更新，无需换地址或密钥。

2. 提交的数据

{
  "rule_set": "sf-international",
  "items": [
    {"or_no":"OR001","user_name":"毛绒挂件","user_tax_code":"25000000"},
    {"or_no":"OR002","user_name":"漫画2本","user_tax_code":"17010000"}
  ],
  "format":"json",
  "reference":"批次001"
}

3. 附带图片（可选）

把图片转成Base64，加入同一个请求。例如下面的图片对应第一项商品：

"images": [
  {"index":1,"data_url":"data:image/jpeg;base64,图片的真实Base64内容"}
]

不要发送本地文件路径或图片网址。单次请求最大5000000字节；每张图最多500KB。图片只辅助识别，不确定会返回待确认。一项商品可以对应多张图，总计最多5张。

4. 返回结果

{
  "results": [
    {"tax_code":"19020100","name":"玩偶"},
    {"tax_code":"17010000","name":"图书、报刊、期刊等出版物"}
  ]
}

结果与items顺序和数量一致，重复项保留。tax_code始终作为字符串处理，保留开头的0。无法确定时，两个字段均为“待确认”，需要人工处理。

format=txt时返回无表头的两列文本，税号与名称用Tab分隔、CRLF换行。原始用户税号、系统匹配和后续返回数据可在本页批次明细中核对。

5. 状态与记录

响应头：X-Batch-Id=批次号；X-Rule-Version=规则版本；X-Pending-Count=待确认数量；X-AI-Status=ok / not_needed / not_configured / failed。HTTP 200也要检查待确认项，AI失败不能当全部匹配成功。

400：字段错误；401：密钥无效；403：权限不足；413：请求过大；429：额度不足；500：服务异常。错误信息见JSON的error字段。请求超时后先核对批次，不要循环重试；相同reference也会生成新记录。

默认每天每个密钥1000件，日本时间重置，管理员可调整。已受理的待确认项和AI失败项也计入额度。密钥仅放程序后端，不支持浏览器跨域直接调用。图片会保存至对应批次并交给模型识别，请仅提交商品相关资料。