#该帮助文件描述 EmsData.dll 扩展一组规范的[下家专线(100-500)]接口的方法#
#EmsData.dll内置支持的专线数字区间限定为0-99

一、总概

1.1、通讯协议遵循 HTTP (1.0/1.1) 
1.2、数据包装采用JSON,遵循RFC4627
     字符集编码：UTF-8 (65001)
     *特别提示，共有8个ASCII码采用x编码转义：
     "(双引号) = \x22
     \(反斜杠) = \x5C
     /(斜杠)   = \x2F
      (换行符) = \x0A
      (回车符) = \x0D
      (制表符) = \x09 (罕用)
      (退格符) = \x08 (极罕用)    
      (换页符) = \x0C (极罕用)
     *POST数据，遵循上述编码规则，建议不进行URL_Encode(定义URL_ENCODE=1，强制URL_ENCODE)
      
1.3、接口API为：“/xxx/xxx”
1.4、接口请求方式为：POST
1.5、安全控制，MD5数字签名,绑定客户ID、专线数字、帐号、密钥，通过与时间戳生成摘要码验证。




二、JSON命名规范

2.1、RequestName：发起请求名称，为请求方的第一个顶级成员名称，定义如下：
     {"RequestName":"DoUpload","icID":79,"ac":"theAllocAccount","iSLine":100,"TimeStamp":1405534421123,"MD5":"19ee05ca9c4eee8382fb7c34421ddc68",...}：		提交预报数据,请求转单号及标签URL等
 

2.1.2、每一个请求都必须包含成员变量：icID、ac,iSLine,TimeStamp、MD5。
2.1.2.1、icID：客户在EMMis中建档时由系统生成的唯一整数值
2.1.2.2、TimeStamp：时间戳，1970.1.1 0:0:0开始到请求时刻的毫秒数(UTC),13位整数。注意北京时间为东8区，需要调整时差。
2.1.2.3、MD5：数字签名，=MD5(icID+ac+iSLine+TimeStamp+密钥)
         *比如客户密钥为“ABCDefg”,如上例程为：MD5("79theAllocAccount10014055344211231234ABCD")="19ee05ca9c4eee8382fb7c34421ddc68"

2.2、ReturnValue：响应返回状态码，为响应方的第一个顶级成员名称，整数值，通用定义如下：
    {"ReturnValue":0,...}：	没有结果或零处理
    {"ReturnValue":1,...}：	大于零，成功
    
    {"ReturnValue":-1,...}：	唯一性字段值重复，操作失败
    {"ReturnValue":-2,...}：	记录不存在，操作失败
    {"ReturnValue":-3,...}：	未提供必须的请求参数，操作失败
    {"ReturnValue":-4,...}：	请求不支持，版本错误或请求未实现
    {"ReturnValue":-5,...}：	未解析出"RequestName"
    {"ReturnValue":-7,...}：	安全校验失败，不是配置的IP或数字签名错误
    {"ReturnValue":-8,...}：	未获授权
    {"ReturnValue":-9,...}：	系统错
    {"ReturnValue":-9999,...}：	系统忙，稍后再试！

    {"ReturnValue":-710,...}：	icID 错误，未提供或小于1
    {"ReturnValue":-711,...}：	icID 错误，客户不存在
    {"ReturnValue":-720,...}：	TimeStamp 错误，超出了同步阈值
    {"ReturnValue":-730,...}：	MD5 错误，长度不是32字符
    {"ReturnValue":-731,...}：	MD5 错误，不匹配


    *负数值均为失败，更多的含义在具体的请求中定义。

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.1、DoUpload
3.1.1、请求：
{"RequestName":"DoUpload","icID":79,"ac":"Accc123","iSLine":100,"cProductCode":"001","iFrom":1,"TimeStamp":1465672867000,"MD5":"de2d48cc850104c71c22a1589d07f792","cNum":"EP14110552775","cNo":"EP14110552775","cRNo":"IDA","cCNo":"","cEmsKind":"DHL","cDes":"美国","iReserve":0,"iItem":1,"nItemType":1,"nPayWay":0,"fAmount":87.40,"iLong":0,"iWidth":0,"iHeight":0,"fWeight":0.800,"cReceiver":"Sandra Wildman","cRAddr":"Bear Lake County","cRCity":"Bern","cRProvince":"ID","cRCountry":"United States","cRPostcode":"83220","cRPhone":"4782182977","cRSms":"","cSender":"","cSAddr":"1234 # Jingjiang Rd.o\u000D\u000AShanghai+家ffff","cSCity":"shanghai","cSProvince":"shanghai","cSCountry":"China","cSPostcode":"200001","cSPhone":"139163654444","cSSms":"18018678335","cPacking":"","cTransNote":"","cMoney":"USD","cOrigin":"CN","cMark":"","cReserve":"","cBy1":"","cBy2":"","cBy3":"","cBy4":"","cBy5":"","fGoods":0.00,"fIValue":0.00,"fDValue":51.00,"GoodsList":[{"cxGoods":"圆石子","cxGoodsA":"Shingle","cxGCodeA":"2517100003","cxGCodeB":"","cxGCodeC":"","ixQuantity":2,"fxPrice":15.00,"fxGCRate":0.0300,"fxGCustom":0.00},{"cxGoods":"硬粒小麦","cxGoodsA":"Durum wheat","cxGCodeA":"1001100001","cxGCodeB":"BBB54324243","cxGCodeC":"CC002321322","ixQuantity":1,"fxPrice":11.33,"fxGCRate":0.0500,"fxGCustom":0.00}]}

