接口说明

该接口提供给第三方平台或是卖家自有系统。目前暂仅支持ontrac和usps服务校验地址。

注意：地址校验接口由于供应商环境限制，暂不支持沙箱环境测试，请直接调用生产环境

使用场景

Ontrac 服务：卖家使用Ontrac区域派送供应商，可以通过该接口验证收货人地址是否正确，并获取建议地址用于修正。减少因地址错误产生地址修正附加费或包裹投递失败。
USPS 服务：卖家使用USPS派送货物，可以通过该接口了解此地址是否被USPS识别，如可识别，USPS会提供该地址的规范输入地址；如不可识别，USPS会返回无法找到该地址，建议完善地址信息（注意：此接口仅做辅助下单参考，地址可识别不代表地址一定可以派送成功，地址不可识别不一定派送失败）

接口名称

winit.tools.address.addressValid

请求说明

请求内容	说明
URL	https://openapi.winit.com.cn/openapi/service
接口测试	https://sandboxopenapi.winit.com.cn/openapi/service
验证方法	Token,md5
格式	json
字符编码	UTF-8
http请求方式	http
请求数限制	默认每分钟100，100有需要可申请加大。

请求入参

名称	类型	必填	说明
type	string	Y	校验类型目前只支持ONTRAC和USPS
country	String	Y	国家 ISO国家码或全称
state	String	Y	州编码或全称
city	String	Y	城市
zipcode	String	Y	邮编
street	String	Y	街道
street2	String	N	街道2

请求示例

Ontrac

{
    "action": "winit.tools.address.addressValid",
    "app_key": "rebecca",
    "data": {
        "type":"ONTRAC",
        "state":"California",
        "city": "Hawthorne",
        "country": "US",
        "street": "13825 CRENSHAW",
        "street2": " BLV",
        "zipcode": "90250-7814"
    },
    "format": "json",
    "language": "zh_CN",
    "platform": "OWNERERP",
    "sign": "00000000000000000000000000000000",
    "sign_method": "md5",
    "timestamp": "2015-06-16 00:19:26",
    "version": "1.0"
}

USPS

{
    "action": "winit.tools.address.addressValid",
    "app_key": "rebecca",
    "data": {
        "type":"USPS",
        "state":"California",
        "city": "Hawthorne",
        "street": "13825 CRENSHAW",
        "street2": " BLV",
        "zipcode": "90250-7814"
    },
    "format": "json",
    "language": "zh_CN",
    "platform": "OWNERERP",
    "sign": "00000000000000000000000000000000",
    "sign_method": "md5",
    "timestamp": "2015-06-16 00:19:26",
    "version": "1.0"
}

返回出参

返回参数说明：正确的返回编码code：0及结果data，错误的返回错误码及错误信息msg。

名称	类型	必传	说明	示例
valid	Boolean	Y	校验结果	true-通过 false-不通过
errorMessage	String	N	错误信息
suggestionList	Object	N	建议地址列表 USPS 校验结果为true返回 Ontrac校验结果为false返回
– country	String	N	国家 Ontrac返回，USPS不返回
– state	String	Y	州
– city	String	Y	城市
– postalCode	String	Y	邮编
– streetName	String	N	街道
– streetName2	String	N	街道2 Ontrac不返回，USPS可能返回
– streetNumber	String	N	街道号 Ontrac返回，USPS不返回
– streetNumberLow	String	N	最小街道号 Ontrac返回，USPS不返回
– streetNumberHigh	String	N	最大街道号 Ontrac返回，USPS不返回
– streetSide	String	N	streetSide Ontrac返回，USPS不返回
– percentage	String	N	相似度 Ontrac返回，USPS不返回

返回示例

异常返回：

{
    "code": "02010260004",
    "msg": "检验失败:[state is null]",
    "data": ""
}

正常返回：

Ontrac校验通过

{
    "code": "0",
    "msg": "操作成功",
    "data": {
        "valid": true,
        "errorMessage": "",
        "scrubbedAddress": null,
        "suggestions": null,
        "error": false
    }
}

Ontrac校验不通过

{
    "code": "0",
    "msg": "操作成功",
    "data": {
        "valid": false,
        "errorMessage": null,
        "suggestions": [
            {
                "streetNumberLow": "13801",
                "streetNumberHigh": "13899",
                "streetSide": "Odd",
                "streetNumber": "13825",
                "streetName": "CRENSHAW BLVD",
                "country": "US",
                "city": "HAWTHORNE",
                "postalCode": "90250",
                "percentage": 95,
                "state": "CA"
            }
        ],
        "error": false
    }
}

USPS校验通过

{
    "code": "0",
    "msg": "操作成功",
    "data": {
        "valid": true,
        "errorMessage": null,
        "suggestions": [
            {
                "streetName": "CRENSHAW BLVD",
                "streetName2": "",
                "city": "HAWTHORNE",
                "postalCode": "90250",
                "state": "CA"
            }
        ],
        "error": false
    }
}

USPS校验不通过

{
        "code": "0",
        "msg": "操作成功",
        "data": {
                "valid": false,
                "errorMessage": "Address Not Found.",
                "scrubbedAddress": null,
                "suggestions": null,
                "error": true
        }
}

关键词