API 文档

提供公开接口与付费接口的请求地址、请求方式、参数说明与响应示例。

接口数量

公开接口

付费接口

接入说明

统一请求规则

Base URL

https://tms-go.czl.net

公开接口

无需鉴权，直接请求即可。

付费接口

请求头使用 Authorization: Bearer <API_KEY>。

免费公开接口

燃油附加费

公开读取 DHL、FedEx、UPS 的燃油附加费区间数据，无需鉴权，适合做前端展示和定时同步。

GET公开

UPS 燃油

获取 UPS 最新燃油附加费区间。

Path

/api/fuel/ups

Method

GET

Auth

无需鉴权

Content-Type

application/json

请求参数

无

请求示例

curl --request GET \
  --url https://tms-go.czl.net/api/fuel/ups

响应示例

{
  "surcharges": [
    {
      "start_date": "2026-03-17",
      "end_date": "2026-03-23",
      "surcharge": "30.50%"
    }
  ]
}

返回字段说明

直接返回原始 JSON，不包裹 code / msg / data。

核心字段是 surcharges 数组，每项包含 start_date、end_date、surcharge。

说明

适合用于公开展示页、内部报价工具或缓存同步任务。

字段 surcharge 为字符串，建议前端按百分比文本直接展示。

GET公开

DHL 燃油

获取 DHL 最新燃油附加费区间。

Path

/api/fuel/dhl

Method

GET

Auth

无需鉴权

Content-Type

application/json

请求参数

无

请求示例

curl --request GET \
  --url https://tms-go.czl.net/api/fuel/dhl

响应示例

{
  "surcharges": [
    {
      "start_date": "2026-03-17",
      "end_date": "2026-03-23",
      "surcharge": "27.75%"
    }
  ]
}

返回字段说明

直接返回原始 JSON，不包裹 code / msg / data。

数据源统一为 surcharges 数组，便于前端复用同一套渲染逻辑。

说明

当 end_date 为空时，表示当前区间尚未封闭。

推荐客户端做短期缓存，避免重复请求。

GET公开

FedEx 燃油

获取 FedEx 最新燃油附加费区间。

Path

/api/fuel/fedex

Method

GET

Auth

无需鉴权

Content-Type

application/json

请求参数

无

请求示例

curl --request GET \
  --url https://tms-go.czl.net/api/fuel/fedex

响应示例

{
  "surcharges": [
    {
      "start_date": "2026-03-17",
      "end_date": "2026-03-23",
      "surcharge": "28.25%"
    }
  ]
}

返回字段说明

直接返回原始 JSON，不包裹 code / msg / data。

适合做燃油看板、周度比价或二次加工计算。

说明

三个燃油接口结构完全一致，前端可以按 carrier 复用组件。

示例响应为文档整理值，实际区间以线上数据为准。

免费公开接口

快递附加费信息

公开读取附加费基础配置，可用于前端报价说明、附加费列表或规则展示。

GET公开

获取附加费列表

读取全部附加费项目。

Path

/api/surcharge/items

Method

GET

Auth

无需鉴权

Content-Type

application/json

请求参数

参数	位置	类型	必填	说明
order	Query	string	否	可选排序字段，常见值有 sortOrder、name、courier、category、charge、created。示例: sortOrder

请求示例

curl --request GET \
  --url 'https://tms-go.czl.net/api/surcharge/items?order=sortOrder'

响应示例

[
  {
    "id": 1,
    "name": "偏远附加费",
    "baseCharge": 25,
    "courierType": "DHL",
    "unit": "票",
    "displayCategory": "通用附加费",
    "note": "按最新价目表同步",
    "sortOrder": 10,
    "createdAt": "2026-03-01T08:00:00+08:00",
    "updatedAt": "2026-03-01T08:00:00+08:00"
  }
]

返回字段说明

直接返回数组，不包裹 code / msg / data。

每个项目都包含基础费用 baseCharge 和展示分类 displayCategory。

说明

如果前端不传 order，服务端会按默认规则返回。

这个接口很适合和燃油接口一起组成报价说明页。

付费接口

国家接口

提供国家基础资料查询，适合下拉字典、国家校验和面单相关前置校验。

GET付费

获取所有国家

返回完整国家列表。

Path

/api/v1/countries

Method

GET

Auth

Authorization: Bearer <API_KEY>

Content-Type

application/json

请求参数

参数	位置	类型	必填	说明
Authorization	Header	string	是	平台发放的 API Key，格式为 Bearer Token。示例: Bearer your_api_key

请求示例

curl --request GET \
  --url https://tms-go.czl.net/api/v1/countries \
  --header 'Authorization: Bearer your_api_key'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "countries": [
      {
        "code": "US",
        "name": "美国",
        "ename": "United States"
      },
      {
        "code": "CN",
        "name": "中国",
        "ename": "China"
      }
    ],
    "total": 2
  }
}

返回字段说明

付费接口统一返回 { code, msg, data } 包裹结构。

data.countries 为国家数组，data.total 为总数。

说明

适合在服务启动时拉取并缓存到本地，减少重复请求。

返回字段 ename 为英文名称，可直接用于英文地址面板或搜索。

GET付费

获取单个国家

按国家代码查询单个国家信息。

Path

/api/v1/country

Method

GET

Auth

Authorization: Bearer <API_KEY>

Content-Type

application/json

请求参数

参数	位置	类型	必填	说明
Authorization	Header	string	是	平台发放的 API Key，格式为 Bearer Token。示例: Bearer your_api_key
code	Query	string	是	国家二字码，例如 US、CN、GB。示例: US

