API 服务与计费说明
注册用户可创建 API KEY,通过三个只读接口获取 HS 编码、商品与商品 HS 关联数据。同一账户、同一接口、同一目标首次成功查询按 0.04 USD 计费,重复查询永久免费,网页查看与 API 共用充值包。
- 可用范围
- 注册并验证邮箱的用户
- 计费
- 0.04 USD
- 扣费顺序
- 充值包 → 余额
可查询的数据
| 能力 | 说明 | 计费 |
|---|---|---|
| HS 编码查询 | 查询 HS 编码的当前版本名称与进口税率,并以树状结构返回其子编码。 | 查询到记录时 0.04 USD |
| 商品资料查询 | 按 JAN 条码或商品 ID 查询商品基础资料,不包含 HS 关联。 | 查询到记录时 0.04 USD |
| 商品 HS 关联查询 | 查询商品的基础资料与已确认的 HS 编码关联。 | 查询到记录时 0.04 USD |
只查询、不写入。三个接口都在查询到记录时扣费,编码或商品不存在时返回 404、不扣费;额度不足时返回 402,不会返回部分数据。
认证
在用户中心创建 API KEY 后,通过 Authorization 请求头携带密钥。密钥只在创建时显示一次,请妥善保管。
Authorization: Bearer mls_xxxxxxxxxxxxxxxx
完整接口地址与请求示例可在工作台的「API 文档」中查看。
每次成功响应都包含本次扣费信息(funding、usesCharged、amountCharged、packRemaining、balance、currency)。
计费与充值包
网页查看与 API 共用充值包和余额:需计费时优先扣充值包,再从余额扣除 0.04 USD;同一账户、同一接口、同一目标的 API 重复查询永久免费,额度用完也可查询。
| 充值包 | 可用次数 | 折合单价 |
|---|---|---|
| 10.00 USD | 275 | 约 0.036 USD / 次 |
| 50.00 USD | 1,500 | 约 0.033 USD / 次 |
| 100.00 USD | 3,250 | 约 0.031 USD / 次 |
| 500.00 USD | 18,750 | 约 0.027 USD / 次 |
也可以直接充值余额,按每次 0.04 USD 扣费。充值包与余额均在用户中心购买和查看。
错误与限额
- 402 insufficient_credit:充值包次数与余额都不足,请先充值。
- 404 not_found:编码或商品不存在,或尚未公开发布。
- 409 ambiguous:条码对应多个商品,请改用商品 ID 查询。
- 每小时 120 次的基础请求限制,超出后返回 429。
API 返回的税率与商品 HS 关联仅供参考,正式归类与通关判断请以日本海关及主管机关的说明为准。