冰河系统快递子母件API_V1.0.md

快递API:常见使用场景:电商将订单打包之后，将快递信息推送到冰河系统，黑狗上门取件,黑狗完成快递配送环节

对接前请阅读对接流程文档:http://www.jianshu.com/p/e6e2627bfe8b

子母件对接流程图

78eae762-1a78-4a9b-a152-fd07c1578376.jpg

测试API URL POST http://test.higo-express.cn/express/api/v1/external/pushMultipleExternalExpress.do

正式API URL POST http://oms.higo-express.cn/express/api/v1/external/pushMultipleExternalExpress.do

API V1.0调用方式:模拟表单提交,json,userKey,userValue参数，其中 json参数为快递明细，具体字段含义参考字段要求

输入参数

   json:"快递明细",
   userKey: "授权key",
  userValue: "授权密码"

json参数参考格式

{
  "preexpressno": "",
  "expresstype": "CRD",
  "providername": "姚杨",
  "providerphone": "15011282486",
  "providercity": "",
  "provideraddress": "海淀区海淀中街16号中关村公馆C座B1层",
  "providercompany": "",
  "providerpostcode": "",
  "receivername": "howard",
  "receiverphone": "15810306658",
  "receivercity": "北京",
  "receiveraddress": "海淀区海淀中街16号中关村公馆C座B1层",
  "receiverpostcode": "",
  "receivercompany": "",
  "remarks": "鸭梨x1",
  "nameofproduct": "",
  "typeofpayments": "月结",
  "methodsofpayment": "",
  "isinsured": "",
  "worth": 2.50,
  "pieces": 1,
  "sourceno": "HG23577668225093",
  "expecteddate": "12:00-14:00",
  "expected": "2016-08-22 17:38:56",
  "type": 0,
  "packages": [
    {
      "weight": 0.542,
      "packageNO": "XYZKJEXHSOHA7-1",
      "temperaturetype": "LC"
    }
  ]
}

字段解释

字段	中文描述	类型	长度/大小限制	必填字段	示例值
expresstype	配送时效(黑狗产品)类型	String	10	是	CRD,其它可选值参考配送时效(黑狗产品)类型解释
providername	寄件人姓名	String	40	是
preexpressno	前订单单号 ,用于退货,换货	String	40		type值为2，preexpressno必填
type	0:正常订单1:上门换货2:上门退货	int	10	是	退货流程值为2
providerphone	寄件人电话	String	13	是
providercity	寄件人所在城市/始发地	String	10	是	北京
providerdistrict	寄件人所在区	String	10	是
provideraddress	寄件人详细地址	String	256	是
providerpostcode	寄件人邮编	String	16
providercompany	寄件人单位名称	String	256
receivername	收件人姓名	String	40	是
receiverphone	收件人电话	String	13	是
receivercity	收件人所在城市/目的地	String	10	是
receiverdistrict	收件人所在区	String	10	是
receiveraddress	收件人详细地址	String	256	是
receiverpostcode	收件人邮编	String	16
receivercompany	收件人单位名称	String	256
weight	重量未称重传入0.00	BigDecimal	12,4	是
volumn	体积	BigDecimal	12,4
aera	面积	BigDecimal	12,4
length	长	BigDecimal	12,4
width	宽	BigDecimal	12,4
hight	高	BigDecimal	12,4
remarks	备注	String	256
nameofproduct	品名	String	256
typeofpayments	付款方式	String	20		付款方式是从货主信息读取的
collectionpayableforcustomers	代收款金额	BigDecimal	12
methodsofpayment	代收货款方式,[现金,刷卡]	String	20		现金
recycle	是否回收卡卷	String	2		0（默认不回收）/1（回收）
isinsured	是否保价	int	2		Y/N
worth	声明价值	BigDecimal	12,2
insurancepremium	保费（1%）	BigDecimal	12,2		Worth*1%
pieces	箱数,一个订单3箱就传3,	BigDecimal	11	是	1
sourceno	来源单号,调用方系统的单号，常见的是订单号，订单号必须在冰河系统唯一，建议调用方在单号前加上公司域名前缀,类似:JD12343，来源单号用于调用方和冰河系统自己对账,排查问题	String	40	是	JD12345678
expecteddate	用户期望到达时间段,格式:10:00-12:00 也可以自定义格式	String	20		示例值：10:00-12:00
expected	用户期望到达时间,格式:yyyy-MM-dd	date			示例值：2015-10-04
billing_account_no	结算帐号，调用方可以自由选择当前快递使用的结算账号,结算账号在黑狗提供的合同上有体现	String	64	是	例如:JS000123546
barcodeList	配送柜条形码,使用条码柜的电商使用	String	256		逗号分割 1,2,3,4
carriersno	承运商类型 默认黑狗配送,此处推送英文	String	32		HIGO0000
packages	箱单(包裹号)明细，具体字段参考箱单明细字段解释	数组		是

配送时效(黑狗产品)类型解释

 CRD(1,"次日达"),
  DRD(2,"当日达"),
  JSD(3,"极速达");
                

承运商类型解释

 HIGO0000(1, "黑狗冷链"), 
  BJZJS(2, "北京宅急送"),
  RFD(3,"如风达"),
  DFRFD(4,"代发如风达");
                

