# expressDeliveryOrder.dll 使用教程 ## 创建DLL工具实例 ### 加载DLL文件 ```gotemplate // ExpressDeliveryOrderDLL 快递订单DLL结构 type ExpressDeliveryOrderDLL struct { dll *syscall.DLL ztoOpenCreateOrder *syscall.Proc // 中通创建订单 jtOrderAddOrder *syscall.Proc // 极兔创建订单 emsAmpApiOpen *syscall.Proc // 邮政订单接入 stoOmsExpressOrderCreate *syscall.Proc // 申通订单创建 integrationOrderCreate *syscall.Proc // 整合快递订单创建 freeCString *syscall.Proc // 释放C字符串 } // 初始化ExpressDeliveryOrderDLL func InitExpressDeliveryOrderDLL() (*ExpressDeliveryOrderDLL, error) { dllPath := filepath.Join("dll", "expressDeliveryOrder.dll") if _, err := os.Stat(dllPath); os.IsNotExist(err) { return nil, fmt.Errorf("expressDeliveryOrder DLL 不存在: %s", dllPath) } if dll, err := syscall.LoadDLL(dllPath); err != nil { return nil, fmt.Errorf("加载expressDeliveryOrder DLL 失败: %s", err) } else { return &ExpressDeliveryOrderDLL{ dll: dll, ztoOpenCreateOrder: dll.MustFindProc("ZtoOpenCreateOrder"), jtOrderAddOrder: dll.MustFindProc("JtOrderAddOrder"), emsAmpApiOpen: dll.MustFindProc("EmsAmpApiOpen"), stoOmsExpressOrderCreate: dll.MustFindProc("StoOmsExpressOrderCreate"), integrationOrderCreate: dll.MustFindProc("IntegrationOrderCreate"), freeCString: dll.MustFindProc("FreeCString"), }, nil } } dll, err := InitExpressDeliveryOrderDLL() ``` ### 获取C字符串 ```gotemplate // cStr 获取C字符串 func (m *ExpressDeliveryOrderDLL) cStr(p uintptr) string { if p == 0 { return "" } b := []byte{} for i := uintptr(0); ; i++ { c := *(*byte)(unsafe.Pointer(p + i)) if c == 0 { break } b = append(b, c) } s := string(b) if m.freeCString != nil { m.freeCString.Call(p) } return s } ``` ### 使用DLL函数示例 ```gotemplate // 调用中通创建订单接口 func (m *ExpressDeliveryOrderDLL) ZtoOpenCreateOrder(requestJSON, appKey, appSecret string) (string, error) { proc, err := m.dll.FindProc("ZtoOpenCreateOrder") if err != nil { return "", fmt.Errorf("找不到函数 ZtoOpenCreateOrder: %v", err) } requestJSONPtr, _ := syscall.BytePtrFromString(requestJSON) appKeyPtr, _ := syscall.BytePtrFromString(appKey) appSecretPtr, _ := syscall.BytePtrFromString(appSecret) resultPtr, _, _ := proc.Call( uintptr(unsafe.Pointer(requestJSONPtr)), uintptr(unsafe.Pointer(appKeyPtr)), uintptr(unsafe.Pointer(appSecretPtr)), ) result := m.cStr(resultPtr) return result, nil } ``` # 接口详情 ## 中通快递创建订单接口--ZtoOpenCreateOrder ### 请求信息 ```gotemplate dll.ZtoOpenCreateOrder(requestJSON, appKey, appSecret) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|--------------| | requestJSON | string | 是 | 创建订单参数JSON字符串 | | appKey | string | 是 | 中通APIkey | | appSecret | string | 是 | 中通API应用密钥 | #### requestJSON json字符串 API地址： https://open.zto.com/#/interfaces?resourceGroup=20&apiName=zto.open.createOrder ```json { "partnerType": "2", "orderType": "1", "partnerOrderCode": "商家自主定义", "accountInfo": { "accountId": "test", "accountPassword": "", "type": 1, "customerId": "GPG1576724269" }, "billCode": "", "senderInfo": { "senderId": "", "senderName": "张三", "senderPhone": "010-22226789", "senderMobile": "13900000000", "senderProvince": "上海", "senderCity": "上海市", "senderDistrict": "青浦区", "senderAddress": "华志路" }, "receiveInfo": { "receiverName": "Jone Star", "receiverPhone": "021-87654321", "receiverMobile": "13500000000", "receiverProvince": "上海", "receiverCity": "上海市", "receiverDistrict": "闵行区", "receiverAddress": "申贵路1500号" }, "orderVasList": [ { "vasType": "COD", "vasAmount": 100000, "vasPrice": 0, "vasDetail": "", "accountNo": "" } ], "hallCode": "S2044", "siteCode": "02100", "siteName": "上海", "summaryInfo": { "size": "", "quantity": 3, "price": "30", "freight": "20", "premium": "10", "startTime": "2020-12-10 12:00:00", "endTime": "2020-12-10 12:00:00" }, "remark": "小吉下单", "orderItems": [ { "name": "", "category": "", "material": "", "size": "", "weight": 0, "unitprice": 0, "quantity": 0, "remark": "" } ], "cabinet": { "address": "", "specification": 0, "code": "" } } ``` ### 响应数据 ```json {"result":{"bigMarkInfo":{"bagAddr":"合肥","mark":"460- 38"},"siteCode":"02100","siteName":"上海","signBillInfo":{},"orderCode":"12123412434","billCode":"130005102254","partnerOrderCode":"43423424"},"message":"请求成功","status":true,"statusCode":"SYS000"} ``` ### 异常示例 ```json {"result":null,"message":"电子面单账号或者集团客户编码不能为空","status":false,"statusCode":"DEF001"} ``` ## 极兔快递创建订单接口--JtOrderAddOrder ### 请求信息 ```gotemplate dll.JtOrderAddOrder(requestJSON, apiAccount, privateKey) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|--------------| | requestJSON | string | 是 | 创建订单参数JSON字符串 | | apiAccount | string | 是 | 极兔API账户标识 | | privateKey | string | 是 | 极兔API私钥 | #### requestJSON JSON字符串 API地址： https://open.bxexpress.com.cn/#/apiDoc/orderserve/create ```json { "customerCode": "J0086474299", "digest": "Base64(Md5(客户编号+密文+privateKey))", "network": "合作网点编码", "txlogisticId": "客户订单号", "expressType": "EZ", "orderType": "2", "serviceType": "01", "deliveryType": "03", "payType": "PP_PM", "sender": { "name": "寄件人姓名", "company": "寄件公司", "postCode": "寄件邮编", "mailBox": "寄件邮箱", "mobile": "寄件手机", "phone": "寄件电话", "countryCode": "CHN", "prov": "寄件省份", "city": "寄件城市", "area": "寄件区域", "town": "寄件乡镇", "street": "寄件街道", "address": "寄件详细地址" }, "receiver": { "name": "收件人姓名", "company": "收件公司", "postCode": "收件邮编", "mailBox": "收件邮箱", "mobile": "收件手机", "phone": "收件电话", "countryCode": "CHN", "prov": "收件省份", "city": "收件城市", "area": "收件区域", "town": "收件乡镇", "street": "收件街道", "address": "收件详细地址" }, "sendStartTime": "yyyy-MM-dd HH:mm:ss", "sendEndTime": "yyyy-MM-dd HH:mm:ss", "goodsType": "bm000001", "isRealName": true, "isCustomsDeclaration": false, "length": 10, "width": 10, "height": 10, "weight": "0.02", "totalQuantity": 1, "itemsValue": "100.00", "priceCurrency": "RMB", "offerFee": "100.00", "remark": "备注信息", "items": [ { "itemType": "bm000001", "itemName": "物品名称", "chineseName": "物品中文名称", "englishName": "English Name", "number": 1, "itemValue": "100.00", "priceCurrency": "RMB", "desc": "物品描述", "itemUrl": "https://example.com/item" } ], "customsInfo": { "count": 1, "unit": "个", "sourceArea": "CHN", "productRecordNo": "产品国检备案编号", "goodPrepardNo": "商品海关备案号", "taxNo": "商品行邮税号", "hsCode": "海关编码", "goodsCode": "商品编号", "brand": "货物品牌", "specifications": "规格型号", "manufacturer": "生产厂家", "cargoDeclaredValue": 100.00000, "declaredValueDeclaredCurrency": "RMB", "customerFreight": "50.00", "iePort": "口岸代码", "enterpriseCustomsCode": "海关注册编号" }, "postSiteCode": "驿站编码", "postSiteName": "驿站名称", "postSiteAddress": "驿站地址", "pickupExpressCodeCheckWay": 0, "pickUpCode": "取件码", "extendInfo": { "isFourLevelAddress": "1" } } ``` ### 响应参数 ```json { "code":"1", "msg":"success", "data":{ "txlogisticId":"TEST20220704210006", "billCode":"UT0000498364212", "sortingCode":"382 300-64 010", "sumFreight":"5.00", "createOrderTime":"2022-07-04 12:00:53", "lastCenterName":"华东转运中心B1" } } ``` ## 邮政快递订单接入接口--EmsAmpApiOpen ### 请求信息 ```gotemplate dll.EmsAmpApiOpen(requestJSON, secretKey) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|--------------| | requestJSON | string | 是 | 创建订单参数JSON字符串 | | secretKey | string | 是 | 邮政API密钥 | #### requestJSON JSON字符串 API地址：https://api.ems.com.cn/#/gnapijj 需要下载API文档，里面的 订单接入 接口 ```json [ { "ecommerceUserId": "12313165", "deliveryPasswordFlag": "1", "deliveryPassword": "", "logisticsOrderNo": "12384565600", "batchNo": "", "waybillNo": "", "oneBillFlag": "", "submailNo": "", "oneBillNum": "", "oneBillFeeType": "", "contentsAttribute": "1", "bizProductNo": "1", "bizProductId": "", "teanIncrementFlag": "", "weight": 0, "volume": 0, "length": 0, "width": 0, "height": 0, "postageTotal": 12, "remarks": "", "insuranceFlag": "", "insuranceAmount": "0", "deliverType": "1", "deliverPreDate": "", "paymentMode": "", "codFlag": "", "codAmount": "0", "valuableFlag": "1", "receiverAgentIdType": "1", "receiverIdNo": "", "projectId": "", "reservationReturnFlag": "1", "reservationReturnTime": "1", "returnRelationNo": "", "receiptFlag": "", "receiptWaybillNo": "", "localCollectionFee": "1", "sender": { "name": "张三", "postCode": "", "phone": "", "mobile": "15232805086", "prov": "北京市", "city": "北京市", "county": "西城区", "address": "永安路174号" }, "receiver": { "name": "张三", "postCode": "", "phone": "", "mobile": "15232805086", "prov": "北京市", "city": "北京市", "county": "西城区", "address": "永安路174号" }, "cargos": [ { "cargoName": "测试商品", "cargoCategory": "", "cargoQuantity": "1", "cargoValue": "1", "cargoWeight": "1" } ] } ] ``` ### 响应参数 ```json { "logisticsOrderNo": "客户内部订单号", "waybillNo": "物流运单号1,物流运单号2", "routeCode": "四段码/分拣码", "packageCode": "集包地编码", "packageCodeName": "集包地名称", "markDestinationCode": "大头笔编码", "markDestinationName": "大头笔" } ``` ## 申通快递订单创建接口--StoOmsExpressOrderCreate ### 请求信息 ```gotemplate dll.StoOmsExpressOrderCreate(requestJSON, fromAppkey, secretKey, fromCode) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|-------------| | requestJSON | string | 是 | 创建订单参数JSON字符串 | | fromAppkey | string | 是 | 请求发起方应用密钥 | | secretKey | string | 是 | 签名密钥 | | fromCode | string | 是 | 请求发起方应用资源编码| #### requestJSON JSON字符串 API地址：https://open.sto.cn/#/apiDocument ```json { "orderNo": "8885452262", "orderSource": "****", "billType": "00", "orderType": "01", "sender": { "name": "测试名称", "tel": "0558-45778586", "mobile": "18775487548", "postCode": "100001", "country": "中国", "province": "安徽", "city": "合肥", "area": "泸州", "town": "测试镇", "address": "XX街道XX小区XX楼888" }, "receiver": { "name": "测试名称", "tel": "0556-45778586", "mobile": "15575487548", "postCode": "100001", "country": "中国", "province": "河北", "city": "湖州", "area": "江汉", "town": "收件镇", "address": "XX街道XX小区XX楼666", "safeNo": "13466666632-0011" }, "cargo": { "battery": "10", "goodsType": "大件", "goodsName": "XX物", "goodsCount": 10, "spaceX": 10, "spaceY": 10, "spaceZ": 10, "weight": 10, "goodsAmount": "100", "cargoItemList": [ { "serialNumber": "8451234", "referenceNumber": "88838783634", "productId": "001", "name": "小商品", "qty": 10, "unitPrice": 1, "amount": 10, "currency": "美元", "weight": 10, "remark": "无" } ] }, "customer": { "siteCode": "666666", "customerName": "666666000001", "sitePwd": "***", "monthCustomerCode": "9000000" }, "internationalAnnex": { "internationalProductType": "01", "customsDeclaration": false, "senderCountry": "中国", "receiverCountry": "俄罗斯" }, "waybillNo": "59635456632", "assignAnnex": { "takeCompanyCode": "862456565466", "takeUserCode": "9000000007" }, "codValue": "2000", "freightCollectValue": "20", "timelessType": "01", "productType": "01", "serviceTypeList": [ "***" ], "extendFieldMap": { "mapValue": "***" }, "remark": "无备注", "expressDirection": "01", "createChannel": "01", "regionType": "01", "insuredAnnex": { "insuredValue": "6.66", "goodsValue": "6.66" }, "expectValue": "10", "payModel": "1" } ``` ### 响应数据 ```json { "success": true, "errorCode": "PARAM_INVALID/QUERY_ROOKIE_EXCEPTION/AddOrderFailed/SendMobileError/SendPhoneError/SERVER_EXCEPTION/TIME_OUT/PrintCodeRepeat", "errorMsg": "waybillNo invalid:运单号不符合申通单号规则；ROUTING_INFO_QUERY_NO_REACHABLE: 物流服务不支持派送；该账号剩余面单库存不足，请联系合作网点充值；", "data": { "orderNo": "88875485332", "waybillNo": "47893154", "bigWord": "877-342-213", "packagePlace": "上海青浦测试集包地", "sourceOrderId": "88875485332", "safeNo": "95013740109424", "newBlockCode": "新四段码" } } ``` ## 韵达快递--电子面单下单接口--YdCreateBmOrder ### 请求信息 ```gotemplate dll.YdCreateBmOrder(requestJSON, appKey, appSecret) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|-------------| | requestJSON | string | 是 | 创建订单参数JSON字符串 | | appKey | string | 是 | 请求发起方应用密钥 | | appSecret | string | 是 | 签名密钥 | #### requestJSON JSON字符串 API地址：https://open.yundaex.com/api/apiDoc?apiCode=apiauth_doc 电子面单下单接口 ```json { "appid": "999999", "partner_id": "201700101001", "secret": "123456789", "orders": [ { "collection_value": 126.5, "cus_area1": "", "cus_area2": "", "isProtectPrivacy": "", "items": [ { "name": "衣服", "number": 1, "remark": "袜子" } ], "khddh": 2012121715001, "node_id": "350", "order_serial_no": 2012121715001, "order_type": "common", "platform_source": "", "receiver": { "address": "上海市，青浦区，盈港东路 6679 号", "city": "上海市", "company": "", "county": "青浦区", "mobile": "17601206977", "name": "李四", "province": "上海市" }, "remark": "", "sender": { "address": "上海市，青浦区，盈港东路 7766 号", "city": "上海市", "company": "", "county": "青浦区", "mobile": "17601206977", "name": "张三", "province": "上海市" }, "size": "0.12,0.23,0.11", "special": 0, "value": 126.5, "weight": 0, "multi_pack": { "mulpck": "", "total": 0, "endmark": 0 }, "markingInfos": [ { "type": "INSURED", "markingValue": { "value": 2100 } }, { "type": "DF", "markingValue": { "value": 15 } }, { "type": "COD", "markingValue": { "value": 15 } }, { "type": "RETURN", "markingValue": { "value": "1,2" } }, { "type": "YXZ" }, { "type": "MUL", "markingValue": { "value": 10 } }, { "type": "CONTACT" } ] } ] } ``` ### 响应参数 ```json { "code": "0000", "message": "请求成功", "result": true, "data":[{ "order_serial_no": "0000019876576897", "pdf_info": "[[{"order_id":"5160533654","order_serial_no":"test_191021002","partner_id":"2017001068","partner_orderid":"test_191021002","order_type":"common","mailno":"4060005469862","customer_id":"","sender_name":"\u738b\u5c0f\u864e","sender_company":"\u51ef\u5229","sender_area_ids":"","sender_area_names":"\u6c5f\u82cf\u7701\uff0c\u5f90\u5dde\u5e02\uff0c\u65b0\u6c82\u5e02","sender_address":"\u6e56\u4e1c\u8def999\u53f7","sender_postcode":"221435","sender_phone":"021-85926525","sender_mobile":"13761960078","sender_branch":"201700","receiver_name":"\u9646\u5927\u6709","receiver_company":"\u5343\u5343","receiver_area_ids":"310118","receiver_area_names":"\u4e0a\u6d77\u5e02,\u4e0a\u6d77\u5e02,\u9752\u6d66\u533a","receiver_address":"\u4e0a\u6d77\u5e02\u9752\u6d66\u533a\u76c8\u6e2f\u4e1c\u8def6633\u53f7","receiver_postcode":"201700","receiver_phone":"020-57720341","receiver_mobile":"13761960075","receiver_branch":"200230","weight":"11.00","remark":"","status":"rs10","time":"2019-10-21 11:16:26","position_no":"G096-00 20","position_zz":"0","options":"","send_num":"0","nb_ckh":"2001123","cus_area1":"\u8ba2\u5355\u53f7:test_191021002\n\u8ba2\u5355\u53f7\uff1a123 \n\u6279\u6b21\u53f7\uff1a456212","cus_area2":"","position":"300","receiver_flag":"1","package_wd":"J200000","callback_id":"","wave_no":"","node_id":"","ems_flag":"","cus_area3":"","trade_code":"","shi1":null,"sheng1":null,"shi2":"310100","sheng2":"310000","collection_value":"100.00","value":"20.00","zffs":"0","innerProvinceName":"\u7701\u5185\u4ef6","package_wdjc":"\u96c6\u5305\u5730\uff1a\u4e0a\u6d77\u5206\u62e8\u5305 ","sender_branch_jc":"\u9752\u6d66\u533aYD","bigpen_code":"G096-00","lattice_mouth_no":"20","mailno_barcode":"406000546986204240","tname":"mailtmp_s12","dispatch_code":"20","qrcode":"4060005469862\/300 G096-00 20","privacy_receiver_name":"\u9646**","privacy_receiver_phone":"020-****0341","privacy_receiver_mobile":"137****0075"},["0424",0]]]", "mail_no": "5300010219368", "status": "1", "remark": null, "msg": "订单创建成功", "orderId":"9876576897" }] } ``` ### 错误响应参数 ```json { "result": false, "code": "7777", "message": "内部接口服务失败", "sub_code":"s10", "sub_msg": "参数校验不合法" } ``` ## 韵达快递--电子面单打印接口--YdBmGetPdfInfo ### 请求信息 ```gotemplate dll.YdBmGetPdfInfo(requestJSON, appKey, appSecret) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|-------------| | requestJSON | string | 是 | 创建订单参数JSON字符串 | | appKey | string | 是 | 请求发起方应用密钥 | | appSecret | string | 是 | 签名密钥 | #### requestJSON JSON字符串 API地址：https://open.yundaex.com/api/apiDoc?apiCode=apiauth_doc 电子面单打印接口 ```json { "appid": "999999", "partner_id": "201700101001", "secret": "123456789", "orders": [ { "mailno": "312356465656666" } ] } ``` ### 响应参数 ```json { "code": "0000", "data": [ { "mailno": "312356465656666", "pdfInfo": "base64info" } ], "message": "请求成功", "result": true, "sub_code": null, "sub_msg": null } ``` ## 整合快递订单创建接口--IntegrationOrderCreate ### 请求信息 ```gotemplate dll.StoOmsExpressOrderCreate(requestJSON, fromAppkey, secretKey, fromCode) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |-------------|--|--|---------------------------------------------------------------------| | orderType | string | 是 | 快递类型（ZTO 中通/JT 极兔/EMS 邮政/STO 申通） | | requestJSON | string | 是 | 创建订单参数JSON字符串 | | key | string | 是 | key 对应ZTO中appKey,JT中apiAccount,STO中fromAppkey，EMS类型的时候可以不填，其他类型必填 | | secret | string | 是 | 签名密钥 对应ZTO中appSecret,JT中privateKey,EMS中secretKey,STO中secretKey | | fromCode | string | 是 | 请求发起方应用资源编码,快递类型：EMS类型时必填 | ### 请求参数 ```text 可以看上面（ZTO 中通/JT 极兔/EMS 邮政/STO 申通） 的订单接口请求参数 ``` ### 响应参数 ```text 可以看上面（ZTO 中通/JT 极兔/EMS 邮政/STO 申通） 的订单接口响应参数 ``` ## 释放C字符串内存--FreeCString ### 请求信息 ```gotemplate dll.FreeCString(str) ``` ### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--|--|--|----------| | str | string | 是 | 需要释放的字符串 |