运单服务-地址校验

基本信息

• 方法：POST
• 路径：/label/carrier/verifyAddress
• Handler：carrierApi.VerifyAddress
• Service：CarrierOpenAPIService.VerifyAddress

用途

调用承运商地址校验能力，返回标准化后的地址信息、地址分类和有效性结果。

请求参数

字段	类型	必填	说明
carrierCode	string	是	承运商代码
accountAlias	string	否	账号别名
accountId	int	否	预留字段，当前未使用
address	object	是	待校验地址，结构见下方地址对象字段

地址对象字段

用于 address 字段。

字段	类型	必填	说明
code	string	否	地址编码
name	string	否	名称/公司名
attentionName	string	否	联系人姓名
countryCode	string	是	国家代码，如 US
stateCode	string	否	州/省代码，如 CA、NY
city	string	否	城市
addressLine1	string	是	地址行 1
addressLine2	string	否	地址行 2
addressLine3	string	否	地址行 3
postalCode	string	是	邮编
phone	string	否	联系电话
phoneExtension	string	否	电话分机
email	string	否	邮箱
memo	string	否	备注
mid	string	否	MID 标识，部分国际件场景使用
isResidential	bool	否	是否住宅地址，默认 false
verifyStatus	int	否	地址校验状态，一般由响应回填，请求可不传

说明：Gin 绑定仅校验地址对象本身非空；实际调用时 countryCode、addressLine1、postalCode 为业务必填。

请求示例

{
  "carrierCode": "UPS",
  "accountAlias": "UPS_MAIN",
  "accountId": 0,
  "address": {
    "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",
    "isValid": true
  },
  "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
data.isValid	bool	是否有效，来源于 VerifyStatus == 1

接口说明

• 服务层会先解析账号，再调用对应平台服务的 VerifyAddress()
• 如果平台服务没有实现地址校验能力，会返回类似错误：

{
  "code": 400,
  "data": null,
  "message": "carrier GOFO does not support address verification"
}

账号解析规则

服务层统一通过 ResolveShipmentAccount() 解析账号，规则如下：

• 必填：carrierCode
• 可选：serviceCode
• 可选：accountAlias
• 如果筛选后只剩一个账号，直接使用
• 如果存在多个可用账号但没有传 accountAlias，会返回错误：存在多个可用账号，请提供 accountAlias 进行消歧

注意：请求体里虽然有 accountId，但当前实现没有使用它做账号解析，可以视为预留字段。