3.1.1.1、字段名解释
icID：客户ID,必须。客户唯一识别。
ac:帐号必须,
iSLine:专线数字,必须,有效值:100-500
cProductCode:产品代码,0-7字符
iFrom:来源,0(分拣系统);1:EmsData.dll

cNum：内单号,0-30字符。
cNo：转单号,0-30字符。
cRNo：参考号,0-30字符。
cCNo：报关号,0-30字符。
cEmsKind：快递类别,1-15字符，必须。
cDes：目的地,1-63字符，必须。
iReserve：留用数，默认0
iItem：件数，默认1。

nItemType：快件类型，默认为1。取值为：0(文件),1(包裹),2(防水袋)
nPayWay：付款方式，默认为0。取值为：0(月结),1(现付),2(到付)
fAmount：快递费，2位小数。
iLong：长，厘米。
iWidth：宽，厘米。
iHeight：高，厘米。
fWeight：重量，公斤，3位小数。

cReceiver：收件人,0-63字符。
cRUnit：收件单位,0-254字符。
cRAddr：收件地址,1-254字符，必须。
cRCity：收件城市,0-126字符。
cRPostcode：收件邮编,0-15字符。
cRProvince：收件省州,0-63字符。
cRCountry：收件国家,2-126字符，必须。
cRPhone：收件电话,0-63字符。
cREMail：收件电邮,0-63字符。
cRSms：收件短信,0-22字符。

cSender：发件人,0-30字符。
cSUnit：发件单位,0-127字符。
cSAddr：发件地址,0-127字符。
cSCity：发件城市,0-63字符。
cSPostcode：发件邮编,0-15字符。
cSProvince：发件省州,0-30字符。
cSCountry：发件国家,0-63字符。
cSPhone：发件电话,0-63字符。
cSEMail：发件电邮,0-63字符。
cSSms：发件短信,0-22字符。
cDepart：所属部门,0-30字符。


cMoney：货币代码，0-3字符。
fGoods：物品货值，代收货款收件人支付的货值，2位小数。
fDValue：物品声明价，2位小数。
fIValue：物品投保价，2位小数。
cOrigin：原产地国家代码，0-3字符。
cPacking：包装,0-15字符。
cTransNote：托运备注,0-63字符。

cMark：标签,0-15字符。
cReserve：留用串,0-30字符。

cBy1：备用1,0-63字符。
cBy2：备用2,0-63字符。
cBy3：备用3,0-63字符。
cBy4：备用4,0-63字符。
cBy5：备用5,0-254字符。


**GoodsList：快件所含物品列表，为1-100个物品对象
#为了区分，命名在顶层字段名称中嵌入了一个“x”,注意字段长度有所不同。
cxGoods：物品描述,0-63字符。必须。
ixQuantity：物品数量。必须。
fxPrice：物品单价，2位小数。
cxGoodsA：物品别名，通常为英文描述,0-63字符。
cxGCodeA：物品甲码，通常为HS编码,0-63字符。
cxGCodeB：物品乙码，通常为统一编码,0-63字符。
cxGCodeC：物品丙码，通常为客户编码,0-63字符。
fxGCustom：关税额，2位小数。
fxGCRate：税率，4位小数。

3.1.2、响应：
{"ReturnValue":1,"cNum":"EP14110552775","cMess":"","cNo":"EM123456789CN","cBy1":"","cBy2":"","cBy3":"","cBy4":"","cBy5":"http://xxx.yyy.zz/hhggddfdkkxxyyy.pdf"}
3.1.2.1、字段名解释
ReturnValue：大于0,成功,负数，失败
cNum：内单号，回传。
cNo：转单号,成功必有(7-30字符)
cBy1：备用1,0-63字符。
cBy2：备用2,0-63字符。
cBy3：备用3,0-63字符。
cBy4：备用4,0-63字符。
cBy5：备用5,0-254字符。成功应有(为pdf标签的下载链接URL)
cMess：错误信息,0-63字符。



2.2、反向上传pdf标签：
2.2.1、入口： /cgi-bin/EmsData.dll?DoGen
2.2.2、POST 数据包(JSON)
     {"RequestName":"UploadLabel","icID":1,"ac":"theAllocAccount","iSLine":100,"TimeStamp":1405534421123,"MD5":"19ee05ca9c4eee8382fb7c34421ddc68","cNo":"EM123456789CN","vData":"JVBERi0xLjQKJeLjz9MKMyAwIG9iaiA8PC9Db2xvclNwYWNlL0RldmljZVJHQi9TdWJ0eXBlL0ltYWdlL0hlaWdodCAyMDAvRmlsdGVyL0ZsYXRlRGVjb2RlL1R5cGUvWE9iamVjdC9XaWR0aCAyMDAvTGVuZ3RoIDI5MzkvQml0c1BlckNvbXBvbmVudCA4Pj5zdHJlYW0KeJztlzGSIDcMxO7/n7bjS+RFARTHW+qUYhPdE82fP3/pn7/1503f9E3f9E3f9E3f9E3f9E1/1/..."}

icID，ac：必须提供，系统并不进行一致性检查，但按规则做签名校验，icID如未知，建议提供固定值1
cNo:转单号
vData:BASE64_编码的_PDF_文件数据


四、测试连接
http://www.xxx.cn/xxx/xxx?DoApi&{"RequestName":"DoUpload",.....}