开发者参考文档
跨境外贸工具开放 API
以 HTTP 对外提供 HS 海关编码、外汇汇率、港口、集装箱装载、国别认证、FBA 头程、进出口税率、价格计算、智能归类与货代黄页共 10 个业务域的能力。全部为只读查询或纯计算,采用 AppKey + HMAC-SHA256 签名鉴权。
01
概述
10 个业务域均为只读或纯计算接口,不含任何写入 / 运维类操作。外部客户端一律按已登录会员处理,返回完整数据。
基础地址
| 环境 | Base URL |
|---|---|
| 开发 (context-path=/api) | http://localhost:8882/api/openapi/v1 |
| 生产 (context-path=/cloud/api) | https://<host>/cloud/api/openapi/v1 |
统一响应封装
无论成功或失败,服务端都返回统一 JSON 结构。判断是否成功以 meta.code == 200 为准,不要仅依赖 HTTP 状态码。
{ "meta": { "code": 200, "message": "操作成功!", "error": "", "success": true }, "data": { ... } // 业务数据；失败时为 null }
!
实测提示:响应为
{meta:{code,message,success}, data} 的嵌套结构,状态码在 meta.code。接入时请从 meta.code 取业务码,data 取数据。↓
下方每个接口都附带 Python / Java 完整可运行示例,内含签名逻辑,可一键复制或下载为独立文件直接运行(Python 需
requests,Java 需 JDK 11+)。02
鉴权与签名
每次请求都必须携带以下 4 个请求头,缺一不可。服务端依次校验:请求头完整性 → AppKey 有效性 → 时间戳窗口 → Nonce 防重放 → 签名一致性 → 限流。
| 请求头 | 必填 | 说明 |
|---|---|---|
| X-Api-Key | 是 | 平台分配的 appKey |
| X-Timestamp | 是 | Unix 毫秒时间戳字符串,与服务端时差 ≤ 300000ms(5 分钟),否则 40103 |
| X-Nonce | 是 | 随机串(建议 UUID),同一 AppKey 下 300 秒内不可重复,否则 40104 |
| X-Sign | 是 | HMAC-SHA256 签名,Base64 输出,大小写敏感 |
签名原文 stringToSign
由 6 段用换行符 \n 拼接,顺序固定:
METHOD # 大写 GET / POST PATH # 从 /openapi/v1 开始,生产环境剥离 /cloud/api 前缀 CANONICAL_QUERY # key 升序、key=value 用 & 连接、value 未编码 X-Timestamp # 与请求头逐字节一致 X-Nonce # 与请求头逐字节一致 BODY_SHA256_HEX # 请求体 SHA-256 十六进制小写；无体取空串常量
i
空请求体(GET / 无体)的 SHA-256 为固定常量
e3b0c442…7852b855。最终 X-Sign = Base64(HMAC_SHA256(appSecret, stringToSign))。可复算的完整示例
以调用 HS 编码搜索为例,测试凭证 appKey test-appkey-0001 / appSecret test-secret-please-change。
规范化查询串
query kw=laptop&cat=16 按 key 升序(cat < kw)→ cat=16&kw=laptop
请求体 SHA-256(GET 无体,取空串常量)
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
拼接 stringToSign(行间为单个 \n)
GET /openapi/v1/hs/search cat=16&kw=laptop 1754784000000 550e8400-e29b-41d4-a716-446655440000 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
HMAC-SHA256 + Base64 → X-Sign
l2dz9cJRuGrlfoAM/gETAia1kUH89ZNezP3YiuZWFTk= ✓ 已复算验证
curl "http://localhost:8882/api/openapi/v1/hs/search?kw=laptop&cat=16" \ -H "X-Api-Key: test-appkey-0001" \ -H "X-Timestamp: 1754784000000" \ -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \ -H "X-Sign: l2dz9cJRuGrlfoAM/gETAia1kUH89ZNezP3YiuZWFTk="
03
错误码
所有错误码位于 meta.code,data 为 null。鉴权类错误码在下方均已端到端验证。
| code | 含义 | 处理建议 |
|---|---|---|
| 200 | 成功 | 正常解析 data |
| 40101 | 缺少鉴权请求头 | 检查 4 个请求头是否齐全 |
| 40102 | 无效的 AppKey | 检查 X-Api-Key 是否正确、已开通 |
| 40103 | 时间戳过期或非法 | 校正时钟,毫秒且差值 ≤ 5 分钟 |
| 40104 | 重复请求(nonce 已用) | 每次生成新的随机 Nonce |
| 40105 | AppKey 已停用 | 联系管理员恢复 status=1 |
| 40106 | 签名错误 | 核对 stringToSign / 密钥 / 换行 / 排序 |
| 40107 | 请求过于频繁 | 降频或提升 qps_limit,可退避重试 |
| 40201 | 余额不足,请先充值 | 会员密钥按次计费,到「我的钱包」充值后重试 |
| 40001 | 业务参数错误 | 依 message 修正入参 |
| 50000 | 服务器内部错误 | 稍后重试,持续出现请联系平台 |
04
限流
按 AppKey 维度、每秒 QPS 计量。服务端以 openapi:rate:{appKey}:{epochSecond} 计数,每秒窗口内超过 qps_limit 即返回 40107。默认 10 QPS,测试客户端 20 QPS。
✓
实测:对测试客户端 1 秒内突发 25 次请求,精确返回 20×200 + 5×40107,与 qps_limit=20 完全吻合。触发后建议指数退避重试。
i
计费:会员自助创建的密钥按次扣钱包余额(默认 ¥0.01/次),在验签与限流全部通过后扣费;海关智能归类接口(
/openapi/v1/classify/suggest)按 DeepSeek token 消耗×2 计费(精确到 0.0001 元,响应体 cost 字段返回本次实扣金额);平台内置客户端免费。余额不足返回 40201,请到会员中心「我的钱包」充值。每次扣费可在「我的钱包 → 消费记录」查询。05 · 业务域
HS 海关编码 /hs
22 大类目、按关键词/类目分页搜索、编码详情(含监管与检疫中文解释)、热门词与字典。
GET
/hs/categories
22 大类目(含每类编码数)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | int | 类目 ID(1–22),可作为 /hs/search 的 cat 入参 |
| name | string | 类目中文名 |
| en | string | 类目英文名 |
| range | string | 编码区段,如 "84-85" |
| roman | string | 罗马序号 |
| sort | int | 排序值 |
| count | int | 该类目下有效 HS 编码数量 |
GET
/hs/search
按关键词 / 类目分页搜索
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kw | string | 否 | 关键词,匹配中/英名、编码、别名 |
| cat | int | 否 | 类目 ID |
| page | int | 否 | 页码,默认 1 |
| limit | int | 否 | 每页 1–200,默认 20 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| total | int | 命中总数 |
| page | int | 当前页码 |
| limit | int | 每页条数 |
| results | array | 结果列表,元素字段如下 |
| results[].code | string | HS 编码(8 位带点) |
| results[].cn | string | 中文品名 |
| results[].en | string | 英文品名 |
| results[].cat | int | 一级类目 ID(1–22) |
| results[].rebate | decimal | 出口退税率 % |
| results[].vat | decimal | 增值税率 % |
| results[].duty | decimal | MFN 关税 % |
| results[].dutyGen | decimal | 普通关税率 % |
| results[].mon | string | 监管条件代码(配合 /hs/dict/regulation 解读) |
| results[].ciq | string | 检验检疫类别代码(配合 /hs/dict/ciq 解读) |
| results[].unit | string | 法定计量单位 |
| results[].declare | string | 申报要素 |
| results[].ftaJson | string | 协定/RCEP 税率 JSON:{"fta":{国:税率},"rcep":{国:税率}} |
{ "total":1, "page":1, "limit":20, "results":[{ "code":"8471.3000", "cn":"便携式自动数据处理设备", "cat":16, "rebate":13.00, "vat":13.00, "unit":"台" }] }
GET
/hs/detail/{code}
单编码完整详情 + 相似推荐
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string(path) | 是 | HS 编码,如 8471.3000;不存在返回 40001 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| code / cn / en | string | HS 编码 / 中文品名 / 英文品名 |
| cat | int | 一级类目 ID |
| rebate / vat | decimal | 出口退税率 % / 增值税率 % |
| duty / dutyGen | decimal | MFN 关税 % / 普通关税 % |
| mon / ciq | string | 监管条件 / 检验检疫代码(原始值) |
| declare | string | 申报要素 |
| unit | string | 法定计量单位 |
| validFrom / validTo | date | 税率生效起期 / 止期(yyyy-MM-dd) |
| monZh | array | 监管条件中文解释列表,元素 {code, name, desc} |
| ciqZh | array | 检验检疫中文解释列表,元素 {code, name, desc} |
| similar | array | 同类目相似推荐(最多 5 条),字段同 /hs/search 的 results 元素 |
GET/hs/hot热门搜索词 Top 10
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| kw | string | 热门搜索词 |
| code | string | 关联 HS 编码(仅内置兜底词提供) |
| count | int | 近 7 天搜索次数(兜底词为 0) |
GET/hs/dict/regulation监管条件字典
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 监管条件代码,如 A / B / t |
| name | string | 条件名称 |
| desc | string | 条件说明 |
| sort | int | 排序值 |
GET/hs/dict/ciq检验检疫字典
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 检验检疫类别代码,如 M / R / P |
| name | string | 类别名称 |
| desc | string | 类别说明 |
| sort | int | 排序值 |
业务域
外汇汇率 /fx
52 币种实时牌价、任意币种互换、近 N 日中间价与币种字典。
GET/fx/currencies币种字典(可按 region 切片)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| region | string | 否 | 区域切片:major/europe/asia/america/other;缺省返回全部 |
响应字段 · data(数组,52 外币 + CNY)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 币种 ISO 代码 |
| cn / en | string | 中文名 / 英文名 |
| flag | string | 旗帜 emoji |
| region | string | 所属区域 |
| decimalPlaces | int | 小数位 |
| unit | int | 报价单位(如 100 日元) |
| isQuoted | int | 是否有牌价:1=是 0=否 |
GET/fx/rates52 币种实时牌价
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| region | string | 否 | 区域过滤,默认 all |
| kw | string | 否 | 关键字,匹配币种代码 / 中 / 英文名 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| updateTime | string | 整页最新报价时刻(yyyy-MM-dd HH:mm:ss) |
| total | int | 条数 |
| results | array | 牌价列表,元素字段如下 |
| results[].code / cn / en / flag / region / unit | - | 同 /fx/currencies |
| results[].mid | decimal | 中间价 |
| results[].cashBuy / cashSell | decimal | 现汇买入价 / 卖出价 |
| results[].noteBuy / noteSell | decimal | 现钞买入价 / 卖出价 |
| results[].change | decimal | 涨跌值 |
| results[].pct | decimal | 涨跌幅 % |
| results[].spark | string | 近 7 日中间价 JSON 数组(迷你走势) |
| results[].quoteTime | string | 该币种报价时刻 |
GET
/fx/convert任意币种互换
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| from | string | 是 | 源币种 ISO,如 USD(大小写不敏感) |
| to | string | 是 | 目标币种 ISO,如 CNY |
| amount | decimal | 是 | 金额,≥ 0 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| from / to | string | 源 / 目标币种代码(大写) |
| amount | decimal | 输入金额 |
| result | decimal | 换算结果(amount × midRate,4 位小数) |
| midRate | decimal | 折算汇率:1 from = midRate to |
| fromMid / toMid | decimal | 源 / 目标币种对 CNY 的中间价(CNY 固定 1) |
| quoteTime | string | 报价时刻(取两侧较新者) |
| reverseRate | decimal | 反向汇率:1 to = reverseRate from |
{ "from":"USD", "to":"CNY", "amount":100, "result":675.2286, "midRate":6.752286 }
GET/fx/history近 N 日中间价(最大 30 天)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 是 | 币种 ISO,如 USD;不支持的币种返回 40001 |
| days | int | 否 | 天数,默认 30,最大 30 |
响应字段 · data(数组,按日期升序)
| 字段 | 类型 | 说明 |
|---|---|---|
| date | string | 日期(yyyy-MM-dd) |
| mid | decimal | 当日中间价 |
| cashBuy / cashSell | decimal | 现汇买入 / 卖出估算价(按当日价差比例还原) |
业务域
港口 /port
全球港口列表、自动建议、详情、船公司直挂矩阵、地图点位与国家分组。
GET/port/list港口列表(分页 + 过滤)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| region | string | 否 | 区域过滤(all 或缺省为全部) |
| country | string | 否 | 国家 ISO2,如 US |
| onlyMain | boolean | 否 | true 只看基本港 |
| kw | string | 否 | 关键字,匹配代码 / 中英文名 / 国家中文 |
| page | int | 否 | 页码,默认 1 |
| limit | int | 否 | 每页条数,默认 20,最大 200 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| total / page / limit | int | 总数 / 当前页 / 每页条数 |
| results | array | 港口列表,元素字段如下 |
| results[].code | string | 港口代码(UN/LOCODE 风格) |
| results[].nameZh / nameEn | string | 中文名 / 英文名 |
| results[].countryIso / countryCn | string | 国家 ISO2 / 中文名 |
| results[].city | string | 所在城市 |
| results[].region | string | 所属区域 |
| results[].flag | string | 国旗 emoji |
| results[].portType | string | 港口类型(sea 等) |
| results[].isMain | int | 是否基本港:1=是 |
| results[].ipiUsd | int | IPI 参考价(USD) |
| results[].days | int | 参考航程天数 |
| results[].orc / ddc / thc | int | ORC / DDC / THC 附加费参考 |
GET/port/suggest自动建议下拉
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kw | string | 是 | 输入关键字;为空返回空数组 |
| limit | int | 否 | 返回条数,默认 20,最大 50 |
响应字段 · data(数组,基本港优先)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 港口代码 |
| cn / en | string | 中文名 / 英文名 |
| country / countryCn | string | 国家 ISO2 / 中文名 |
| flag | string | 国旗 emoji |
| isMain | int | 是否基本港:1=是 |
GET/port/detail/{code}港口详情
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string(path) | 是 | 港口代码,如 LAX;不存在返回 40001 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| code / nameZh / nameEn | string | 代码 / 中文名 / 英文名 |
| countryIso / countryCn / city / region / flag | string | 国家与城市信息 |
| portType | string | 港口类型 |
| isMain / isOrigin / isDest | int | 基本港 / 可做起运港 / 可做目的港(1=是) |
| ipiUsd / days / orc / ddc / thc | int | 运价与附加费参考 |
| authority | string | 港务局 / 管理方 |
| note | string | 备注 |
| lng / lat | decimal | 经纬度 |
| linesDetail | array | 直挂船公司元数据 [{code,nameZh,nameEn,bgColor,fgColor,alliance,isDirect}] |
| similarPorts | array | 同国家其它港口(最多 8 个)[{code,nameZh,isMain}] |
GET/port/matrix港口 × 船公司直挂矩阵
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| region | string | 否 | 区域过滤,默认 all;矩阵仅含基本港 + 海港 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| lines | array | 9 家船公司元数据 [{code,nameZh,nameEn,bgColor,fgColor,alliance,sort}],固定顺序 MSK/MSC/COSCO/EVA/CMA/HPL/ONE/HMM/ZIM |
| ports | array | 每行一个港口 |
| ports[].portMeta | object | 港口元信息 {code,nameZh,countryCn,flag,region,isMain} |
| ports[].marks | object | 直挂标记 {船公司code: true/false} |
GET/port/map全球港口分布点位
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,仅含有经纬度的港口)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 港口代码 |
| cn | string | 中文名 |
| lng / lat | decimal | 经度 / 纬度 |
| isMain | int | 是否基本港 |
| region | string | 所属区域 |
GET/port/countries国家分组(含港口数)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,按港口数降序)
| 字段 | 类型 | 说明 |
|---|---|---|
| country | string | 国家 ISO2 |
| countryCn | string | 国家中文名 |
| flag | string | 国旗 emoji |
| portCount | int | 该国家港口数量 |
GET/port/lines船公司元数据(9 家)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 船公司代码,如 MSK |
| cn / en | string | 中文名 / 英文名 |
| bgColor / fgColor | string | 品牌背景色 / 前景色 |
| alliance | string | 所属航运联盟 |
| website / logoUrl | string | 官网 / Logo 地址 |
| sort | int | 排序值 |
GET/port/hot热门港口
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,固定 11 个常用港口)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 港口代码,如 LAX |
| clickCount | int | 点击次数(当前固定 0,预留) |
| sort | int | 排序值(1 起) |
业务域
集装箱 /container
集装箱规格、推荐换柜阈值规则,以及装载计算(体积/重量利用率 + 拼箱建议)。
GET/container/specs规格列表(可按 cat 过滤)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cat | string | 否 | 类型分组:sea/reefer/open/frame/air,默认 all |
响应字段 · data(数组,17 种海/空运规格)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键(雪花 ID,JSON 序列化为字符串) |
| code | string | 规格编码:20GP / 40HQ / LD3 等 |
| name | string | 规格中文名 |
| cat | string | 类型分组:sea / reefer / open / frame / air |
| innerLMm / innerWMm / innerHMm | int | 内长 / 内宽 / 内高(mm) |
| volM3 | decimal | 理论容积(m³) |
| maxWeightKg | int | 最大载重(kg) |
| sort | int | 排序值 |
| enabled | int | 是否启用:1=启用 |
| createTime / updateTime | string | 创建 / 更新时间 |
GET/container/recommend-rules推荐换柜阈值规则
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键(雪花 ID) |
| ruleKey | string | 规则键,如 upgrade_20gp / overweight / lcl |
| ruleName | string | 规则名(中文) |
| targetSpec | string | 触发该规则的源规格 code,空为全局规则 |
| threshold | decimal | 触发阈值(%) |
| actionText | string | 建议文案,支持 {pct} 占位符 |
| sort / enabled | int | 排序 / 是否启用 |
| createTime / updateTime | string | 创建 / 更新时间 |
POST
/container/calc装载计算
请求体 ContainerCalcDTO:specCode + cargos[](1–20 行,每行含 L/W/H/weight/qty,可选 stackable/fragile)。
请求参数(JSON 请求体)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| specCode | string | 是 | 集装箱规格 code,如 20GP / 40HQ / LD3 |
| cargos | array | 是 | 货物清单,1–20 行 |
| cargos[].name | string | 否 | 货物名称 |
| cargos[].L / W / H | int | 是 | 单件长 / 宽 / 高(cm),1–2000 |
| cargos[].weight | decimal | 是 | 单件重量(kg) |
| cargos[].qty | int | 是 | 件数,1–100000 |
| cargos[].stackable | boolean | 否 | 是否可堆码,默认 true;false 利用率折扣 -15% |
| cargos[].fragile | boolean | 否 | 是否易碎品,默认 false(仅影响建议文案) |
{ "specCode":"40HQ", "cargos":[{ "name":"纸箱A", "L":60, "W":40, "H":40, "weight":12.5, "qty":300 }] }
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| specCode / specName | string | 所选规格 code / 中文名 |
| volPct / weightPct / overallPct | decimal | 体积 / 重量 / 综合利用率(%;综合取两者较大值) |
| loadedQty / totalDemandQty | int | 实装件数 / 需求总件数 |
| loadedQtyPct | decimal | 装载率 % |
| loadedVol / loadedWeight | decimal | 已装体积(m³)/ 已装重量(kg) |
| totalCargoVol / totalCargoWeight | decimal | 货物总体积(m³)/ 总重量(kg) |
| containerVol | decimal | 集装箱理论容积(m³) |
| containerMaxWeight | int | 集装箱最大载重(kg) |
| remainVol | decimal | 剩余空间(m³) |
| badge | string | 等级:ok / warn / danger |
| badgeText | string | 等级文案:装载合理 / 建议拼箱 / 需换大柜 等 |
| tips | array<string> | 智能建议列表(含 emoji) |
{ "specName":"40英尺高箱(HC)", "volPct":37.9, "weightPct":14.2, "overallPct":37.9, "badge":"warn", "tips":["…"] }
业务域
国别认证 /cert
按品类 × 目的国查认证清单、国家×认证矩阵、7 大地区全景与办理机构介绍。
GET/cert/categories品类下拉
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,10 类)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 品类代码,如 electronic;可作 /cert/search 的 category 入参 |
| nameZh / nameEn | string | 品类中文名 / 英文名 |
| sort | int | 排序值 |
GET/cert/countries国家下拉(可按 region)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| region | string | 否 | 区域过滤:major/europe/americas/asia/middle-east/oceania/africa/other |
响应字段 · data(数组,仅含已录入认证条目的国家)
| 字段 | 类型 | 说明 |
|---|---|---|
| iso | string | 国家 ISO2(EU 等区域代码兜底补入) |
| nameZh / nameEn | string | 中文名 / 英文名 |
| flag | string | 国旗 emoji |
| regionCode | string | 大区代码 |
| sort | int | 排序值 |
GET/cert/search品类 × 目的国认证清单
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| category | string | 是 | 品类代码,取值见 /cert/categories |
| country | string | 是 | 目的国 ISO2,如 US |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| summary.count | int | 认证条目总数 |
| summary.totalDays | int | 累计办理周期(工作日) |
| summary.totalCostUsd | int | 累计参考费用(USD) |
| items | array | 认证条目明细,元素字段如下 |
| items[].id | string | 条目 ID(雪花) |
| items[].cert | string | 认证代号,如 CE / FCC |
| items[].full | string | 英文全称 |
| items[].country / category | string | 适用国家 ISO / 品类代码 |
| items[].mandatory | boolean | true=强制 / false=自愿 |
| items[].validYears | int | 有效期年(0=长期/一次性) |
| items[].processDays | int | 办理周期(工作日) |
| items[].costUsd | int | 参考费用(USD) |
| items[].agencies | array<string> | 推荐办理机构短代码列表 |
| items[].note | string | 中文备注 / 法规依据 |
GET/cert/matrix国家 × 认证矩阵
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| category | string | 否 | 品类代码,默认 electronic |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| category | string | 品类代码 |
| certs | array<string> | 列:该品类下出现过的认证 code(去重) |
| countries | array | 行:每个国家一行(默认 22 国 + 数据中出现的其它国家) |
| countries[].iso / name / flag / regionCode | string | 国家 ISO2 / 中文名 / 国旗 / 大区 |
| countries[].cells | object | 认证覆盖标记 {cert_code: true/false} |
GET/cert/regions-overview7 大地区分组全景
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,7 大地区)
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | 地区名,如 欧盟 / 欧洲、北美、中东 / GCC |
| countries | array | 该组国家列表 |
| countries[].iso / nameZh / flag | string | 国家 ISO2 / 中文名 / 国旗 |
| countries[].certs | array<string> | 该国出现过的认证 code 列表(不限品类) |
GET/cert/agencies办理机构介绍卡
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,5 大机构)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 机构 ID(雪花) |
| code | string | 机构短代码,如 SGS / TUV |
| nameZh / nameEn | string | 中文名 / 英文名 |
| hqCountry | string | 总部国家 |
| foundedYear | int | 成立年份 |
| branchCount | int | 分支机构数 |
| descZh | string | 中文介绍 |
| colorClass | string | 前端着色 class |
| isMajor / sort | int | 是否主要机构(1=是)/ 排序值 |
业务域
FBA 头程 /fba
起运地/目的国/仓库字典、旺季 PSS 表、内部费率表,以及海/空/快三档比价。
GET/fba/origins起运地列表
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,7 个起运地)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键 ID(雪花) |
| code | string | 起运港代码:SZX/SHA/NGB/YIW/CAN/XMN/TAO/TSN |
| cityZh | string | 城市中文名 |
| portZh | string | 港区中文名 |
| sort | int | 排序值 |
| isActive | int | 是否启用:1=启用 |
GET/fba/destinations目的国列表
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,7 个目的国)
| 字段 | 类型 | 说明 |
|---|---|---|
| iso | string | 目的国代码:US/EU/JP/UK/CA/AU/MX |
| name | string | 中文名 |
| sort | int | 排序值 |
GET/fba/warehouses按目的国查 FBA 仓库
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dest | string | 是 | 目的国代码,如 US;为空返回 40001 |
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键 ID(雪花) |
| area | string | 所属目的国代码 |
| code | string | FBA 仓库码,如 ONT8 |
| cityZh | string | 城市中文名 |
| stateCode | string | 州 / 省代码 |
| countryIso | string | 国家 ISO |
| isRemote | int | 是否偏远仓:1=是 |
| remoteNote | string | 偏远说明 |
| sort | int | 排序值 |
GET/fba/peak-table12 月旺季 PSS 表
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,按月份 1–12)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键 ID(雪花) |
| month | int | 月份(1–12) |
| seaPct / airPct / expPct | int | 海运 / 空运 / 快递旺季附加费 % |
| label | string | 月份标签,如 "9月 · 备货旺季" |
GET/fba/rates内部费率表
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| origin | string | 否 | 起运港代码过滤,如 SZX |
| dest | string | 否 | 目的国代码过滤,如 US |
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键 ID(雪花) |
| originCode / destIso | string | 起运港代码 / 目的国代码 |
| seaM3 | decimal | 海运单价(CNY/m³) |
| seaEta | string | 海运时效文案,如 "35-42 天" |
| airKg | decimal | 空运单价(CNY/kg) |
| airEta | string | 空运时效文案 |
| expKg | decimal | 快递单价(CNY/kg) |
| expEta | string | 快递时效文案 |
POST
/fba/calc海/空/快三档比价
请求体 FbaCalcDTO:origin/dest/warehouse/weight/volume/month 必填,battery/powder/brand/ddp 可选。
请求参数(JSON 请求体)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| origin | string | 是 | 起运港 code,取值见 /fba/origins |
| dest | string | 是 | 目的国(US/EU/JP/UK/CA/AU/MX),须与仓库所属区域一致 |
| warehouse | string | 是 | FBA 仓库码,取值见 /fba/warehouses |
| weight | decimal | 是 | 实重 kg,≥ 1 |
| volume | decimal | 是 | 体积 m³(体积重按 1m³=167kg 折算) |
| month | int | 是 | 月份 1–12,决定旺季 PSS |
| battery | boolean | 否 | 是否带电池,默认 false(叠加敏感货系数) |
| powder | boolean | 否 | 是否粉末 / 液体,默认 false |
| brand | boolean | 否 | 是否品牌货,默认 false |
| ddp | boolean | 否 | 是否 DDP 包税,默认 true |
{ "origin":"SZX", "dest":"US", "warehouse":"ONT8", "weight":200, "volume":1.2, "month":9, "ddp":true }
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| chargeWeight | decimal | 计费重 kg = max(实重, 体积×167) |
| originName | string | 起运港中文名 |
| dest / warehouse | string | 目的国 / 仓库 code(回显) |
| isRemote | boolean | 是否偏远仓 |
| peak | object | 当月 PSS:{month, seaPct, airPct, expPct, label} |
| sea / air / exp | object | 三档渠道结果,结构相同,字段如下 |
| sea.channel | string | 渠道标识:sea / air / exp |
| sea.total | decimal | 该档总价(CNY,取整) |
| sea.unit | decimal | 单价 CNY/kg(按实重) |
| sea.eta | string | 时效文案,如 "35-42 天" |
| sea.etaDaysMin | int | 时效下限天数(fastest 判定用) |
| sea.lines | array | 费用明细行 [{key, value, show}];show=false 为未触发项 |
| badges | object | 角标:{cheapest, fastest},值为 sea/air/exp |
业务域
税率测算 /tax
HS 下拉、国家税率、HS × 国家联合税率(含 FTA)、税率矩阵,以及报税利润计算器。
GET/tax/hs-codesHS 编码下拉(按品类)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| cat | string | 否 | 品类过滤(对应 HS 一级类目,如 电子电器) |
| kw | string | 否 | 关键字,匹配编码 / 中 / 英名 |
响应字段 · data(数组,最多 200 条)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | HS 8 位编码 |
| name | string | 品名(优先中文) |
| cat | string | 所属品类 |
| rebate / vat | decimal | 出口退税率 % / 增值税率 % |
GET/tax/countries国家/地区税率列表
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,38 国/地区)
| 字段 | 类型 | 说明 |
|---|---|---|
| iso | string | 国家 ISO2 |
| name / flag | string | 中文名 / 国旗 emoji |
| region | string | 所属区域 |
| cur | string | 当地货币代码 |
| mfn | decimal | MFN 平均关税 % |
| vat / vatName | decimal / string | 增值税率 % / 当地称谓(如 VAT / GST) |
| cTax | decimal | 消费税率 %(无细分品类时取国家级) |
| fta / ftaCls | string | 协定代码 / 协定分类(rcep/wto/cn-asean 等) |
| isFta / isRcep | int | 是否 FTA / RCEP 成员:1=是 |
| note | string | 备注 |
GET/tax/rateHS × 国家联合税率
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| hsCode | string | 是 | HS 8 位编码,如 8517.1200;不存在返回 40001 |
| iso | string | 是 | 目的国 ISO2,如 US;不存在返回 40001 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| cn.rebate / cn.vat | decimal | 中国出口侧:退税率 % / 增值税率 % |
| cn.hsCode / cn.hsName / cn.hsCat | string | HS 编码 / 名称 / 大类(回显) |
| dest.mfn | decimal | 估算 MFN 关税 %(mfn_avg × 品类倍率 × FTA/RCEP 折扣) |
| dest.vat / dest.cTax | decimal | 目的国 VAT % / 消费税 % |
| dest.total | decimal | 综合税负 % = mfn + vat×(1+mfn/100) + cTax |
| dest.vatName / currency / iso | string | VAT 称谓 / 当地货币 / ISO2 |
| dest.countryLabel | string | 国名(含国旗 emoji 前缀) |
| fta.name / fta.desc | string | 协定优惠标题 / 说明(如 "★ RCEP 优惠适用") |
| fta.cls | string | 着色 class:rcep/wto/cn-asean/cn-kr/cn-pak/cn-au/cn-nz |
| fta.isFta / fta.isRcep | boolean | 是否 FTA / RCEP |
| note | string | 综合备注 |
GET/tax/matrix国家税率矩阵
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| region | string | 否 | 区域过滤(all 或缺省为全部) |
| isFta | boolean | 否 | true 只看 FTA 国家 |
| isRcep | boolean | 否 | true 只看 RCEP 国家 |
| vatRange | string | 否 | VAT 区间:high(≥20%)/ low(≤10%) |
响应字段 · data(数组)
| 字段 | 类型 | 说明 |
|---|---|---|
| 元素字段与 /tax/countries 完全相同(iso/name/flag/region/cur/mfn/vat/vatName/cTax/fta/ftaCls/isFta/isRcep/note) | ||
POST
/tax/profit-calc报税利润计算器
请求体 TaxProfitCalcDTO:hs/iso/unit/qty 必填,term/costPct/fx/freightPct 可选。
请求参数(JSON 请求体)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| hs | string | 是 | HS 8 位编码,如 8517.1200;不存在返回 40001 |
| iso | string | 是 | 目的国 ISO2,如 US;不存在返回 40001 |
| unit | decimal | 是 | 出口单价(USD/件),负数按 0 处理 |
| qty | decimal | 是 | 数量(件),负数按 0 处理 |
| term | string | 否 | 贸易术语 FOB/CFR/CIF,默认 CIF;FOB 时叠加 freightPct |
| costPct | decimal | 否 | 采购成本占售价 %(含进项 VAT),默认 0 |
| fx | decimal | 否 | 即期汇率 USD→CNY,缺省 7.21 |
| freightPct | decimal | 否 | 海运费占货值 %(仅 FOB 生效),默认 0 |
{ "hs":"8517.1200", "iso":"US", "unit":50, "qty":1000, "term":"FOB", "costPct":70, "fx":7.21 }
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| outTotalUSD | decimal | 销售总额(USD)= unit × qty |
| outTotalCNY | decimal | 销售总额(CNY,按 fx 折算) |
| outCostCNY | decimal | 采购成本(CNY,含进项 VAT) |
| outRebate | decimal | 出口退税回流(CNY) |
| outDestCIF | decimal | 目的国 CIF 货值(USD) |
| outDestDuty / outDestVAT / outDestCTax | decimal | 目的国关税 / VAT / 消费税(USD) |
| outRetail | decimal | 终端零售估算(当地币) |
| outProfit | decimal | 出口商毛利(CNY) |
| outMargin | decimal | 综合毛利率 %(1 位小数) |
| total / margin | decimal | 兼容字段,分别 = outTotalCNY / outMargin |
| destCur | string | 当地货币代号,如 USD / JPY |
| calcCurUnit | string | 计价币,固定 USD |
| usedMfn / usedVat / usedCTax / usedRebate | decimal | 调试用:本次计算采用的税率 % |
业务域
价格计算 /price
外贸报价工具：Incoterms 2020 全部 11 种贸易术语（EXW/FCA/FAS/FOB/CFR/CIF/CPT/CIP/DAP/DPU/DDP）一次性报价对比，计入出口退税抵扣与汇率换算。
GET/price/terms11 种术语元数据(中文名/运输方式/卖方费用责任)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,Incoterms 2020 共 11 条)
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 术语代码,如 FOB / CIF / DDP |
| nameZh | string | 中文名,如 装运港船上交货 |
| mode | string | 适用运输方式:any=任何方式 / sea=海运及内河 |
| sellerCost | string | 卖方费用责任说明 |
POST
/price/calc11 种术语报价对比计算
请求体 PriceCalcDTO:profitMargin/exchangeRate 必填;商品明细二选一 —— items 多行商品(单价/数量/箱规/毛净重,整票汇总) 或 unitCostRmb/quantity 单商品快捷方式;vatRate/rebateRate/insuranceRate/importDutyRate/importVatRate/inlandFeeRmb/portFeeRmb/freightFeeRmb/destFeeRmb/targetCurrency 可选。费用为整票 RMB,按总数量摊薄;汇率为 1 CNY = X 目标币种。
请求参数(JSON 请求体)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| profitMargin | decimal | 是 | 预期利润率(对报价的 margin),0–0.9 |
| exchangeRate | decimal | 是 | 汇率:1 CNY = X 目标币种,> 0 |
| items | array | 条件 | 多行商品明细(整票汇总);与 unitCostRmb/quantity 二选一 |
| items[].unitCostRmb | decimal | 是 | 含税采购单价(元/件),> 0 |
| items[].quantity | int | 是 | 数量(件),≥ 1 |
| items[].name | string | 否 | 品名 |
| items[].unitsPerCarton | int | 否 | 每箱数量(件/箱),填了才统计箱数 |
| items[].cartonLengthCm / cartonWidthCm / cartonHeightCm | decimal | 否 | 外箱三边(cm),齐全才计体积 |
| items[].grossWeightPerCartonKg / netWeightPerCartonKg | decimal | 否 | 毛重 / 净重(kg/箱) |
| unitCostRmb | decimal | 条件 | 单商品模式:含税采购成本(元/件),> 0 |
| quantity | int | 条件 | 单商品模式:数量(件),≥ 1 |
| vatRate | decimal | 否 | 增值税率,默认 0.13,0–1 |
| rebateRate | decimal | 否 | 出口退税率,默认 0.13,0–1 |
| inlandFeeRmb | decimal | 否 | 国内段费用总额(内陆运费+出口报关,整票 RMB),默认 0 |
| portFeeRmb | decimal | 否 | 起运港杂费总额(THC/文件费等,整票 RMB),默认 0 |
| freightFeeRmb | decimal | 否 | 国际运费总额(整票 RMB),默认 0 |
| insuranceRate | decimal | 否 | 保险费率,默认 0.003(按 CIF×110% 投保),0–0.2 |
| destFeeRmb | decimal | 否 | 目的港本地+派送费总额(整票 RMB,DAP/DPU/DDP 用),默认 0 |
| importDutyRate | decimal | 否 | 进口关税率(DDP 用),默认 0,0–1 |
| importVatRate | decimal | 否 | 进口增值税率(DDP 用),默认 0,0–1 |
| targetCurrency | string | 否 | 目标币种,默认 USD |
{ "unitCostRmb":100, "quantity":1000, "profitMargin":0.15, "inlandFeeRmb":2000, "portFeeRmb":1500, "freightFeeRmb":12000, "exchangeRate":0.1387, "targetCurrency":"USD" }
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 11 个术语各一条报价(按风险递增),元素字段如下 |
| items[].term / termName | string | 术语代码 / 中文名 |
| items[].costRmb | decimal | 单件成本 RMB(未含利润) |
| items[].quoteRmb / quoteForeign | decimal | 单件报价(RMB / 目标币种) |
| items[].profitRmb | decimal | 单件利润 RMB |
| items[].totalQuoteRmb / totalQuoteForeign | decimal | 整票报价(RMB / 目标币种) |
| items[].steps | array | 成本累加明细 [{label, amount}] |
| actualCost | decimal | 实际成本(退税抵扣后,元/件) |
| rebatePerUnit | decimal | 退税额(元/件) |
| exchangeRate / targetCurrency / quantity | - | 入参回显:汇率 / 目标币种 / 数量 |
| cargo.totalQuantity | int | 整票总数量(件) |
| cargo.totalCartons | int | 总箱数(仅统计填了每箱数量的行) |
| cargo.totalCbm | decimal | 总体积 m³(仅统计箱规三边齐全的行) |
| cargo.totalGwKg / totalNwKg | decimal | 总毛重 / 总净重(kg) |
| cargo.lines | array | 逐行明细 [{name,unitCostRmb,quantity,cartons,cbm,gwKg,nwKg}] |
业务域
海关智能归类 /classify
商品归类建议：规则引擎基于 HS 编码库（品名/别名/英文名 + 申报要素）打分给出 Top 5 候选（含退税/增值税/关税/监管/检疫/申报要素），并可选叠加 DeepSeek AI 依据归类总规则复核。未配置 AI 密钥或复核失败时 ai 字段为 null，不影响规则结果。
POST
/classify/suggest智能归类建议(规则引擎 Top 5 + AI 复核)
请求体 ClassifySuggestDTO:productName 商品名称必填;material 材质 / usage 用途 / process 加工方式 / spec 规格型号 / composition 成分含量均可选,填写越充分匹配越准。响应 data.candidates 为按 score 降序的候选数组(code/nameZh/nameEn/score/matchReasons/rebate/vat/duty/dutyGen/mon/ciq/unit/declare),data.ai 为 AI 复核结果(suggestedCode/suggestedName/reasoning/rules/caveat/model),可空。
请求参数(JSON 请求体)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| productName | string | 是 | 商品名称,如 "蓝牙耳机" |
| material | string | 否 | 材质,如 "塑料" |
| usage | string | 否 | 用途,如 "音频播放" |
| process | string | 否 | 加工方式 |
| spec | string | 否 | 规格型号 |
| composition | string | 否 | 成分含量 |
{ "productName":"蓝牙耳机", "material":"塑料", "usage":"音频播放" }
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| candidates | array | 规则引擎 Top 5 候选(按 score 降序),元素字段如下 |
| candidates[].code | string | HS 编码(8 位带点) |
| candidates[].nameZh / nameEn | string | 中文 / 英文品名 |
| candidates[].score | int | 匹配得分(0–100) |
| candidates[].matchReasons | array<string> | 命中说明,如 品名命中:蓝牙 / 属性命中:材质=塑料 |
| candidates[].rebate / vat | decimal | 出口退税率 % / 增值税率 % |
| candidates[].duty / dutyGen | decimal | MFN 关税 % / 普通关税 % |
| candidates[].mon / ciq | string | 监管条件 / 检验检疫类别 |
| candidates[].unit | string | 法定计量单位 |
| candidates[].declare | string | 申报要素 |
| ai | object | null | DeepSeek AI 复核结果;未配置密钥或调用失败时为 null |
| ai.suggestedCode / suggestedName | string | AI 建议的 HS 编码 / 对应品名 |
| ai.reasoning | string | 归类理由 |
| ai.rules | array<string> | 引用的归类总规则 |
| ai.caveat | string | 免责提示 |
| ai.model | string | 调用的模型名 |
业务域
货代黄页 /forwarder
货代列表查询、详情(含报价历史与评价),以及航线/服务类型/港口字典。
GET/forwarder/list货代列表(分页 + 过滤 + 排序)
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| line | string | 否 | 航线:美西/美东/欧基港/地中海/东南亚/中东/南美/非洲/澳新 |
| origin | string | 否 | 出运港代码(SHA/YTN 等)或中文名,映射到城市模糊匹配 |
| dest | string | 否 | 目的港代码(UN/LOCODE),取值见 /forwarder/destinations |
| type | string | 否 | 服务类型:海运/空运/快递/拖车/报关/仓储/跨境海派双清 |
| minRating | int | 否 | 最小评级 0/3/4/5,默认 0=不过滤 |
| sort | string | 否 | 排序:rating(默认)/price/review/year |
| page | int | 否 | 页码,默认 1 |
| limit | int | 否 | 每页条数,默认 20,最大 200 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| total / page / limit | int | 总数 / 当前页 / 每页条数 |
| results | array | 货代列表(已脱敏),元素字段如下 |
| results[].id | string | 货代 ID(雪花,序列化为字符串) |
| results[].name | string | 公司中文全称 |
| results[].city | string | 注册城市 |
| results[].rating | decimal | 综合评分(满分 5) |
| results[].reviewCount | int | 累计评价数 |
| results[].midPrice | int | 历史报价中位数(CNY) |
| results[].foundYear | int | 成立年份 |
| results[].nvocc / fiata | boolean | NVOCC 资质 / FIATA 会员 |
| results[].lines / types | array<string> | 主营航线 / 服务类型代码列表 |
| results[].addr | string | 地址(列表复用为出运港展示) |
| results[].maskedTel / maskedEmail | string | 脱敏电话 / 邮箱 |
| results[].note | string | 一句话特长 |
GET/forwarder/detail/{id}详情 + 报价历史 + 评价
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | long(path) | 是 | 货代雪花 ID;不存在或已下线返回 40001 |
响应字段 · data
| 字段 | 类型 | 说明 |
|---|---|---|
| id / name / city | - | ID(字符串)/ 公司名 / 注册城市 |
| rating / reviewCount | decimal / int | 综合评分 / 评价数 |
| midPrice | int | 历史报价中位数(CNY) |
| foundYear | int | 成立年份 |
| nvocc / fiata | boolean | NVOCC 资质 / FIATA 会员 |
| addr / address | string | 完整地址(address 为兼容字段,同 addr) |
| maskedTel / maskedEmail | string | 脱敏电话 / 邮箱 |
| note | string | 备注 / 特长 |
| lines / types | array<string> | 主营航线 / 服务类型 |
| priceHistory | array | 报价历史 [{month(yyyy-MM), price(CNY), lineCode}];库无数据时按 midPrice 派生 12 个月 |
| reviews | array | 已通过审核的评价 [{user(脱敏), score(0-5), content, createdAt}],最多 20 条 |
GET/forwarder/lines航线字典
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,9 大航线)
| 字段 | 类型 | 说明 |
|---|---|---|
| code / name | string | 航线代码与名称(相同):美西/美东/欧基港/地中海/东南亚/中东/南美/非洲/澳新 |
| sort | int | 排序值 |
GET/forwarder/types服务类型字典
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,7 类服务)
| 字段 | 类型 | 说明 |
|---|---|---|
| code / name | string | 服务类型:海运/空运/快递/拖车/报关/仓储/跨境海派双清 |
| sort | int | 排序值 |
GET/forwarder/origins出运港字典
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,9 大出运港)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键 ID(雪花) |
| code | string | 港口代码:SHA/NGB/YTN/SKU/NSH/TAO/XMN/TSN/DLC |
| name / nameEn | string | 中文名 / 英文名 |
| countryIso | string | 国家 ISO |
| sort | int | 排序值 |
GET/forwarder/destinations目的港字典
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 无参数 | |||
响应字段 · data(数组,36 个主要目的港,按航线分组)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 主键 ID(雪花) |
| code | string | 目的港代码(UN/LOCODE) |
| name / nameEn | string | 中文名 / 英文名 |
| countryIso | string | 国家 ISO |
| lineCode | string | 所属航线代码 |
| sort | int | 排序值 |
附录
签名示例代码 · Python
与第 2 节完全一致的 stringToSign 实现,可直接互操作,也可复算示例签名。POST 的 BODY_SHA256_HEX 必须对实际发送的请求体字节计算。
import hashlib, hmac, base64, time, uuid, requests EMPTY = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" def canonical(q): return "&".join(f"{k}={q[k]}" for k in sorted(q)) if q else "" def call(method, path, query=None, body=None): ts, nonce = str(int(time.time()*1000)), str(uuid.uuid4()) bh = hashlib.sha256(body.encode()).hexdigest() if body else EMPTY sts = "\n".join([method, "/openapi/v1"+path, canonical(query), ts, nonce, bh]) sign = base64.b64encode(hmac.new(SECRET.encode(), sts.encode(), hashlib.sha256).digest()).decode() headers = {"X-Api-Key":KEY, "X-Timestamp":ts, "X-Nonce":nonce, "X-Sign":sign} return requests.request(method, BASE+path, params=query, data=body, headers=headers).json()
i
Java 版实现见仓库
docs/开放API接入文档.md §7.1。端到端测试脚本 docs/openapi_e2e.py 覆盖 21 项检查(8 域正向 + 鉴权负向 + 防重放 + 限流),可直接运行做回归。