企业服务平台接入技术规范_V3.6_160507

更新时间:2024-06-06 09:05:01 阅读量: 综合文库 文档下载

说明:文章内容仅供预览,部分内容可能不全。下载后的文档,内容与下面显示的完全一致。下载之前请确认下面内容是否您想要的,是否完整无缺。

顺丰科技有限公司

企业服务平台接入规范

V3.6

系统与数据集成研发中心

16.2.19

?版权所有2015顺丰科技有限公司,未经顺丰科技有限公司/顺丰速运有限公司授权,不得向任何第三方透露本文档所含信息的全部或部分内容。

企业服务平台技术规范 – 目录

1. 目录

1. 目录 ......................................................................................................................................... 1 2. 前言 ......................................................................................................................................... 5 3. 接口规范说明 .......................................................................................................................... 6

3.1. 报文及报文编码 ........................................................................................................... 6 3.2. 通讯协议 ....................................................................................................................... 6 3.3. 接口规范说明 ............................................................................................................... 6

3.3.1. 接口基本信息说明............................................................................................. 6 3.3.2. XML报文说明 .................................................................................................... 7 3.3.3. 元素及元素属性说明 ......................................................................................... 8 3.4. 开发用公共接口信息 ................................................................................................... 9 4. 下订单(含筛选)接口 .........................................................................................................10

4.1. 功能描述 ......................................................................................................................10 4.2. 接口定义 ......................................................................................................................10

4.2.1. 接口基本信息 ...................................................................................................10 4.2.2. 元素<请求>Order ..............................................................................................10 4.2.3. 元素<请求>Order/Cargo ...................................................................................16 4.2.4. 元素<请求>Order/ AddedService(可选).......................................................17 4.2.5. 元素<响应> OrderResponse ..............................................................................17 4.2.6. 增值服务下单属性说明 ....................................................................................18 4.2.7. 扩展字段信息 ...................................................................................................19 4.2.8. 报文范例 ...........................................................................................................19

5. 订单确认/取消接口 ...............................................................................................................23

5.1. 功能描述 ......................................................................................................................23 5.2. 接口定义 ......................................................................................................................23

5.2.1. 接口基本信息 ...................................................................................................23 5.2.2. 元素<请求> OrderConfirm ................................................................................23 5.2.3. 元素<请求> OrderConfirm/OrderConfirmOption(可选) ...............................23 5.2.4. 元素<响应> OrderConfirmResponse .................................................................24 5.2.5. 扩展字段信息 ...................................................................................................24 5.2.6. 报文范例 ...........................................................................................................24

第 1页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 目录

6. 订单结果查询接口 .................................................................................................................26

6.1. 功能描述 ......................................................................................................................26 6.2. 接口定义 ......................................................................................................................26

6.2.1. 接口基本信息 ...................................................................................................26 6.2.2. 元素<请求> OrderSearch...................................................................................26 6.2.3. 元素<响应> OrderSearchResponse ...................................................................26 6.2.4. 报文范例 ...........................................................................................................27

7. 订单筛选接口 .........................................................................................................................28

7.1. 功能描述 ......................................................................................................................28 7.2. 接口定义 ......................................................................................................................28

7.2.1. 接口基本信息 ...................................................................................................28 7.2.2. 元素<请求> OrderFilter .....................................................................................28 7.2.3. 元素<请求> OrderFilter/OrderFilterOption(可选) ........................................29 7.2.4. 元素<响应> OrderFilterResponse ......................................................................30 7.2.5. 报文范例 ...........................................................................................................30

8. 人工筛单结果推送接口 .........................................................................................................32

8.1. 功能描述 ......................................................................................................................32 8.2. 接口定义 ......................................................................................................................32

8.2.1. 接口基本信息 ...................................................................................................32 8.2.2. 元素<请求> OrderFilterResult ...........................................................................32 8.2.3. 报文范例 ...........................................................................................................33

9. 路由查询接口 .........................................................................................................................35

