EMS自助服务系统和大客户接口规范V09取单号打印后回传数据.docx

1、EMS自助服务系统和大客户接口规范V09取单号打印后回传数据EMS自助服务系统和大客户接口规范变更历史日期变更描述版本号变更人批准2013-03-18创建文档V0.9王一松1 总体说明1.1 接口目的本文包含了相关接口的数据格式、通讯格式。本文附录包含了接口使用的基础代码信息。该文档约束了中国邮政速递物流EMS自助服务系统和大客户的接口规范，文档内容需严格保密。1.2 接口规范EMS自助服务系统和大客户接口建议采用http接口方式，同时支持webservice接口方式；http接口编码格式均为UTF-8格式。为保证单号正常获取，不影响用户使用。需在当天将打印后的数据更新到EMS自助服务系统（接

2、口2.2）。2 EMS自助服务客户端和大客户接口规范2.1 根据大客户号、业务类型获取详情单号接口功能描述通过大客户号，业务类型获取详情单号服务端EMS自助服务系统客户端大客户系统接口方式HTTP接口地址.cn:8081/zkweb/bigaccount/getBigAccountDataAction.do?method=getBillNumBySys&xml=输入参数大客户号、密码、业务种类、获取数量输入参数格式定义使用BASE64加密输入参数！特别注意：单号是唯一的，获取后本地保存时必须作为唯一索引。！XML标记串：/大客户号，必填，代码调试期间请务必传入大客户号：A90Z/大客户密码，必

3、填，小写md5加密，e10adc3949ba59abbe56e057f20f883e/对接方平台id，作为接口调用方的身份凭据，由接口提供方提供/业务类型，必填，1为标准快递，4为经济快递（传数字）需要详情单数量，最多输入100个字段类型Limit说明订单信息sysAccountVARCHAR2(20 CHAR)NotNull大客户号passWordVARCHAR2(40 CHAR)Not Null密码（MD5 加密，全小写，32位）appKeyVARCHAR2(20 CHAR)平台id，暂时留空billNoAmountVARCHAR2(5 CHAR)Not Null 请求数量（1-100）返

4、回值格式定义使用BASE64加密返回值XML标记串：/是否执行成功，1是成功，0是失败/错误原因描述 /详情单号 . .参考方法名getBillNoBySys(xml)Webservice_:8081/zkweb/services/getPrintDatas?wsdlWebservice_name实现类EmsPrintService备注2.2 详情单打印信息更新到EMS自助服务系统接口功能描述将详情单打印信息更新到自助服务系统服务端EMS自助服务系统客户端大客户系统接口方式HTTP接口地址.cn:8081/zkweb/bigaccount/getBigAccountDataAction.do?

5、method=updatePrintDatas&xml=输入参数大客户号、打印类型将详情单信息按照xml格式封装成一个字符串传入系统进行数据更新输入参数格式定义使用BASE64加密输入参数XML标记串：/大客户号，必填/大客户密码，必填，小写md5加密，e10adc3949ba59abbe56e057f20f883e/对接方平台id，作为接口调用方的身份凭据，由接口提供方提供/打印类型，1为五联单打印，2为热敏打印，必填 /大客户数据的唯一标识，如某电商公司的配货单号，必填(订单如果打印条码,应为非13位数字) /详情单号，和配货单号对应，必填（详情单号打印条形码必须128码）/寄件人姓名/寄

6、件人联系方式1/寄件人联系方式2(选填) /寄件人邮编 /寄件人地址 /寄件人公司/收件人姓名/收件人联系方式1/收件人联系方式2(选填) /收件人邮编 /收件人地址 /收件人公司/到件省 /到件市/到件县 /寄件重量 /物品长度保价，每件最高投保金额以人民币5万元为限/保险/小写金额，代收货款和收件人付费不保留小数点；标准快递和经济快递保留两位小数点 /大写金额（代收货款和收件人付费需要填写） /业务类型，1为标准快递，2为代收货款，3为收件人付费，4为经济快递（传数字） /内件信息，根据货品的实际情况填写（对个别已与EMS和买家达成协议的，可只写货号，不写实际货物名称）/内件类型：（文件、

7、物品） /备注/对揽投员的投递要求，填写客户的个性化投递要求 /产品代码 /预留字段1 /预留字段2 /预留字段3 /预留字段4 /预留字段5 .字段类型Limit说明订单信息scontactorVARCHAR2(50 CHAR)NotNull寄件人姓名scustMobileVARCHAR2(20 CHAR)Not Null寄件人联系方式1scustTelplusVARCHAR2(20 CHAR)寄件人联系方式2scustPostVARCHAR2(6 CHAR)Not Null寄件人邮编scustAddrVARCHAR2(200 CHAR)Not Null 寄件人地址scustCompVARC

