企业服务平台接入技术规范_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”/>