9.1. 功能描述 ......................................................................................................................35 9.2. 接口定义 ......................................................................................................................35

9.2.1. 接口基本信息 ...................................................................................................35 9.2.2. 元素<请求> RouteRequest ................................................................................35 9.2.3. 元素<响应> RouteResponse ..............................................................................36 9.2.4. 元素<响应> RouteResponse/Route ...................................................................36 9.2.5. 报文范例 ...........................................................................................................37

10. 路由推送接口 .......................................................................................................................38

10.1. 功能描述 ....................................................................................................................38 10.2. 接口定义 ....................................................................................................................38

10.2.1. 接口基本信息 .................................................................................................38

第 2页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 目录

10.2.2. 元素<请求> WaybillRoute ...............................................................................38 10.2.3. 报文范例 .........................................................................................................39

11. 时效查询接口 .......................................................................................................................41

11.1. 功能描述 ....................................................................................................................41 11.2. 接口定义 ....................................................................................................................41

11.2.1. 接口基本信息 .................................................................................................41 11.2.2. 元素<请求> DeliverTmRequest .......................................................................41 11.2.3. 元素<请求> DeliverTmRequest/SrcAddress.....................................................42 11.2.4. 元素<请求> DeliverTmRequest/DestAddress ..................................................43 11.2.5. 元素<响应> DeliverTmResponse/DeliverTm....................................................43 11.2.6. 报文范例 .........................................................................................................44

12. 产品及增值服务查询接口 ...................................................................................................46

12.1. 功能描述 ....................................................................................................................46 12.2. 接口定义 ....................................................................................................................46

12.2.1. 接口基本信息 .................................................................................................46 12.2.2. 元素<请求> Scope ...........................................................................................46 12.2.3. 元素<响应> Scope/Service ..............................................................................46 12.2.4. 产品/增值服务客户属性说明.........................................................................47 12.2.5. 报文范例 .........................................................................................................47

13. 子单号申请接口 ...................................................................................................................48

13.1. 功能描述 ....................................................................................................................48 13.2. 接口定义 ....................................................................................................................48

13.2.1. 接口基本信息 .................................................................................................48 13.2.2. 元素<请求> OrderZDService ............................................................................48 13.2.3. 元素<响应> OrderZDResponse ........................................................................48 13.2.4. 报文范例 .........................................................................................................48

14. 身份证图片查询接口 ...........................................................................................................50

14.1. 功能描述 ....................................................................................................................50 14.2. 接口定义 ....................................................................................................................50

14.2.1. 接口基本信息 .................................................................................................50 14.2.2. 元素<请求> IdentitySearch..............................................................................50 14.2.3. 元素<响应> IdentitySearchResponse ..............................................................50 14.2.4. 报文范例 .........................................................................................................50

第 3页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 目录

15. 附录 ......................................................................................................................................54

15.1. 原因代码表 ................................................................................................................54 15.2. 快件产品类别表 ........................................................................................................57 15.3. 其它参考材料 ............................................................................................................59

第 4页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口

4. 下订单(含筛选)接口

4.1. 功能描述

下订单接口根据客户需要,可提供以下三个功能:

1) 客户系统向顺丰下发订单。 2) 为订单分配运单号。

3) 筛单(可选,具体商务沟通中双方约定,由顺丰内部为客户配置)。

此接口也用于路由推送注册。客户的顺丰运单号不是通过此下订单接口获取,但却需要获取BSP的路由推送时,需要通过此接口对相应的顺丰运单进行注册以使用BSP的路由推送接口。

4.2. 接口定义

