一、总概 1.1、通讯协议遵循 HTTP (1.0/1.1) 1.2、数据包装采用JSON,遵循RFC4627 非ASCII字符编码:UTF-8 (65001) 或者 \u转义 *特别提示,共有8个ASCII码采用x编码转义: "(双引号) = \x22 \(反斜杠) = \x5C /(斜杠) = \x2F (换行符) = \x0A (回车符) = \x0D (制表符) = \x09 (罕用) (退格符) = \x08 (极罕用) (换页符) = \x0C (极罕用) *POST数据,遵循上述编码规则,建议不进行URL_Encode(定义URL_ENCODE=1,强制URL_ENCODE) 1.3、接口API为:“/cgi-bin/GInfo.dll?DoApi” 1.4、接口请求方式为:POST 1.5、安全控制,MD5数字签名,绑定客户ID、客户密钥,通过与时间戳生成摘要码验证。 1.6、服务器程序配置: GInfo服务器需要有Api接口授权(ems_api.ini)。 二、JSON命名规范 2.1、RequestName:发起请求名称,为请求方的第一个顶级成员名称,定义如下: {"RequestName":"TimeStamp"}: *服务器时间戳获取 {"RequestName":"GenerateMD5","cString":"1881405534421123xxxxxxxx"}: *获取MD5,用于调试 {"RequestName":"sEPostUpload","icID":79,"TimeStamp":1405534421123,"MD5":"6c08ea4dff56d5a7a959c09f121c3c4f",...}: 提交eub数据,获取eub单号 {"RequestName":"sEPostPdf","icID":79,"TimeStamp":1405534421123,"MD5":"6c08ea4dff56d5a7a959c09f121c3c4f","cqNo":"LN562467349CN"}: 下载eub的标签(pdf格式) {"RequestName":"sGetLabel","icID":79,"TimeStamp":1405534421123,"MD5":"6c08ea4dff56d5a7a959c09f121c3c4f",...}: 下载系统模板生成的PDF标签 2.1.2、所有以小写"s"打头的接口,都必须包含成员变量:icID、TimeStamp、MD5。 2.1.2.1、icID:客户在EMMis中建档时由系统生成的唯一整数值,同时还应该点击“客户API密钥”,为客户设置密钥(修改密钥通常需要重新启动www服务) 2.1.2.2、TimeStamp:时间戳,1970.1.1 0:0:0开始到请求时刻的毫秒数(UTC),13位整数。注意北京时间为东8区,需要调整时差。 2.1.2.3、MD5:数字签名,=MD5(icID+TimeStamp+客户密钥) *比如客户密钥为“1234ABCD”,如上例程为:MD5("7914055344211231234ABCD")="306f241be2d5963f20be2966f9961f55" 2.2、ReturnValue:响应返回状态码,为响应方的第一个顶级成员名称,整数值,通用定义如下: {"ReturnValue":0,...}: 没有结果或零处理 {"ReturnValue":1,...}: 大于零,结果数或处理记录数,为成功的标识 {"ReturnValue":-1,...}: 唯一性字段值重复,操作失败 {"ReturnValue":-2,...}: 记录不存在,操作失败 {"ReturnValue":-3,...}: 未提供必须的请求参数,操作失败 {"ReturnValue":-4,...}: 请求不支持,版本错误或请求未实现 {"ReturnValue":-7,...}: 安全校验失败,不是配置的IP或数字签名错误 {"ReturnValue":-8,...}: 未获授权 {"ReturnValue":-9,...}: EmsData.dll程序错误,通常为数据库查询失败 {"ReturnValue":-9999,...}: 数据库忙,稍后再试! {"ReturnValue":-710,...}: icID 错误,未提供或小于1 {"ReturnValue":-711,...}: icID 错误,客户不存在 {"ReturnValue":-720,...}: TimeStamp 错误,超出了同步阈值 {"ReturnValue":-730,...}: MD5 错误,长度不是32字符 {"ReturnValue":-731,...}: MD5 错误,不匹配 {"ReturnValue":-810,...}: cEmsKind错误,不支持 {"ReturnValue":-820,...}: iSP_Type错误,接口不支持 {"ReturnValue":-821,...}: iSP_Type错误,相关接口未初始化 *负数值均为失败,更多的含义在具体的请求中定义。 2.3、记录字段命名采用类匈牙利命名法,第一个符号小写,为字段数据类型,名称实词首字母大写 n:单字节正整数,取值0-255,常为枚举值。如:nItemType(快件类型) d:日期,实际为一固定格式字符串,格式为:“YYYY-MM-DD hh:mm:ss”,年月日为必须。如:dDate(业务日期) i:4字节整数,取值+-2^31。如:iItem(件数) f:双精度数,精确小数位数因字段而异。如:fWeight(重量,3位小数) b:逻辑值,true/false。如:bSmsSend(是否发派件短信) c:字符串,合法的长度区间,长度按ANSI字节计算。如:cRName(收件人姓名,1-62字节) 三、各请求详解及例子 3.1、sEPostPdf 3.1.1、请求: API: /cgi-bin/EmsData.dll?DoApi POST_DATA: {"RequestName":"sEPostPdf","icID":79,"TimeStamp":1405534421123,"MD5":"6c08ea4dff56d5a7a959c09f121c3c4f","cqNo":"LN562467349CN","iSP_Type":0} iSP_Type:接口类型,默认0。(0:EUB;1:澳邮交接) cEmsKind:快递类别,0-15字符,如果未提供iSP_Type(大于1时),可提供cEmsKind *iSP_Type 和 cEmsKind 提供一个即可,用于多渠道识别。 cqNo:运单号,7-30字符,必须。转单号。 3.1.2、响应: 失败:{"ReturnValue":-10} 成功:pdf文件数据 3.1.2.1、字段名解释 ReturnValue:失败时的错误代码: -3:未提供“cqNo”或不是eub的单号 -10:未准备好数据,稍后再试。eub的pdf数据通常在转单号数据提交后10秒左右准备好 cqNo:从eub获取的单号 3.2、TimeStamp 3.2.1、请求: API: /cgi-bin/EmsData.dll?DoApi POST_DATA: {"RequestName":"TimeStamp"} 3.2.2、响应: {"ReturnValue":1409591437000} 3.2.2.1、字段名解释 ReturnValue:服务器时间戳,1970.1.1 0:0:0 到此刻的毫秒值(UTC),可用于时间戳错误(-720)校验 3.3.1、sEPostUpload 3.3.1、请求: a.非ASCII编码为UTF-8 {"RequestName":"sEPostUpload","icID":79,"TimeStamp":1416458014000,"MD5":"ddcf481543088e8d22c4a52a3e92bc53","iSP_Type":0,"cNum":"EE1020472289","cEmsKind":"SKYNET","cDes":"美国","fWeight":1.000,"cReceiver":"bbERRe3266","cRAddr":"LOS ANGELES COUNTY\x0D\x0AALHAMBRA , CA 91801 , USA","cRCity":"ALHAMBRA","cRProvince":"CA","cRCountry":"UNITED STATES OF AMERICA","cRPostcode":"91801","cRPhone":"1394333344121","cRSms":"","cGoods":"玉米","cGoodsA":"MAIZE","iQuantity":1,"fPrice":11.00} b.或者对于非ASCII进行转义编码: {"RequestName":"sEPostUpload","icID":79,"TimeStamp":1416505667000,"MD5":"f2ceda7fe738181941994c7ab2a4dfa3","cNum":"EE55520472289","cEmsKind":"SKYNET","cDes":"\u7F8E\u56FD","fWeight":1.000,"cReceiver":"bbERRe3266","cRAddr":"LOS ANGELES COUNTY\x0D\x0AALHAMBRA , CA 91801 , USA","cRCity":"ALHAMBRA","cRProvince":"CA","cRCountry":"UNITED STATES OF AMERICA","cRPostcode":"91801","cRPhone":"1394333344121","cRSms":"","cGoods":"\u7389\u7C73","cGoodsA":"MAIZE","iQuantity":1,"fPrice":11.00} 3.3.1.1、字段名解释 icID:客户ID,客户唯一识别。 #如下为记录对象的成员,依据网络渠道,提供相应的字段 iSP_Type:接口类型,默认0。(0:EUB;1:澳邮交接) cNum:运单号,7-30字符,必须。内单号或客户订单号 cEmsKind:网络渠道,1-15字符,必须。 fWeight:重量,公斤,3位小数。 iLong:长,厘米。不必须 iWidth:宽,厘米。不必须 iHeight:高,厘米。不必须 nItemType:快件类型,默认为1。取值为:0(文件),1(包裹),2(防水袋) iItem:件数,默认1。 nPayWay:付款方式,默认为0。取值为:0(月结),1(现付),2(到付) fAmount:快递费,2位小数。 cReceiver:收件人,1-63字符。 cRUnit:收件单位,0-254字符。不必须 cRAddr:收件地址,1-254字符。 cRCity:收件城市,1-126字符。 cRPostcode:收件邮编,4-15字符。 cRProvince:收件省州,2-63字符。 cRCountry:收件国家,4-126字符。 cRPhone:收件电话,4-63字符。 cREMail:收件电邮,0-63字符。不必须 cRSms:收件移动电话,4-22字符。 cGoods:物品描述,中文,2-254字符。不短于两个汉字 cGoodsA:物品别名,为英文描述,1-254字符。 iQuantity:物品数量,默认0 fPrice:物品单价,2位小数。 cTransNote:托运备注,0-63字符。不必须 cPrintCode:打印控制编码,0-15字符。不必须(00-a4;01-4*4;03:4*6) cMark:标签,0-15字符。 cReserve:留用串,0-30字符。 iReserve:留用数,默认0 cBy1:备用1,0-63字符。 cBy2:备用2,0-63字符。 cBy3:备用3,0-63字符。 cBy4:备用4,0-63字符。 cBy5:备用5,0-254字符。 cPacking:包装,0-15字符。 cTransNote:托运备注,0-63字符。 cMoney:货币代码,0-3字符。 fGoods:物品货值,代收货款收件人支付的货值,2位小数。 fDValue:物品声明价,2位小数。 fIValue:物品投保价,2位小数。 cOrigin:原产地国家代码,0-3字符。 cGoodsA:物品别名,通常为英文描述,0-254字符。 cGCodeA:物品甲码,通常为HS编码,0-63字符。 cGCodeB:物品乙码,通常为统一编码,0-63字符。 cGCodeC:物品丙码,通常为客户编码,0-63字符。 fGCustom:关税额,2位小数。 fGCRate:税率,4位小数。 3.3.2、响应: 成功:{"ReturnValue":1,cNum":"EE1020472289",cNo":"LN562467349CN","cMess":"","cReserve":"留用串","cBy1":"","cBy2":"","cBy3":"","cBy4":"","cBy5":"Test备5"} 失败:{"ReturnValue":-12,cNum":"EE1020472289",cNo":"","cMess":"收件国家空"} -810:网络渠道(cEmsKind)错误 3.3.2.1、字段名解释 ReturnValue:1,成功。负数,失败(-12:数据提交或检查错误,解释参见“cMess”) cNo:获取的运单号! cMess:错误信息,0-63字符。 cReserve:留用串,0-30字符。 cBy1:备用1,0-62字符。 cBy2:备用2,0-62字符。 cBy3:备用3,0-62字符。 cBy4:备用4,0-62字符。 cBy5:备用5,0-254字符。 3.4.1、sGetLabel 3.4.1、请求: {"RequestName":"sGetLabel","icID":79,"TimeStamp":1416458014000,"MD5":"ddcf481543088e8d22c4a52a3e92bc53","iNoType":1,"cModelName":"EMS10_10","aNo":["EM123456780CN","EM123456781CN"]} 3.4.1.1、字段名解释 iTable:记录查询源选择,默认0。(0:正式快递业务记录;1:预录单记录) iNoType:运单号类别,默认0。(0:内单号;1:转单号) cModelName:PDF模板名称,1-30字节,必须。 aNo:运单号数组,1-20个运单号字串,每个运单号7-30字节 ***e邮宝,澳邮标签批量生成,确认为同一帐号下记录(转单号),使用固定模板名称: 1、“EUB_A4_PDF_BATCH”:EUBA4纸张输出 2、“EUB_44_PDF_BATCH”:EUB4*4标签输出 3、“AUPX_A4_PDF_BATCH”:澳邮A4纸张输出 4、“AUPX_44_PDF_BATCH”:澳邮标签输出 如果成功,ReturnValue为1,将会在cMess中输出文件下载的URL 形如:{"ReturnValue":1,"cNess":"http://www.ems.cn/xxx/fe783ff83c354113877ffcc82daff421.pdf"} 3.4.2、响应: 1,成功:PDF文件数据,可判断PDF文件类型"Content-Type: application/pdf"或者字节大小,比如大于1000字节,或者PDF的BOM 2,失败:返回JSON,形如{"ReturnValue":0,"cNess":"没有符合条件的记录"} *判断ReturnValue,查看cNess 四、测试连接 http://127.0.0.1/cgi-bin/GInfo.dll?DoApi&{"RequestName":"TimeStamp"}