资源描述
EMS自助服务系统和大客户
接口规范
变更历史
日期
变更描述
版本号
变更人
批准
2013-03-18
创建文档
V0.9
王一松
1 总体说明
1.1 接口目的
本文包含了相关接口的数据格式、通讯格式。本文附录包含了接口使用的基础代码信息。
该文档约束了中国邮政速递物流EMS自助服务系统和大客户的接口规范，文档内容需严格保密。
1.2 接口规范
EMS自助服务系统和大客户接口建议采用http接口方式，同时支持webservice接口方式；
http接口编码格式均为UTF-8格式。
为保证单号正常获取，不影响用户使用。需在当天将打印后的数据更新到EMS自助服务系统（接口2.2）。
2 EMS自助服务客户端和大客户接口规范
2.1 根据大客户号、业务类型获取详情单号接口
功能描述
通过大客户号，业务类型获取详情单号
服务端
EMS自助服务系统
客户端
大客户系统
接口方式
HTTP
接口地址
:8081/zkweb/bigaccount/getBigAccountDataAction.do?method=getBillNumBySys&xml=""
输入参数
大客户号、密码、业务种类、获取数量
输入参数格式定义
使用BASE64加密输入参数
！！！特别注意：单号是唯一的，获取后本地保存时必须作为唯一索引。！！！
XML标记串：
<?xml version="1.0" encoding="UTF-8"?>
<XMLInfo>
<sysAccount></sysAccount>//大客户号，必填，代码调试期间请务必传入大客户号：A1234567890Z
<passWord></passWord>//大客户密码，必填，小写md5加密，
e10adc3949ba59abbe56e057f20f883e
<appKey></appKey>//对接方平台id，作为接口调用方的身份凭据，由接口提供方提供
<businessType></businessType>//业务类型，必填，1为标准快递，4为经济快递（传数字）
<billNoAmount></billNoAmount>需要详情单数量，最多输入100个
</XMLInfo>
返回值格式定义
使用BASE64加密返回值
XML标记串：
<?xmlversion="1.0" encoding="UTF-8"?>
<response>
<result></result>//是否执行成功，1是成功，0是失败
<errorDesc></errorDesc>//错误原因描述
<assignIds>
<assignId>
<billno></billno>//详情单号
</assignId>
<assignId>
......
</assignId>
..........
<assignIds>
</response>
参考方法名
getBillNoBySys(xml)
Webservice_path
:8081/zkweb/services/getPrintDatas?wsdl
Webservice_name
实现类
EmsPrintService
备注
2.2 详情单打印信息更新到EMS自助服务系统接口
功能描述
将详情单打印信息更新到自助服务系统
服务端
EMS自助服务系统
客户端
大客户系统
接口方式
HTTP
接口地址
:8081/zkweb/bigaccount/getBigAccountDataAction.do?method=updatePrintDatas&xml=""
输入参数
大客户号、打印类型
将详情单信息按照xml格式封装成一个字符串传入系统进行数据更新
输入参数格式定义
使用BASE64加密输入参数
XML标记串：
<?xml version="1.0" encoding="UTF-8"?>
<XMLInfo>
<sysAccount></sysAccount>//大客户号，必填
<passWord></passWord>//大客户密码，必填，小写md5加密，
e10adc3949ba59abbe56e057f20f883e
<appKey></appKey>//对接方平台id，作为接口调用方的身份凭据，由接口提供方提供
<printKind></printKind>//打印类型，1为五联单打印，2为热敏打印，必填
<printDatas>
<printData>
<bigAccountDataId></bigAccountDataId>//大客户数据的唯一标识，如某电商公司的配货单号，必填(订单如果打印条码,应为非13位数字)
<billno></billno>//详情单号，和配货单号对应，必填（详情单号打印条形码必须128码）
<scontactor></scontactor>//寄件人姓名
<scustMobile></scustMobile>//寄件人联系方式1
<scustTelplus></scustTelplus>//寄件人联系方式2(选填)
<scustPost></ scustPost >//寄件人邮编
<scustAddr></scustAddr>//寄件人地址
<scustComp></scustComp>//寄件人公司
<tcontactor></ tcontactor>//收件人姓名
<tcustMobile></tcustMobile>//收件人联系方式1
<tcustTelplus></tcustTelplus>//收件人联系方式2(选填)
<tcustPost></ tcustPost >//收件人邮编
<tcustAddr></tcustAddr>//收件人地址
<tcustComp></tcustComp>//收件人公司
<tcustProvince></tcustProvince>//到件省
<tcustCity></tcustCity>//到件市
<tcustCounty></tcustCounty>//到件县
<weight></weight>//寄件重量
<length></length>//物品长度
<insure></insure>保价，每件最高投保金额以人民币5万元为限
<insurance></insurance>//保险
<fee></fee>//小写金额，代收货款和收件人付费不保留小数点；
标准快递和经济快递保留两位小数点
<feeUppercase></feeUppercase>//大写金额（代收货款和收件人付费需要填写）
<businessType></businessType>//业务类型，1为标准快递，2为代收货款，3为收件人付费，4为经济快递（传数字）
<cargoDesc></cargoDesc> //内件信息，根据货品的实际情况填写（对个别已与EMS和买家达成协议的，可只写货号，不写实际货物名称）
<cargoType></cargoType>//内件类型：（文件、物品）
<remark></remark>//备注
<deliveryclaim></deliveryclaim>//对揽投员的投递要求，填写客户的个性化投递要求
<productCode></productCode>//产品代码
<blank1></blank1>//预留字段1
<blank2></blank2>//预留字段2
<blank3></blank3>//预留字段3
<blank4></blank4>//预留字段4
<blank5></blank5>//预留字段5
</ printData >
<printData >
……
</printData >
........
</printDatas>
</XMLInfo>
字段
类型
Limit
说明
订单信息
scontactor
VARCHAR2(50 CHAR)
Not
Null
寄件人姓名
scustMobile
VARCHAR2(20 CHAR)
Not Null
寄件人联系方式1
scustTelplus
VARCHAR2(20 CHAR)
寄件人联系方式2
scustPost
VARCHAR2(6 CHAR)
Not Null
寄件人邮编
scustAddr
VARCHAR2(200 CHAR)
Not Null
寄件人地址
scustComp
VARCHAR2(50 CHAR)
寄件人公司
tcontactor
VARCHAR2(50 CHAR)
Not Null
收件人姓名
tcustPost
VARCHAR2(6 CHAR)
Not Null
收件人邮编
tcustAddr
VARCHAR2(200 CHAR)
Not Null
收件人地址
tcustComp
VARCHAR2(50 CHAR)
收件人公司
tcustMobile
VARCHAR2(30 CHAR)
Not Null
收件人联系方式1
tcustTelplus
VARCHAR2(30
CHAR)
收件人联系方式2
tcustProvince
VARCHAR2(20 CHAR)
Not Null
到件省
tcustCity
VARCHAR2(20 CHAR)
Not Null
到件市
tcustCounty
VARCHAR2(20 CHAR)
Not Null
到件县
weight
NUMBER(14,4)
寄件重量
length
NUMBER(14,4)
物品长度
Remark
VARCHAR2(100 CHAR)
备注
bigAccountDataId
VARCHAR2(30 CHAR)
Not Null
大客户数据的唯一标识，如某电商公司的配货单号
billno
VARCHAR2(20 CHAR)
Not Null
详情单号
customerDn
VARCHAR2(30 CHAR)
大客户数据的客户订单号，主要是对于电商客户有用
insure
NUMBER(14,4)
保价
insurance
NUMBER(14,4)
保险
fee
NUMBER(14,4)
小写金额
feeUppercase
VARCHAR2(20 CHAR)
大写金额
deliveryclaim
VARCHAR2(100 CHAR)
对揽投员的投递要求
businessType
VARCHAR2(10 CHAR)
业务种类
cargoDesc
VARCHAR2(100 CHAR)
内件信息
cargoType
VARCHAR2(10
CHAR)
内件类型
productCode
VARCHAR2(20
CHAR)
产品代码
blank1
VARCHAR2(100 CHAR)
预留字段1
blank2
VARCHAR2(100 CHAR)
预留字段2
blank3
VARCHAR2(100 CHAR)
预留字段3
blank4
VARCHAR2(100 CHAR)
预留字段4
blank5
VARCHAR2(100 CHAR)
预留字段5
返回值格式定义
使用BASE64加密返回值
XML标记串：
<?xmlversion="1.0" encoding="UTF-8"?>
<response>
<result></result>//是否执行成功，1是成功，0是失败
<errorDesc></errorDesc>//错误原因描述
</response>
参考方法名
updatePrintEMSDatas(xml)
Webservice_path
:8081/zkweb/services/getPrintDatas?wsdl
Webservice_name
实现类
EmsPrintService
备注
3 OCX接口
3.1 调用身份验证
程序加载OCX过程中调用一次本方法即可，相当于登陆。
功能描述
大客户系统调用EMS自助服务系统OCX身份验证
接口方式
OCX
接口地址
EmsPrint.ocx（在EMS自助服务客户端安装根目录下）
输入参数
大客户号，密码(小写MD5加密)
输入参数格式定义
单个字符串，使用#%分隔不同参数
参数示例：大客户号#%密码(小写MD5加密)
A1234567890Z#%e10adc3949ba59abbe56e057f20f883e
返回值格式定义
单个字符串，使用#%分隔不同返回值字段
返回值示例
验证成功：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
字段
类型
Limit
说明
订单信息
businessType
VARCHAR2(2 CHAR)
Not Null
业务类型
billnoType
VARCHAR2(2 CHAR)
Not Null
单号类型
Billno
VARCHAR2(16 CHAR)
Not Null
详情单号
dateType
VARCHAR2(2 CHAR)
时间类型
procdate
VARCHAR2(16 CHAR)
时间值
scontactor
VARCHAR2(50 CHAR)
Not Null
寄件人姓名
scustMobile
VARCHAR2(12 CHAR)
Not Null
寄件人联系方式1
scustTelplus
VARCHAR2(12 CHAR)
寄件人联系方式2
scustPost
VARCHAR2(6 CHAR)
Not Null
寄件人邮编
scustAddr
VARCHAR2(200 CHAR)
Not Null
寄件人地址
tcontactor
VARCHAR2(50 CHAR)
Not Null
收件人姓名
tcustMobile
VARCHAR2(30CHAR)
Not Null
收件人联系方式1
tcustTelplus
VARCHAR2(30CHAR)
收件人联系方式2
tcustPost
VARCHAR2(6 CHAR)
Not Null
收件人邮编
tcustAddr
VARCHAR2(200 CHAR)
Not Null
收件人地址
tcustProvince
VARCHAR2(20 CHAR)
Not Null
到件省
tcustCity
VARCHAR2(20 CHAR)
Not Null
到件城市
tcustCounty
VARCHAR2(20 CHAR)
Not Null
到件县
weight
NUMBER(14,4)
寄件重量
insure
NUMBER(14,4)
保价
fee
NUMBER(14,4)
小写金额
feeUppercase
VARCHAR2(20 CHAR)
大写金额
cargoDesc
VARCHAR2(100 CHAR)
内件信息
bigAccountDataId
VARCHAR2(30 CHAR)
Not Null
大客户数据的唯一标识，如某电商公司的配货单号
customerDn
VARCHAR2(30 CHAR)
大客户数据的客户订单号，主要是对于电商客户有用
mainBillNo
VARCHAR2(20 CHAR)
主单邮件号，可为空
blank1
VARCHAR2(100 CHAR)
留白1
blank2
VARCHAR2(100 CHAR)
留白2
输入参数示例
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 附录：接口调用说明
本文档中各接口，根据对接系统处理方式的不同，提供以下两个分支的建议调用流程：
说明：
1、 需调用ocx接口时，必须先调用3.1checkID接口。程序加载OCX过程中调用一次本方法即可，相当于登陆
2、 单号获取后，给订单分配单号可选择对接系统完全自开发，也可使用3.2接口的返回值作为参考依据
3、 对面单自定义需求较强的对接系统，建议完全自开发面单打印
4、 订单打印后，建议对接系统尽可能及时的批量上传已打印数据
展开阅读全文
浙ICP备2021020529号-1 | 浙B2-20240490 