4.2.1. 接口基本信息 服务名称 批量交易 接口类型 接口方法 OrderService 不支持 接入 String sfexpressService(String xml, String verifyCode) 4.2.2. 元素<请求>Order # 1 属性名 orderid 类型(约束) 必填 String(64) 是 默认值 描述 客户订单号 顺丰运单号,一个订单只能有一个母单号,如果是子母单的情况,以半角2 mailno String(4000) 条件 逗号分隔,主单号在第一个位置,如“755123456789,001123456789,002123456789”,对于路由推送注册,此字段为必填。 第 10页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口 # 属性名 is_gen_bill_no 类型(约束) 必填 Number(1) 默认值 _SYSTEM 描述 是否要求返回顺丰运单号: 3 否 ? 1:要求 ? 其它为不要求 4 5 6 7 8 9 j_company j_contact j_tel j_mobile j_shippercode j_country String(100) String(100) String(20) String(20) String(30) String(30) 条件 条件 条件 否 条件 否 _SYSTEM _SYSTEM _SYSTEM _SYSTEM 寄件方公司名称,如果需要生成电子运单,则为必填。 寄件方联系人,如果需要生成电子运单,则为必填。 寄件方联系电话,如果需要生成电子运单,则为必填。 寄件方手机 寄件方国家/城市代码,如果是跨境件,则此字段为必填。 寄方国家 寄件方所在省份 10 j_province String(30) 否 _SYSTEM 字段填写要求:必须是标准的省名称称谓 如:广东省,如果是直辖市,请直接传北京、上海等。 寄件方所在城市名称,字段填写要11 j_city String(100) 否 _SYSTEM 求:必须是标准的城市称谓 如:深圳市。 12 j_county String(30) 否 寄件人所在县/区,必须是标准的县/区称谓,示例:“福田区”。 寄件方详细地址,包括省市区,示13 j_address String(200) 条件 _SYSTEM 例:“广东省深圳市福田区新洲十一街万基商务大厦10楼” ,如果需要生成电子运单,则为必填。 14 j_post_code 15 d_company 16 d_contact 17 d_tel 第 11页 /共 59页

?版权所有2015顺丰科技有限公司

