华南通用下单对接文档


1-路由推送接口

路由推送接口-速运类API

RoutePushService
1. 功能描述

  • 该接口用于当路由信息生产后向客户主动推送要求的顺丰运单路由信息。推送方式为增量推送,对于同一个顺丰运单的同一个路由节点,不重复推送。仅推送通过丰桥接口下单的订单路由信息。

    不管您的下订单是在测试环境，还是在生产环境，当您选择了路由推送接口并填写了接收地址，下单会自动生成测试路由并推送。贵司接口能正常接收并正确响应，则测试成功。

    客户需提供一个符合以下规范的HTTP URL,以接收顺丰系统推送的信息。

    • 请求方法为:"json"或"form",客户可从配置选项中选择请求方法。

    \1) 请求方法为"json"时,数据类型为"application/json ;charset=UTF-8";

    \2) 请求方法为"form"时,数据类型为"application/x-www-form-urlencoded; charset=UTF-8 "; 请求参数为"content";数据是以URL编码(字符集为UTF-8)的XML。

    • 请求方式为:HTTP POST方式推送给客户。

    • 请求方法为"form"时,客户通过"content"字段接收到数据后,需要先对其进行URL解码,得到相应的XML;请求方法为"json"时,客户可直接从请求的数据流中得到相应的json。

    • 1.请求方法为form，在客户处理XML信息后,向顺丰系统返回响应XML报文,响应XML报文结果只能为OK/ERR(参见XML报文说明),顺丰系统将重新推送此次交易的所有信息;

    • 2.请求方法为json，客户处理完Json信息后，向顺丰系统返回响应json报文，响应Json报文结果包含【return_code（0000:成功 1000：失败）、return_msg】

    • 沙箱环境推送频率:10min/次,沙箱测试环境每单固定推送两条路由数据
2. 接口定义
2.1. 公共参数
名称 值
接口服务代码 RoutePushService
批量交易 最多10个WaybillRoute元素
接口类型 推送
报文类型 application/x-www-form-urlencoded
2.2. 公共请求参数
2.3. 请求参数 /WaybillRoute
# 属性名 类型（约束） 必填 默认值 描述
1 mailno String 客户运单号
2 acceptAddress String 收货地址
3 reasonName String 异常描述
4 orderid String 客户订单号
5 acceptTime String 收货时间
6 remark String 备注
7 opCode String 操作码
8 reasonName String 异常描述
9 id String ID
10 reasonCode String 异常编码

注意事项:

  • 1)需要与顺丰商务人员沟通确认路由信息的语言，目前支持中文简体，中文繁体和英文。

  • 2)需要与顺丰商务人员沟通确认推送的方式：

    • 标准路由推送，可从顺丰商务人员处获取顺丰标准推送路由节点信息列表;

    -定制路由推送，须与顺丰商务人员沟通，客户可基于顺丰所有路由节点（列表可从顺丰商务人员处获取）定制所需的路由节点及其具体描述与操作码。

  • 查看路由信息操作码。
2.4. 响应参数 
# 元素名 类型（约束） 必填 描述
1 return_code String Y 返回响应码
2 return_msg String Y 返回消息
2.5. 请求示例\应用场景(JSON)示例

请求报文:

{
    "Body": {
        "WaybillRoute": [{
            "mailno": "SF7444400031887",
            "acceptAddress": "test",
            "reasonName": "",
            "orderid": "202003225d33322239ddW1df5t3",
            "acceptTime": "2020-05-11 16:56:54",
            "remark": "test",
            "opCode": "50",
            "id": "158918741444476",
            "reasonCode": ""
        },
        {
            "mailno": "SF7444400031887",
            "acceptAddress": "test",
            "reasonName": "",
            "orderid": "202003225d33322239ddW1df5t3",
            "acceptTime": "2020-05-11 16:56:54",
            "remark": "test",
            "opCode": "80",
            "id": "158918741457126",
            "reasonCode": ""
        }]
    }
}
2.6. 返回示例\应用场景(JSON)示例

响应报文:

  • 成功响应:
{
    "return_code": "0000",
    "return_msg": "成功"
}
  • 失败报文-范例1
{
    "return_code": "1000",
    "return_msg": "系统异常"
}
2.7. 请求示例\应用场景(XML)示例

请求报文:

2.8. 返回示例\应用场景(XML)示例

响应报文:

  • 成功响应:

OK
  • 失败报文-范例1

ERR
系统发生数据错误或运行时异常
3.1. 错误代码
3.1 （API）平台结果代码列表
标识 说明 【处理建议】
A1000 统一接入平台校验成功，调用后端服务成功； 注意：不代表后端业务处理成功，实际业务处理结果， 需要查看响应属性apiResultData中的详细结果
A1001 必传参数不可为空 serviceCode 已作废 requestID timestamp 已作废 msgData 不可为空
A1002 请求时效已过期 时效参考auth2 https://open.sf-express.com/customerService/395002?interId=590549&faqId=4
A1003 IP无效 参考常见问题 https://open.sf-express.com/customerService/395002?activeIndex=905584&interId=590549&faqId=2
A1004 无对应服务权限 联系销售经理，配置权限
A1005 流量受控 测试环境流量限制为5000，请不要在测试环境做压测
A1006 数字签名无效 参考常见问题 签名加解密问题 https://open.sf-express.com/customerService/395002?activeIndex=905584&interId=795986
A1007 重复请求 过一分钟在尝试
A1008 数据解密失败
A1009 目标服务异常或不可达
A1099 系统异常
3.2 业务异常代码
原因代码 errorCode 描述 errorMsg 分类
S0000 成功 是
S0001 非法的JSON格式 系统错误
S0002 必填参数为空 系统错误
S0003 系统发生数据错误或运行时异常 系统错误

页面列表

ITEM_HTML