EMS自助服务系统和大客户
接口规范
变更历史 日期 变更描述 版本号 V0.9 变更人 王一松 批准 2013-03-18 创建文档
1 总体说明
1.1 接口目的
本文包含了相关接口的数据格式、通讯格式。本文附录包含了接口使用的基础代码信息。 该文档约束了中国邮政速递物流EMS自助服务系统和大客户的接口规范，文档内容需严格保密。
1.2 接口规范
EMS自助服务系统和大客户接口建议采用http接口方式，同时支持webservice接口方式；
http接口编码格式均为UTF-8格式。
为保证单号正常获取，不影响用户使用。需在当天将打印后的数据更新到EMS自助服务系统（接口2.2）。
2 EMS自助服务客户端和大客户接口规范
2.1 根据大客户号、业务类型获取详情单号接口
功能描述 服务端 客户端 接口方式 接口地址 输入参数 通过大客户号，业务类型获取详情单号 EMS自助服务系统 大客户系统 HTTP http://os.ems.com.cn:8081/zkweb/bigaccount/getBigAccountDataAction.do?method=getBillNumBySys&xml=\ 大客户号、密码、业务种类、获取数量 输入参数格式定义 使用BASE64加密输入参数 ！！！特别注意：单号是唯一的，获取后本地保存时必须作为唯一索引。！！！ XML标记串：
功能描述 服务端 客户端 接口方式 接口地址 输入参数 将详情单打印信息更新到自助服务系统 EMS自助服务系统 大客户系统 HTTP http://os.ems.com.cn:8081/zkweb/bigaccount/getBigAccountDataAction.do?method=updatePrintDatas&xml=\ 大客户号、打印类型 将详情单信息按照xml格式封装成一个字符串传入系统进行数据更新 输入参数格式定义 使用BASE64加密输入参数 XML标记串：
3.1 调用身份验证
程序加载OCX过程中调用一次本方法即可，相当于登陆。 功能描述 接口方式 接口地址 输入参数 大客户系统调用EMS自助服务系统OCX身份验证 OCX EmsPrint.ocx（在EMS自助服务客户端安装根目录下） 大客户号，密码(小写MD5加密) 输入参数格式定义 单个字符串，使用#%分隔不同参数 参数示例：大客户号#%密码(小写MD5加密) 返回值格式定义 A1234567890Z#á0adc3949ba59abbe56e057f20f883e 单个字符串，使用#%分隔不同返回值字段 返回值示例 验证成功：1#%验证成功#%寄件城市 验证失败：0#%错误代码#%错误信息 参考方法名 错误信息定义 CheckID () 0#%网络连接失败 0#%该用户不存在 0#%ocx版本不一致,请更新客户端并登录一次后使用0#%当前版本... 0#%密码错误 0#%其他错误#%错误信息 备注 3.2 获取邮件号种类及邮件产品代码
功能描述 接口方式 接口地址 输入参数 输入参数格式定义 大客户系统调用EMS自助服务系统OCX打印详情单 OCX EmsPrint.ocx（在EMS自助服务客户端安装根目录下） ‘head|’开头，‘|end’结尾，参数字段以’|’分隔拼接的字符串，空值也需要用’|’占位。拼接完成后将整个字符串传入接口 字符串，‘head|’开头，‘|end’结尾。各字段值使用‘|’（英文竖线）分隔。拼接完成后使用整个字符串作为接口参数。空值也需要用’|’占位 businessType -- 业务类型，1为标准快递，2为代收货款，3为收件人付费，4为经济快递，不可传空 cargo_type -- 内件性质，3为物品，1为文件,传空默认为物品 tcustProvince -- 到件省 tcustCity -- 到件市 tcustCounty -- 到件县 输入参数示例 返回值格式定义 返回值说明 参考方法名 错误信息定义 head|businessType|cargo_type|tcustProvince|tcustCity|tcustCounty|end 单个字符串，使用‘#%’分隔不同返回值字段 返回值参数格式如下： 1#%单号类型#%产品代码 单号类型：1、标快单号（11开头），2、经快单号（51开头） getprtInfo(prtData) E007：请验证账号后使用 E011：参数错误 E999：错误信息(其他错误) 备注
3.3 大客户系统调用客户端OCX打印详情单
功能描述 接口方式 接口地址 输入参数 输入参数格式定义 大客户系统调用EMS自助服务系统OCX打印详情单 OCX EmsPrint.ocx（在EMS自助服务客户端安装根目录下） ‘head|’开头，‘|end’结尾，参数字段以’|’分隔拼接的字符串，空值也需要用’|’占位。拼接完成后将整个字符串传入接口 字符串，‘head|’开头，‘|end’结尾。各字段值使用‘|’（英文竖线）分隔。拼接完成后使用整个字符串作为接口参数。空值也需要用’|’占位 businessType -- 业务类型，1为标准快递，2为代收货款，3为收件人付费，4为经济快递，不可传空 billnoType -- 单号类型，1为标快，2为经快，“业务类型”为“代收货款”、“收件人付费”时不可传空 Billno -- 详情单号（运单号、邮件号） dateType -- 时间类型，1为收寄时间 ；2为打印时间 ；可传空 Procdate -- 收寄时间或打印时间，形式如“YYYY-MM-DD hh:mi:ss”，可精确到“秒”，时间类型为空时，本值可为空也可进行传值。 scontactor -- 寄件人姓名 scustMobile -- 寄件人联系方式1 scustTelplus -- 寄件人联系方式2(选填) scustPost -- 寄件人邮编 scustAddr -- 寄件人地址 tcontactor -- 收件人姓名 tcustMobile -- 收件人联系方式1 tcustTelplus -- 收件人联系方式2(选填) tcustPost -- 收件人邮编 tcustAddr -- 收件人地址 tcustProvince -- 到件省 tcustCity -- 到件市 tcustCounty -- 到件县 weight -- 寄件重量 insure -- 保价，每件最高投保金额以人民币5万元为限 fee -- 小写金额，代收货款和收件人付费不保留小数点； 标准快递和经济快递保留两位小数点 feeUppercase -- 大写金额（代收货款和收件人付费需要填写） cargoDesc -- 内件信息，根据货品的实际情况填写（对个别已与EMS和买家达成协议的，可只写货号，不写实际货物名称） bigAccountDataId -- 大客户数据的唯一标识，如某电商公司的配货单号 customerDn -- 大客户数据的客户订单号，主要是对于电商客户有用） mainBillNo -- 主单邮件号，分单对应的主单邮件号，可为空 blank1 -- 留白1 blank2 -- 留白2 字段 businessType billnoType Billno dateType procdate scontactor scustMobile scustTelplus scustPost scustAddr tcontactor tcustMobile tcustTelplus tcustPost tcustAddr 类型 订单信息 VARCHAR2(2 CHAR) VARCHAR2(2 CHAR) VARCHAR2(16 CHAR) VARCHAR2(2 CHAR) VARCHAR2(16 CHAR) VARCHAR2(50 CHAR) VARCHAR2(12 CHAR) VARCHAR2(12 CHAR) VARCHAR2(6 CHAR) VARCHAR2(200 CHAR) VARCHAR2(50 CHAR) VARCHAR2(30CHAR) VARCHAR2(30CHAR) VARCHAR2(6 CHAR) VARCHAR2(200 Not Null Not Null Not Null Not Null Not Null Not Null 业务类型 单号类型 详情单号 时间类型 时间值 寄件人姓名 寄件人联系方式1 寄件人联系方式2 寄件人邮编 Limit 说明 Not Null 寄件人地址 Not Null Not Null Not Null Not Null 收件人姓名 收件人联系方式1 收件人联系方式2 收件人邮编 收件人地址 CHAR) tcustProvince tcustCity tcustCounty weight insure fee feeUppercase cargoDesc bigAccountDataId VARCHAR2(20 CHAR) VARCHAR2(20 CHAR) VARCHAR2(20 CHAR) NUMBER(14,4) NUMBER(14,4) NUMBER(14,4) VARCHAR2(20 CHAR) VARCHAR2(100 CHAR) VARCHAR2(30 CHAR) Not Null Not Null Not Null Not Null 到件省 到件城市 到件县 寄件重量 保价 小写金额 大写金额 内件信息 大客户数据的唯一标识，如某电商公司的配货单号 大客户数据的客户订单号，主要是对于电商客户有用 主单邮件号，可为空 留白1 留白2 customerDn VARCHAR2(30 CHAR) mainBillNo blank1 blank2 VARCHAR2(20 CHAR) VARCHAR2(100 CHAR) VARCHAR2(100 CHAR) 输入参数示例 返回值格式定义 head|businessType|billnoType|Billno|dateType|procdate|scontactor|scustMobile|scustTelplus|scustPost|scustAddr|tcontactor|tcustMobile|tcustTelplus|tcustPost|tcustAddr|tcustProvince|tcustCity|tcustCounty|weight|insure|fee|feeUppercase|cargoDesc|bigAccountDataId|customerDn|mainBillNo|blank1|blank2|end 单个字符串，使用’#%’分隔不同返回值字段 返回值参数格式如下： 打印成功： 1#%打印成功 打印失败：0#%错误代码#%错误信息 localPrt(prtData) E007：请验证账号后使用 E011：参数错误 E021：您没有打印代收货款面单的权限，如有需要请向EMS申请开通 E022：您没有打印收件人付费面单的权限，如有需要请向EMS申请开通 E999：错误信息(其他错误) 参考方法名 错误信息定义 备注 已同步的订单信息打印前有变化时，需作为新订单获取新单号 4 附录：接口调用说明
本文档中各接口，根据对接系统处理方式的不同，提供以下两个分支的建议调用流程：
开始调用2.1接口请求单号对接系统保存单号自开发单号分配规则使用3.2接口获取单号分配规则给订单分配单号自开发面单打印使用3.3接口打印面单2.2接口数据回传结束 说明：
1、需调用ocx接口时，必须先调用3.1checkID接口。程序加载OCX过程中调用一次本方法即可，相当于登陆
2、单号获取后，给订单分配单号可选择对接系统完全自开发，也可使用3.2接口的返回值作为参考依据
3、对面单自定义需求较强的对接系统，建议完全自开发面单打印 4、订单打印后，建议对接系统尽可能及时的批量上传已打印数据
EMS自助服务系统和大客户接口规范V0.9（取单号打印后回传数据）