String(25) String(100) String(100) String(20) 条件 是 是 是 寄方邮编,跨境件必填(中国大陆,港澳台互寄除外)。 到件方公司名称 到件方联系人 到件方联系电话 企业服务平台技术规范 – 下订单(含筛选)接口 # 属性名 类型(约束) 必填 String(20) 否 默认值 描述 到件方手机 到件方代码,如果是跨境件,则要传这个字段,用于表示到方国家的城19 d_deliverycode String(30) 条件 市。如果此国家整体是以代理商来提供服务的,则此字段可能需要传国家编码。具体商务沟通中双方约定。 20 d_country String(30) 否 到方国家 到件方所在省份,必须是标准的省名称称谓 如:广东省,如果是直辖市,请直接传北京、上海等。如果此字段21 d_province String(30) 否 与d_city字段都有值,BSP则直接使用这两个值而不是通过对d_address进行地址识别获取。为避免地址识别不成功的风险,建议传输此字段。 到件方所在城市名称,必须是标准的城市称谓 如:深圳市,如果是直辖市,请直接传北京(或北京市)、上22 d_city String(100) 否 海(或上海市)等。如果此字段与d_province字段都有值,BSP则直接使用这两个值而不是对d_address进行地址识别获取。为避免地址识别不成功的风险,建议传输此字段。 23 d_county String(30) 否 到件方所在县/区,必须是标准的县/区称谓,示例:“福田区”。 到件方详细地址,如果不传输d_province/d_city字段,此详细地址24 d_address String(200) 是 需包含省市信息,以提高地址识别的成功率,示例:“广东省深圳市福田区新洲十一街万基商务大厦10楼”。 25 d_post_code String(25) 条件 到方邮编,跨境件必填(中国大陆,港澳台互寄除外)。 18 d_mobile 第 12页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口 # 属性名 类型(约束) 必填 String(20) 条件 默认值 _SYSTEM 描述 顺丰月结卡号 付款方式: 27 pay_method Number(1) 否 1 _SYSTEM ? 1:寄方付 ? 2:收方付 ? 3:第三方付 28 express_type String(5) 否 1 _SYSTEM 快件产品类别,详见附录《快件产品类别表》,只有在商务上与顺丰约定的类别方可使用。 包裹数,一个包裹对应一个运单号,29 parcel_quantity Number(5) 否 1 如果是大于1个包裹,则返回则按照子母件的方式返回母运单号和子运单号。 30 cargo_length 31 cargo_width 32 cargo_height Number(10, 3) 否 Number(10, 3) 否 Number(10, 3) 否 客户订单货物总长,单位厘米,精确到小数点后3位,包含子母件。 客户订单货物总宽,单位厘米,精确到小数点后3位,包含子母件。 客户订单货物总高,单位厘米,精确到小数点后3位,包含子母件。 订单货物总体积,单位立方厘米,精33 volume Number(17,3) 否 确到小数点后3位,会用于计抛(是否计抛具体商务沟通中双方约定)。 34 cargo_total_weight 订单货物总重量,包含子母件,单位Number(10,3) 否 千克,精确到小数点后3位,如果提供此值,必须>0 。 客户订单货物总声明价值,包含子母35 declared_value Number(15, 3) 条件 件,精确到小数点后3位。如果是跨境件,则必填。 26 custid 第 13页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口 # 属性名 类型(约束) 必填 默认值 描述 货物声明价值币别,支持以下值: ? CNY: 人民币 ? HKD: 港币 ? USD: 美元 ? NTD: 新台币 如果目的地是中国36 declared_value_currency 大陆的,String(5) 否 则默认为CNY,否则默认为USD ? RUB: 卢布 ? EUR: 欧元 ? MOP: 澳门元 ? SGD: 新元 ? JPY: 日元 ? KRW: 韩元 ? MYR: 马币 ? VND: 越南盾 ? THB: 泰铢 ? AUD: 澳大利亚元 ? MNT: 图格里克 跨境件报关需要填写 37 customs_batchs String(20) 否 _SYSTEM BSP接收38 sendstarttime Date 否 到XML报文的时间 报关批次 要求上门取件开始时间,格式:YYYY-MM-DD HH24:MM:SS,示例:2012-7-30 09:30:00。 是否要求通过是否手持终端通知顺丰39 is_docall Number(1) 否 _SYSTEM 收派员收件: ? 1:要求 ? 其它为不要求 40 need_return_tracking_no 是否要求签回单号: String(2) String(30) String(30) 否 否 否 ? 1:要求 ? 其它为不要求 41 return_tracking 42 d_tax_no 顺丰签回单服务运单号 收件人税号 第 14页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口

j_contact='小雷' j_tel='13810744' j_mobile='13111744' j_province='广东省' j_city='深圳' j_county='福田区'

j_address='罗湖火车站东区调度室' d_company='顺丰速运' d_contact='小邱' d_tel='15819050'

d_mobile='15539050'

d_address='北京市海淀区中关村' express_type='1' pay_method='1'

parcel_quantity='1' cargo_length='33' cargo_width='33' cargo_height='33' remark=''>

name='LV1' count='3' unit='a' weight='' amount='' currency=''

source_area=''>

name='LV2' count='3' unit='a' weight='' amount='' currency=''

source_area=''>

value1='0123456789'>

第 20页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口

e2=”abc”/>

? 跨境件:

BSPdevelop

orderid='TEST_201501290001' j_company='SFSingapore' j_contact='PeterK' j_tel='12345678' j_mobile='12345678' j_shippercode='SIN01D' j_country='SG'

j_province='Singapore' j_city='Singapore' j_county='Singapore'

j_address='7SixthLokYangRoad#11-11Singapore628105' j_post_code='628105' d_deliverycode='852' d_country='HK'

d_company='Daniel' d_contact='DanielLi' d_tel='87654321' d_mobile='87654321' d_province='Hong Kong' d_city='Hong Kong' d_county='Hong Kong'

d_address='27/Ftestaddress,Kowloon,HongKong' d_post_code='852852' custid='0650000001' pay_method='1' express_type='23' parcel_quantity='1'

cargo_total_weight='2.18' declared_value='1'

declared_value_currency='CNY'

sendstarttime='2014-12-1707:08:38' remark='beizhu'>