请求示例

curl --request GET \
  --url 'https://tms-go.czl.net/api/v1/country?code=US' \
  --header 'Authorization: Bearer your_api_key'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "code": "US",
    "name": "美国",
    "ename": "United States"
  }
}

返回字段说明

成功时 data 为单个国家对象。

未找到国家时返回 404 和统一错误结构。

说明

如果 code 为空，接口会直接返回 400。

适合在表单输入后做单点校验，不必每次都拉全量国家列表。

付费接口

基于 DHL

围绕 DHL 地址提示能力的两个接口，通常先判断国家是否支持邮编，再决定用邮编还是城市名做建议查询。

GET付费

DHL 国家邮编支持查询

判断某个国家是否支持按邮编查询。

Path

/api/v1/dhl/country/postcode-support

Method

GET

Auth

Authorization: Bearer <API_KEY>

Content-Type

application/json

请求参数

参数	位置	类型	必填	说明
Authorization	Header	string	是	平台发放的 API Key，格式为 Bearer Token。示例: Bearer your_api_key
country_code	Query	string	是	国家二字码，例如 US、CN、DE。示例: US

请求示例

curl --request GET \
  --url 'https://tms-go.czl.net/api/v1/dhl/country/postcode-support?country_code=US' \
  --header 'Authorization: Bearer your_api_key'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "country_code": "US",
    "postcode_supported": true
  }
}

返回字段说明

成功时 data.postcode_supported 为 true / false。

建议把这个结果缓存起来，减少后续城市建议查询前的重复判断。

说明

你提供的原始列表里，这个接口的 Apifox 链接写错成了单个国家查询；这里已对齐到真实页面。

接口本身不返回城市列表，只负责告诉你查询策略。

GET付费

DHL 城市建议查询

根据国家和关键词返回 DHL 城市建议列表。

Path

/api/v1/dhl/city/suggestions

Method

GET

Auth

Authorization: Bearer <API_KEY>

Content-Type

application/json

请求参数

参数	位置	类型	必填	说明
Authorization	Header	string	是	平台发放的 API Key，格式为 Bearer Token。示例: Bearer your_api_key
country_code	Query	string	是	国家二字码，例如 US、CN、DE。示例: US
query	Query	string	是	城市名或邮编关键词。示例: 10001

请求示例

curl --request GET \
  --url 'https://tms-go.czl.net/api/v1/dhl/city/suggestions?country_code=US&query=10001' \
  --header 'Authorization: Bearer your_api_key'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "country_code": "US",
    "query": "10001",
    "suggestions": [
      {
        "name": "NEW YORK",
        "code": "NYC"
      }
    ]
  }
}

返回字段说明

成功时 data.suggestions 为数组，每项至少包含 name，部分国家会返回 code。

建议先调用邮编支持查询，再决定给用户展示城市输入还是邮编输入。

说明

这个接口特别适合做自动补全和模糊提示。

字段 code 为 DHL 侧建议代码，可能为空。

付费接口

查询偏远

核心偏远查询接口，统一输出 DHL、FedEx、TNT、UPS 以及自定义渠道的偏远命中结果。

POST付费

偏远地区查询

查询指定国家与城市 / 邮编的偏远信息。

Path

/api/v1/remote

Method

POST

Auth

Authorization: Bearer <API_KEY>

Content-Type

application/json

请求参数

参数	位置	类型	必填	说明
Authorization	Header	string	是	平台发放的 API Key，格式为 Bearer Token。示例: Bearer your_api_key
country_code	Body	string	是	国家二字码，例如 US、CA、AU。示例: US
city_or_post	Body	string	是	城市名或邮编。若国家支持邮编，首查通常传邮编；服务端会先做格式校验。示例: 96813
selected_city	Body	string	否	可选。用户从候选城市中选定的具体城市名。传入后，服务端会将邮编首查结果与该城市补查结果合并后返回。示例: HONOLULU

请求示例

curl --request POST \
  --url https://tms-go.czl.net/api/v1/remote \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country_code": "NZ",
    "city_or_post": "0112",
    "selected_city": "MAIRTOWN"
  }'

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "query_cities": ["KAMO", "MAIRTOWN", "OTANGAREI"],
    "dhl": {
      "is_remote": false,
      "total_cities": 3
    },
    "fedex": {
      "is_remote": true,
      "remote_type": "TIERB",
      "matched_city": "MAIRTOWN",
      "remote_cities": ["MAIRTOWN"],
      "total_cities": 3
    },
    "ups": {
      "is_remote": false,
      "total_cities": 3
    }
  }
}

返回字段说明

成功时 data 下会出现 dhl、fedex、tnt、ups 等承运商对象。

每个承运商对象包含 is_remote、remote_type、matched_city、matched_post，部分场景还会返回 remote_cities、total_cities。

当首查邮编对应多个城市，且 FedEx / UPS 中仍有未判偏远的载体时，会返回 query_cities 供客户端展示城市选择框。

说明

如果某个承运商没有结果，对应字段可能不存在。

自定义偏远渠道会按 expressType 作为动态字段名直接并入响应。

推荐流程：先仅传 country_code + city_or_post（邮编）首查；若响应里返回 query_cities，再让用户选择城市后连同 selected_city 再次调用。

本次更新后，邮编首查不会再自动把所有候选城市合并进 FedEx / UPS 结果，城市补查由 selected_city 显式触发。