箱单明细(packages)字段

字段	字段描述	类型	长度/大小限制	是否必填字段	示例
weight	重量,未称重传入0.00	double	(10,3)	是	1.23
packageNO	箱单号(包裹号),订单所属箱子的条码号,BJ15091133335617-1,黑狗子母件根据来源箱单号打印黑狗箱单号,单件可以用来源单号作为来源箱单号,冰河系统不允许箱单号重复,建议使用公司域名作为前缀	String	64	是	BJ15091233351896-1
temperaturetype	温区类型,使用字母代码表示:LC:冷藏LD:冷冻CW:常温	String	6	是	LC

API返回示例

{
  "data": {
    "waybillID": "4000009880",
    "sourceNO": "HG21617706239693",
    "externalExpressNO": "KDW000006481",
    "destStop":"朝阳RDC/翠城",
    "beginStop":"大兴RDC/黄村分站"
  },
  "list": [
    {
      "weight": 0.0,
      "packageNO": "XYZOWJM4JXU5T-1",
      "temperaturetype": "LD",
      "higoPackageNO": "4000009880BXP1",
      "items": null
    },
    {
      "weight": 0.0,
      "packageNO": "XYZOWJM4JXU5T-2",
      "temperaturetype": "LD",
      "higoPackageNO": "4000009880BXP2",
      "items": null
    },
    {
      "weight": 0.0,
      "packageNO": "XYZOWJM4JXU5T-3",
      "temperaturetype": "LD",
      "higoPackageNO": "4000009880BXP3",
      "items": null
    },
    {
      "weight": 0.0,
      "packageNO": "XYZOWJM4JXU5T-4",
      "temperaturetype": "LD",
      "higoPackageNO": "4000009880BXP4",
      "items": null
    },
    {
      "weight": 0.0,
      "packageNO": "XYZOWJM4JXU5T-5",
      "temperaturetype": "LD",
      "higoPackageNO": "4000009880BXP5",
      "items": null
    }
  ],
  "code": "success",
  "msg": "",
  "fail": false
}

返回结果字段说明

字段	中文描述
data	sourceNO:来源单号,waybillID:冰河系统生成的黑狗快递单号,收件人根据此号查询快递,externalExpressNO:冰河系统内部编号;beginStop始发站点;destStop:目的站点(打印黑狗面单用)，如果未返回对应的目的站点信息，人工干预之后，系统会主动推送目的站点给调用方，请参考API文档:https://coding.net/s/fc14b7ff-e6f2-4a76-82cb-8278129babe4
list	传入的包裹信息,以及黑狗对应的箱单号(higoPackageNO,打印黑狗面单，必须打印该条码)
code	成功,失败标志,failed/success
msg	错误说明
fail	注释

代码示例

  @Test
  public void testPushMultipleExternalExpress() throws IllegalAccessException, InvocationTargetException {
        
        String json = "{\"preexpressno\": \"\",\"expresstype\": \"CRD\",\"providername\": \"姚杨\",\"providerphone\": \"15011282486\",\"providercity\": \"\",\"provideraddress\": \"海淀区海淀中街16号中关村公馆C座B1层\",\"providercompany\": \"\",\"providerpostcode\": \"\",\"receivername\": \"howard\",\"receiverphone\": \"15810306658\",\"receivercity\": \"北京\",\"receiveraddress\": \"海淀区海淀中街16号中关村公馆C座B1层\",\"receiverpostcode\": \"\",\"receivercompany\": \"\",\"remarks\": \"鸭梨x1\",\"nameofproduct\": \"\",\"typeofpayments\": \"月结\",\"methodsofpayment\": \"\",\"isinsured\": \"\",\"worth\": 2.50,\"pieces\": 1,\"sourceno\": \"HG23577668225093\",\"expecteddate\": \"12:00-14:00\",\"expected\": \"2016-08-22 17:38:56\",\"type\": 0,\"packages\": [{\"weight\": 0.542,\"packageNO\": \"XYZKJEXHSOHA7-1\",\"temperaturetype\": \"LC\"}]}";

        String url = "http://dev.higo-express.cn/express/api/v1/external/pushMultipleExternalExpress.do";
        List<BasicNameValuePair> postParams = new ArrayList<BasicNameValuePair>();
        postParams.add(new BasicNameValuePair("json", json));
        postParams.add(new BasicNameValuePair("userKey", "xxxx"));
        postParams.add(new BasicNameValuePair("userValue", "xxx"));
        postParams.add(new BasicNameValuePair("datatime", DateUtils.formatDate2Str(new Date(), "yyyyMMhhHHmmss")));

        BingHeHttpPostRequest bingHeHttpPostRequest = new BingHeHttpPostRequest();
        bingHeHttpPostRequest.setRequestUrl(url);
        bingHeHttpPostRequest.setPostParams(postParams);
        bingHeHttpPostRequest.setContenttype(MediaType.APPLICATION_FORM_URLENCODED_VALUE);
        String re = BingHeHttpClientWrapper.sendHttpPost(bingHeHttpPostRequest);
        HigoLogUtils.debug(re);
  }

黑狗面单格式如下

dfa54461-ba2f-41a9-8262-f185a668fee7.jpg