name='nailcare' count='20' unit='pcs'

weight='0.003' amount='0.05' currency='CNY'

source_area='China'>

响应XML:

? 订单处理成功:

o 中国大陆件:

第 21页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 下订单(含筛选)接口

OK

orderid=\mailno=\origincode=\destcode=\

filter_result=\

o 跨境件:

OK

orderid=\mailno=\origincode=\destcode=\

filter_result=\

? 订单处理失败:

o 范例1:

ERR

o 范例2:

ERR

第 22页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单确认/取消接口

5. 订单确认/取消接口

5.1. 功能描述

该接口用于:

? 客户在确定将货物交付给顺丰托运后,将运单上的一些重要信息,如快件重量通过

此接口发送给顺丰。 ? 客户在发货前取消订单。

注意:订单取消之后,订单号也是不能重复利用的。

5.2. 接口定义

5.2.1. 接口基本信息 服务名称 批量交易 接口类型 接口方法 OrderConfirmService 不支持 接入 String sfexpressService(String xml, String verifyCode) 5.2.2. 元素<请求> OrderConfirm # 1 2 3 属性名 orderid mailno dealtype 类型(约束) 必填 String(64) String(20) Number(1) 是 条件 否 默认值 1 描述 客户订单号 顺丰母运单号(如果dealtype=1,必填) 客户订单操作标识: ? 1:确认 ? 2:取消 5.2.3. 元素<请求> OrderConfirm/OrderConfirmOption(可选) # 属性名 类型(约束) 必填 默认值 描述 第 23页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单确认/取消接口 # 属性名 weight 类型(约束) 必填 Number(10,3) 默认值 描述 订单货物总重量,包含子母件,单位1 否 千克,精确到小数点后2位,如果提供此值,必须>0。 货物的总体积(值为长,宽,高),包含子母件,以半角逗号分隔,单位2 volume String(100) 否 厘米,精确到小数点后2位,会用于计抛(是否计抛具体商务沟通中双方约定)。 3 return_tracking String(30) 否 顺丰签回单服务运单号 快件产品类别,详见附录《快件产品4 express_type String(5) 否 类别表》,只有在商务上与顺丰约定的类别方可使用。如果此字段为空,则以下单时的为准。 5 children_nos String(1000) 否 子单号(以半角逗号分隔)如果此字段为空,则以下订单时为准。 5.2.4. 元素<响应> OrderConfirmResponse # 1 2 属性名 orderid mailno 类型(约束) 必填 String(64) String(20) 是 条件 默认值 描述 客户订单号 顺丰母运单号(如果dealtype=1,必填) 备注 3 res_status Number(1) 是 ? 1:客户订单号与顺丰运单不匹配 ? 2 :操作成功 5.2.5. 扩展字段信息

此接口支持扩展字段,遵循扩展字段规范,参考XML报文说明。 5.2.6. 报文范例

请求XML,使用公共接口信息开发时,按需修改客户订单号及顺丰运单号(OrderConfirm元素中的orderid属性与mailno属性):

第 24页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单确认/取消接口

BSPdevelop

orderid='TE201500104' mailno='444003078326' dealtype='1'>

volume=’33,33,33’/>

响应XML:

? 订单确认成功:

OK

? 订单确认失败:

o 范例1

ERR

o 范例2

ERR

第 25页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单结果查询接口

6. 订单结果查询接口

6.1. 功能描述

因Internet环境下,网络不是绝对可靠,用户系统下订单到顺丰后,不一定可以收到BSP返回的数据,此接口用于在未收到返回数据时,查询下订单(含筛选)接口客户订单当前的处理情况。

6.2. 接口定义

