TMS 运单开放接口-地址校验

基本信息

方法：POST
路径：/label/verifyAddress

用途

调用承运商地址校验能力，返回标准化后的地址信息、地址分类。校验失败时返回 Address not found。

公共请求头

所有 TMS 运单开放接口都需要传以下请求头：

Content-Type: application/json
Apikey: {{api_key}}
Apisign: {{api_sign}}
Timestamp: {{timestamp}}

请求参数

请求体顶层直接是地址对象，完整字段同运单询价的地址对象字段。业务必填项如下：

字段	类型	必填	说明
countryCode	string	是	国家代码，如 `US`
addressLine1	string	是	地址行 1
postalCode	string	是	邮编
stateCode	string	否	州/省代码
city	string	否	城市
`name` / `attentionName`	string	否	名称/联系人
`phone` / `email`	string	否	联系方式
isResidential	bool	否	是否住宅地址

请求示例

{
  "name": "Verify Company",
  "attentionName": "Alice",
  "countryCode": "US",
  "stateCode": "IL",
  "city": "Chicago",
  "addressLine1": "100 E Randolph St",
  "addressLine2": "",
  "postalCode": "60601",
  "phone": "1234567890",
  "email": "demo@example.com",
  "isResidential": false
}

成功响应示例

{
  "code": 200,
  "data": {
    "countryCode": "US",
    "stateCode": "IL",
    "city": "Chicago",
    "addressLine1": "100 E Randolph St",
    "addressLine2": "",
    "postalCode": "60601",
    "classification": "COMMERCIAL"
  },
  "message": "success"
}

返回字段说明

字段	类型	说明
data.countryCode	string	国家代码
data.stateCode	string	州/省代码
data.city	string	城市
data.addressLine1	string	地址行 1
data.addressLine2	string	地址行 2
data.postalCode	string	邮编
data.classification	string	地址分类，`RESIDENTIAL` 或 `COMMERCIAL`

接口说明

仅当承运商返回有效地址时返回标准化地址，否则返回 Address not found
classification 取值取决于请求里的 isResidential：true → RESIDENTIAL，false → COMMERCIAL
该接口不写操作日志，适合下单前批量预校验

错误响应示例

{
  "code": 400,
  "data": null,
  "message": "Address not found"
}

code	message	场景
401	`请传入API授权信息`	缺少 `Apikey`
401	`请传入apiSign授权签名信息`	缺少 `Apisign`
400	由 Gin 绑定错误文本决定	参数绑定失败
400	`Address not found`	地址校验未通过

响应码约定：

成功时响应体 code = 200
参数校验或业务失败时，通常返回 code = 400
鉴权失败时，通常返回 code = 401
这套开放接口的成功码不是后台私有接口常见的 0

基本信息​

用途​

公共请求头​

请求参数​

请求示例​

成功响应示例​

返回字段说明​

接口说明​

错误响应示例​

基本信息

用途

公共请求头

请求参数

请求示例

成功响应示例

返回字段说明

接口说明

错误响应示例