8、HAR2(50 CHAR)寄件人公司tcontactorVARCHAR2(50 CHAR)Not Null收件人姓名tcustPostVARCHAR2(6 CHAR)Not Null收件人邮编tcustAddrVARCHAR2(200 CHAR)Not Null收件人地址tcustCompVARCHAR2(50 CHAR)收件人公司tcustMobileVARCHAR2(30 CHAR)Not Null收件人联系方式1tcustTelplusVARCHAR2(30CHAR)收件人联系方式2tcustProvinceVARCHAR2(20 CHAR)Not Null到件省tcustCityVAR

9、CHAR2(20 CHAR)Not Null到件市tcustCountyVARCHAR2(20 CHAR)Not Null到件县weightNUMBER(14,4)寄件重量lengthNUMBER(14,4)物品长度RemarkVARCHAR2(100 CHAR)备注bigAccountDataIdVARCHAR2(30 CHAR)Not Null大客户数据的唯一标识，如某电商公司的配货单号billnoVARCHAR2(20 CHAR)Not Null详情单号customerDnVARCHAR2(30 CHAR)大客户数据的客户订单号，主要是对于电商客户有用insureNUMBER(14,4)

10、保价insuranceNUMBER(14,4)保险feeNUMBER(14,4)小写金额feeUppercaseVARCHAR2(20 CHAR)大写金额deliveryclaimVARCHAR2(100 CHAR)对揽投员的投递要求businessTypeVARCHAR2(10 CHAR)业务种类cargoDescVARCHAR2(100 CHAR)内件信息cargoTypeVARCHAR2(10CHAR)内件类型productCodeVARCHAR2(20CHAR)产品代码blank1VARCHAR2(100 CHAR)预留字段1blank2VARCHAR2(100 CHAR)预留字段2b

11、lank3VARCHAR2(100 CHAR)预留字段3blank4VARCHAR2(100 CHAR)预留字段4blank5VARCHAR2(100 CHAR)预留字段5返回值格式定义使用BASE64加密返回值XML标记串：/是否执行成功，1是成功，0是失败/错误原因描述参考方法名updatePrintEMSDatas(xml)Webservice_:8081/zkweb/services/getPrintDatas?wsdlWebservice_name实现类EmsPrintService备注3 OCX接口3.1 调用身份验证程序加载OCX过程中调用一次本方法即可，相当于登陆。功能描述大客

12、户系统调用EMS自助服务系统OCX身份验证接口方式OCX接口地址EmsPrint.ocx（在EMS自助服务客户端安装根目录下）输入参数大客户号，密码(小写MD5加密)输入参数格式定义单个字符串，使用#%分隔不同参数参数示例：大客户号#%密码(小写MD5加密)A90Z#%e10adc3949ba59abbe56e057f20f883e返回值格式定义单个字符串，使用#%分隔不同返回值字段返回值示例验证成功：1#%验证成功#%寄件城市验证失败：0#%错误代码#%错误信息参考方法名CheckID ()错误信息定义0#%网络连接失败0#%该用户不存在0#%ocx版本不一致,请更新客户端并登录一次后使用0

13、#%当前版本.0#%密码错误0#%其他错误#%错误信息备注3.2 获取邮件号种类及邮件产品代码功能描述大客户系统调用EMS自助服务系统OCX打印详情单接口方式OCX接口地址EmsPrint.ocx（在EMS自助服务客户端安装根目录下）输入参数head|开头，|end结尾，参数字段以|分隔拼接的字符串，空值也需要用|占位。拼接完成后将整个字符串传入接口输入参数格式定义字符串，head|开头，|end结尾。各字段值使用|（英文竖线）分隔。拼接完成后使用整个字符串作为接口参数。空值也需要用|占位businessType - 业务类型，1为标准快递，2为代收货款，3为收件人付费，4为经济快递，不可传空

14、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

15、：错误信息(其他错误)备注3.3 大客户系统调用客户端OCX打印详情单功能描述大客户系统调用EMS自助服务系统OCX打印详情单接口方式OCX接口地址EmsPrint.ocx（在EMS自助服务客户端安装根目录下）输入参数head|开头，|end结尾，参数字段以|分隔拼接的字符串，空值也需要用|占位。拼接完成后将整个字符串传入接口输入参数格式定义字符串，head|开头，|end结尾。各字段值使用|（英文竖线）分隔。拼接完成后使用整个字符串作为接口参数。空值也需要用|占位businessType - 业务类型，1为标准快递，2为代收货款，3为收件人付费，4为经济快递，不可传空billnoType -