6.2.1. 接口基本信息 服务名称 批量交易 接口类型 接口方法 OrderSearchService 不支持 接入 String sfexpressService(String xml, String verifyCode) 6.2.2. 元素<请求> OrderSearch # 1 属性名 orderid 类型(约束) 必填 String(64) 是 默认值 描述 客户订单号 6.2.3. 元素<响应> OrderSearchResponse # 1 属性名 orderid 类型(约束) 必填 String(64) 是 默认值 描述 客户订单号 顺丰运单号,一个订单只能有一个母单号,如果是子母单的情况,以半角2 mailno String(4000) 是 逗号分隔,主单号在第一个位置,如“755123456789,001123456789,002123456789”。 3 4 origincode destcode String(10) String(10) 是 是 原寄地区域代码 目的地区域代码 第 26页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单结果查询接口 # 属性名 类型(约束) 必填 默认值 描述 筛单结果: 5 filter_result Number(2) 否 ? 1:人工确认 ? 2:可收派 ? 3:不可以收派 如果filter_result=3时为必填,不可以收派的原因代码: 6 remark String(100) 否 ? 1:收方超范围 ? 2:派方超范围 ? 3-:其它原因 6.2.4. 报文范例

请求XML,使用公共接口信息开发时,按需修改客户订单号(OrderSearch元素中的orderid属性):

BSPdevelop

响应XML:

? 订单处理成功:

OK

orderid=\mailno=\origincode=\destcode=\

filter_result=\

? 订单处理失败:

ERR

第 27页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单筛选接口

7. 订单筛选接口

7.1. 功能描述

客户系统通过此接口向BSP发送主动的筛单请求,用于判断客户的收、派地址是否属于顺丰的收派范围。

7.2. 接口定义

7.2.1. 接口基本信息 服务名称 批量交易 接口类型 接口方法 OrderFilterService 最多5个OrderFilter元素 接入 String sfexpressService(String xml, String verifyCode) 7.2.2. 元素<请求> OrderFilter # 属性名 类型(约束) 必填 默认值 描述 筛单类别: ? 1:自动筛单(系统根据地址库进行判断,并返回结果,系统无法检索到可派送的将返回不可派送) 1 filter_type Number(1) 否 1 ? 2:可人工筛单(系统首先根据地址库判断,如果无法自动判断是否收派,系统将生成需要人工判断的任务,后续由人工处理,处理结束后,顺丰可主动推送给客户系统) 2 orderid String(64) 条件 客户订单号,filter_type=2则必须提供。 第 28页 /共 59页

?版权所有2015顺丰科技有限公司

企业服务平台技术规范 – 订单筛选接口 # 属性名 d_address 类型(约束) 必填 String(150) 默认值 描述 到件方详细地址,需要包括省市区,3 是 如:广东省深圳市福田区新洲十一街万基商务大厦。 7.2.3. 元素<请求> OrderFilter/OrderFilterOption(可选) # 1 2 3 属性名 j_tel country province 类型(约束) 必填 String(20) String (50) String (30) 否 否 否 默认值 CN 描述 寄件方电话 寄件人所在国家代码 寄件方所在省份,必须是标准的省名称称谓 如:广东省,如果是直辖市,请直接传北京、上海等。 4 5 6 7 city county d_country d_province String (100) String (30) String(50) String (30) 否 否 否 否 CN 寄件方所属城市名称,必须是标准的城市称谓 如:深圳市。 寄件人所在县/区,必须是标准的县/区称谓,示例:“福田区”。 到件方国家 到件方所在省份,必须是标准的省名称称谓 如:广东省,如果是直辖市,请直接传北京、上海等。 到件方所属城市名称,必须是标准的8 d_city String (100) 否 城市称谓 如:深圳市,如果是直辖市,请直接传北京(或北京市)、上海(或上海市)等。 9 d_county String (30) 否 到件方所在县/区,必须是标准的县/区称谓,示例:“福田区”。 寄件方详细地址,包括省市区,示10 j_address 11 d_tel 12 j_custid String(150) String(23) String(30) 否 否 否 例:“广东省深圳市福田区新洲十一街万基商务大厦10楼”。 到件方电话 结账号,用于在人工筛单时,筛单人员识别客户使用。 第 29页 /共 59页

?版权所有2015顺丰科技有限公司

本文来源:https://www.bwwdw.com/article/1xd6.html

Top