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