16、 单号类型，1为标快，2为经快，“业务类型”为“代收货款”、“收件人付费”时不可传空Billno - 详情单号（运单号、邮件号）dateType - 时间类型，1为收寄时间 ；2为打印时间 ；可传空Procdate - 收寄时间或打印时间，形式如“YYYY-MM-DD hh:mi:ss”，可精确到“秒”，时间类型为空时，本值可为空也可进行传值。scontactor - 寄件人姓名scustMobile - 寄件人联系方式1scustTelplus - 寄件人联系方式2(选填)scustPost - 寄件人邮编scustAddr - 寄件人地址tcontactor - 收件人姓名tcustMob

17、ile - 收件人联系方式1tcustTelplus - 收件人联系方式2(选填)tcustPost - 收件人邮编tcustAddr - 收件人地址tcustProvince - 到件省tcustCity - 到件市tcustCounty - 到件县weight - 寄件重量insure - 保价，每件最高投保金额以人民币5万元为限fee - 小写金额，代收货款和收件人付费不保留小数点；标准快递和经济快递保留两位小数点feeUppercase - 大写金额（代收货款和收件人付费需要填写）cargoDesc - 内件信息，根据货品的实际情况填写（对个别已与EMS和买家达成协议的，可只写货号，不

18、写实际货物名称）bigAccountDataId - 大客户数据的唯一标识，如某电商公司的配货单号customerDn - 大客户数据的客户订单号，主要是对于电商客户有用）mainBillNo - 主单邮件号，分单对应的主单邮件号，可为空blank1 - 留白1blank2 - 留白2字段类型Limit说明订单信息businessTypeVARCHAR2(2 CHAR)Not Null业务类型billnoTypeVARCHAR2(2 CHAR)Not Null单号类型BillnoVARCHAR2(16 CHAR)Not Null详情单号dateTypeVARCHAR2(2 CHAR)时间类型p

19、rocdateVARCHAR2(16 CHAR)时间值scontactorVARCHAR2(50 CHAR) Not Null寄件人姓名scustMobileVARCHAR2(12 CHAR)Not Null寄件人联系方式1scustTelplusVARCHAR2(12 CHAR)寄件人联系方式2scustPostVARCHAR2(6 CHAR)Not Null寄件人邮编scustAddrVARCHAR2(200 CHAR)Not Null 寄件人地址tcontactorVARCHAR2(50 CHAR)Not Null收件人姓名tcustMobileVARCHAR2(30CHAR)Not N

20、ull收件人联系方式1tcustTelplusVARCHAR2(30CHAR)收件人联系方式2tcustPostVARCHAR2(6 CHAR)Not Null收件人邮编tcustAddrVARCHAR2(200 CHAR)Not Null收件人地址tcustProvinceVARCHAR2(20 CHAR)Not Null到件省tcustCityVARCHAR2(20 CHAR)Not Null到件城市tcustCountyVARCHAR2(20 CHAR)Not Null到件县weightNUMBER(14,4)寄件重量insureNUMBER(14,4)保价feeNUMBER(14,4)

21、小写金额feeUppercaseVARCHAR2(20 CHAR)大写金额cargoDescVARCHAR2(100 CHAR)内件信息bigAccountDataIdVARCHAR2(30 CHAR)Not Null大客户数据的唯一标识，如某电商公司的配货单号customerDnVARCHAR2(30 CHAR)大客户数据的客户订单号，主要是对于电商客户有用mainBillNoVARCHAR2(20 CHAR)主单邮件号，可为空blank1VARCHAR2(100 CHAR)留白1blank2VARCHAR2(100 CHAR)留白2输入参数示例head|businessType|billn

22、oType|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返回值格式定义单个字符串，使用#%分隔不同返回值

23、字段返回值参数格式如下：打印成功：1#%打印成功打印失败：0#%错误代码#%错误信息参考方法名localPrt(prtData)错误信息定义E007：请验证账号后使用E011：参数错误E021：您没有打印代收货款面单的权限，如有需要请向EMS申请开通E022：您没有打印收件人付费面单的权限，如有需要请向EMS申请开通E999：错误信息(其他错误)备注已同步的订单信息打印前有变化时，需作为新订单获取新单号4 附录：接口调用说明本文档中各接口，根据对接系统处理方式的不同，提供以下两个分支的建议调用流程：说明：1、需调用ocx接口时，必须先调用3.1checkID接口。程序加载OCX过程中调用一次本方法即可，相当于登陆2、单号获取后，给订单分配单号可选择对接系统完全自开发，也可使用3.2接口的返回值作为参考依据3、对面单自定义需求较强的对接系统，建议完全自开发面单打印4、订单打印后，建议对接系统尽可能及时的批量上传已打印数据