企业服务平台技术规范 – 前言
2. 前言
本文档目的是定义企业服务平台（后面简称BSP）的通用对外服务接口，以便快速集成大客户自有的系统，从而打通大客户与顺丰系统之间的信息流，实现整体物流供应链的一体化，进而达到顺丰与客户的双赢。
第 5页 /共 59页
?版权所有2015顺丰科技有限公司
企业服务平台技术规范 – 接口规范说明
3. 接口规范说明
3.1. 报文及报文编码
BSP统一使用UTF-8编码的XML报文。
BSP使用ORACLE数据库，以UTF-8编码形式保存数据，所以中文字符会在数据库中占varchar2类型的三个单位长度。例如，接口定义中的“类型（约束）”如果为String(100)，则表示对于此字段，如果字段值全部为中文汉字，只能保存33个单位。
3.2. 通讯协议
接口通信协议支持WEBSERVICE及HTTP/POST协议：
1) 当使用WEBSERVICE接口时，报文通过方法参数传入（两个参数分别为XML报文
及校验码）。
2) 当使用HTTP/POST接口时，通过一个名叫xml的参数传入XML报文，一个名叫
verifyCode的参数传入校验码。
其中校验码的生成规则为：
? 接入BSP前，顺丰BSP系统管理员会为每个接入客户分配一个“密钥”，以下把
密钥简称为checkword。 ? 按以下逻辑生成校验码：
o 先把XML报文与checkword前后连接。 o 把连接后的字符串做MD5编码。
o 把MD5编码后的数据进行Base64编码，此时编码后的字符串即为校验码。
3.3. 接口规范说明
3.3.1. 接口基本信息说明 以下表为例： 1 服务名称 第 6页 /共 59页
?版权所有2015顺丰科技有限公司
OrderService 企业服务平台技术规范 – 接口规范说明 2 批量交易 3 接口类型 4 接口方法 不支持 接入 String sfexpressService(String xml, String verifyCode) 1) 服务名称：此接口的服务名称。
2) 批量交易：此接口是否支持批量交易，若支持，则会说明所支持的元素/元素属性。 3) 接口类型：BSP接口分为接入与推送两类接口。 4) 接口方法：此接口的方法。 3.3.2. XML报文说明
BSP使用的XML报文需要遵循以下格式与规则：
? 请求XML报文：
o service 属性与Head元素预先定义了“服务名”及“接入编码”。 o “接入编码”统一由顺丰BSP系统管理员分配。
o lang属性用于定义响应报文的语言，缺省值为zh-CN，目前支持以下值zh-CN表示中文简体，zh-TW或zh-HK或zh-MO表示中文繁体，en表示英文。
? 响应XML报文：
o Head元素值为OK或ERR；OK代表交易成功，ERR代表发生系统或业务异
常，交易失败；对于批量交易场景，只能为成功/失败，无部分成功/部分失败，只要存在有未成功接收的信息即认为为失败。
o Head元素值为OK时只返回Body元素，为ERR时只返回Error元素，Body
与Error元素不能同时存在。
o Error元素中的code属性值为四位数字，错误编码的描述请参考附录《原
因代码表》。
第 7页 /共 59页
?版权所有2015顺丰科技有限公司
企业服务平台技术规范 – 接口规范说明
? 扩展字段
o 个别接口存在扩展字段，扩展字段使用数据元素下保留元素
进行定义。
o 字段的数目最多支持20个，超过20个的部分将被忽略。 o 属性名为e1,…,e20，只支持字符串值。
3.3.3. 元素及元素属性说明 以下表为例： 1 4.2.2. 元素<请求>Order # 1 2 2 属性名 orderid 3 4 类型（约束） 必填 String(64) 是 5 默认值 6 描述 客户订单号 顺丰运单号，一个订单只能有一个母单号，如果是子母单的情况，以半角mailno String(4000) 条件 逗号分隔，主单号在第一个位置，如“755123456789,001123456789,002123456789”，对于路由推送注册，此字段为必填。 3 is_gen_bill_no Number(1) 否 _SYSTEM 是否要求返回顺丰运单号： ? 1：要求 ? 其它为不要求 1) 元素标题，其中<请求>表示此元素属于请求XML报文中的元素，同样<响应>表示 其属于响应XML报文中的元素，Order表示此元素的名称，元素名称后若带“（可选）“代表此元素在XML报文中为可选的元素。 2) 属性名：属于此元素的属性名称，元素的属性也称字段。 第 8页 /共 59页 ?版权所有2015顺丰科技有限公司 企业服务平台技术规范 – 接口规范说明 3) 类型（约束）：表示此属性的数据类型，包括： o String(n)：n代表字节长度（中文汉字占3字节）。 o Number(m,n)：m代表总有效数字的位数，n代表小数点后的有效数字的位 数。 o Date：代表日期，格式为YYYY-MM-DD HH24:MM:SS。 4) 必填：表示此属性是否必填，包括： o 是：此属性为必填。 o 否：此属性为非必填。 o 条件：此属性在某条件下为必填，在描述中会对此说明。 5) 默认值：属性的默认值，如果接口定义中字段默认值标记有 “_SYSTEM”，则表示这 个字段可由顺丰内部为客户配置。 6) 描述：此属性的意义，用途及注意事项的说明。 3.4. 开发用公共接口信息 客户开发时可调用以下公共接口，具体联调需与商务人员沟通安排联调日程。 ? · WEBSERVICE地址 ? http://bspoisp.sit.sf-express.com:11080/bsp-oisp/ws/sfexpressService?wsdl ? 或者 ? https://bspoisp.sit.sf-express.com:11443/bsp-oisp/ws/sfexpressService?wsdl ? ? ? ·HTTP/POST地址 ? http://bspoisp.sit.sf-express.com:11080/bsp-oisp/sfexpressService ? 或者 ? https://bspoisp.sit.sf-express.com:11443/bsp-oisp/sfexpressService ? 开发环境接入编码：BSPdevelop ? 开发环境Checkword：j8DzkIFgmlomPt0aLuwU ? BSP接口开发咨询QQ群号码：314535266 第 9页 /共 59页 ?版权所有2015顺丰科技有限公司