C#实现打印丰密面单 顺丰电子面单打印
目录
1.完成前期准备工作
2.API接口
3.请求参数(Headers)
4.请求参数(Body)
5.返回参数(Return)
6.请求完整报文(示例)
7.成功返回报文(示例)
8.失败返回报文(示例)
9.分步讲解(C#版本)
10.关于签名
前言
丰密面单,就是隐藏了用户个人信息的顺丰快递面单。该面单可将寄、收件人名字、手机、地址等部分信息隐藏,让个人信息不再直接暴露。
我们先看2张面单效果图。
图一
图一是一张二联150MM的电子面单模板,寄件人和收件人手机是可见的。
图二
图二也是一张二联150MM的电子面单模板,寄件人和收件人手机是标星不看见的。这样的面单安全可靠,主要是保护客户隐私,强烈推荐客户使用,下面我们就来讲解实现过程。
1.完成前期准备工作
1.1,去快递鸟免费注册一个对接账号
1.4,订购一个免费套餐
1.5,申请顺丰速运月结账号
顺丰月结账号需要线下与当地顺丰分部签订收派合同,签定后顺丰会提供10位数字的顺丰月结账号,用于发货结算运费;
注:快递鸟官网后台显示的信息和状态(如:“我的物流服务商”页面不显示顺丰或顺丰月结账号)并不影响接口的使用,也不需要在后台添加要使用的客户号,直接通过接口传值下单即可;
1.6,准备打印机、打印纸
打印机:
电子面单模板对打印机品牌、型号等没有要求,只要是热敏打印机即可,常见品牌如:斑马、得力、快麦、汉印、佳博等。
打印机可由快递网点提供或者在淘宝京东上购买,安装打印机及驱动程序联系打印机提供方;
打印纸:
顺丰速运使用的打印纸有100mm*150mm(切点90/60)、100mm*180mm(切点110/70)、100mm*210mm(切点90/60/60)三种,
打印纸可由快递网点提供或者在淘宝京东上购买,购买时可选择全白热敏 纸。
2.API接口
2.1,测试调用地址:http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json
2.2,正式调用地址:http://api.kdniao.com/api/EOrderService
2.3,请求方式:POST
2.4,编码格式(utf-8):application/x-www-form-urlencoded;charset=utf-8
2.5,返回类型:JSON
2.6,调试页面:http://kdniao.com/UserCenter/v2/SandBox/TrackQuery.aspx
2.7,调试工具:去调试(使用快递鸟账号登录)
3.请求参数(Headers)
参数名称 | 类型 | 说明 | 必须要求 |
RequestData | String | 请求内容需进行URL(utf-8)编码,请求内容JSON格式,须和DataType一致 | 必填 |
EBusinessID | String | 用户ID,查看用户ID和ApiKey | 必填 |
RequestType | String | 请求指令类型:1007 | 必填 |
DataSign | String | 签名数据,(Body+ApiKey)进行MD5加密,再进行Base64编码,最后进行URL(utf-8)编码 | 必填 |
DataType | String | 求、返回数据类型:2-json ,默认Json | 选填 |
4.请求参数(Body)
参数名称 | 类型 | 说明 | 是否必须 | |
---|---|---|---|---|
MemberID | String(50) | ERP系统、电商平台等系统或平台类型用户的会员ID或店铺账号等唯一性标识,用于区分其用户 | O | |
CustomerName | String(50) | 电子面单客户号,需要下载《快递鸟电子面单客户号参数对照表.xlsx》,参考对应字段传值 | O | |
CustomerPwd | String(30) | O | ||
SendSite | String(30) | O | ||
SendStaff | String(30) | C | ||
MonthCode | String | C | ||
CustomArea | String(500) | 商家自定义区域 | C | |
WareHouseID | String(30) | 发货仓编码 | O | |
TransType | Int(1) | 运输方式 1- 陆运 2- 空运 不填默认为1 | O | |
ShipperCode | String(10) | 快递公司编码 详细编码参考《快递鸟接口支持快递公司编码.xlsx》 | R | |
LogisticCode | String(30) | 快递单号(仅宅急送可用) | O | |
ThrOrderCode | String(50) | 第三方订单号 (ShipperCode为JD且ExpType为1时必填) | C | |
OrderCode | String(30) | 订单编号(自定义,不可重复) | R | |
PayType | Int(1) | 邮费支付方式:1-现付,2-到付,3-月结,4-第三方支付(仅SF支持) | R | |
ExpType | String(2) | 快递类型:1-标准快件 ,详细快递类型参考《快递公司快递业务类型.xlsx》 | R | |
IsReturnSignBill | Int(1) | 是否要求签回单 1- 要求 0-不要求 | O | |
OperateRequire | String(20) | 签回单操作要求(如:签名、盖章、身份证复印件等) | O | |
Cost | Cost Double(5) | 快递运费 | O | |
OtherCost | Double(5) | 其他费用 | O | |
Receiver | Company | String(30) | 收件人公司 | O |
Name | String(30) | 收件人 | R | |
Tel | String(20) | 电话与手机,必填一个 | R | |
Mobile | String(20) | |||
PostCode | String(10) | 收件人邮编 | c | |
ProvinceName | String(20) | 收件省 (如广东省,不要缺少“省”;如是直辖市,请直接传北京、上海等; 如是自治区,请直接传广西壮族自治区等) | R | |
CityName | String(20) | 收件市(如深圳市,不要缺少“市”; 如果是市辖区,请直接传北京市、上海市等) | R | |
ExpAreaName | String(20) | 收件区/县(如福田区,不要缺少“区”或“县”) | R | |
Address | String(100) | 收件人详细地址 | R | |
Sender | Company | String(30) | 发件人公司 | O |
Name | String(30) | 发件人 | R | |
Tel | String(20) | 电话与手机,必填一个 | R | |
Mobile | String(20) | |||
PostCode | String(10) | 发件地邮编(ShipperCode为EMS、YZPY、YZBK时必填) | C | |
ProvinceName | String(20) | 发件省 (如广东省,不要缺少“省”; 如是直辖市,请直接传北京、上海等; 如是自治区,请直接传广西壮族自治区等) | R | |
CityName | String(20) | 发件市(如深圳市,不要缺少“市; 如是市辖区,请直接传北京市、上海市等”) | R | |
ExpAreaName | String(20) | 发件区/县(如福田区,不要缺少“区”或“县”) | R | |
Address | String(100) | 发件人详细地址 | R | |
IsNotice | Int(1) | 是否通知快递员上门揽件 0- 通知 1- 不通知 不填则默认为1 | O | |
StartDate | Date | 上门取货时间段:"yyyy-MM-dd HH:mm:ss"格式化,本文中所有时间格式相同 | O | |
EndDate | Date | O | ||
Weight | Double(10,3) | 包裹总重量kg 当为快运的订单时必填,不填时快递鸟将根据各个快运公司要求传对应的默认值 | C | |
Quantity | Int(2) | 包裹数(最多支持30件) 一个包裹对应一个运单号,如果是大于1个包裹,返回则按照子母件的方式返回母运单号和子运单号 | R | |
Volume | Double(20,3) | 包裹总体积m3 当为快运的订单时必填,不填时快递鸟将根据各个快运公司要求传对应的默认值 | C | |
Remark | String(60) | 备注 | O | |
AddServices | ||||
AddService | Name | String(20) | 增值服务名称 (数组形式,可以有多个增值服务) | C |
Value | String(30) | 增值服务值 | C | |
CustomerID | String(30) | 客户标识(选填) | O | |
Commoditys | ||||
Commodity | GoodsName | String(100) | 商品名称 | R |
GoodsCode | String(100) | 商品编码 | O | |
Goodsquantity | Int(5) | 商品数量 | O | |
GoodsPrice | Double(10) | 商品价格 | O | |
GoodsWeight | Double(10,3) | 商品重量kg | O | |
GoodsDesc | String(50) | 商品描述 | O | |
GoodsVol | Double(15,3) | 商品体积m3 | O | |
IsReturnPrintTemplate | String(1) | 返回电子面单模板:0-不需要;1-需要 | O | |
IsSendMessage | Int(1) | 是否订阅短信:0-不需要;1-需要 | O | |
TemplateSize | String(10) | 模板规格(默认的模板无需传值,非默认模板传对应模板尺寸) 二联150丰密面单(TemplateSize传值15001) 三联210丰密面单(TemplateSize传值21001) 二联150(默认模板,TemplateSize传值为空) 三联210(TemplateSize传值210) 二联180新(TemplateSize传值180) | O | |
PackingType | Int(2) | 包装类型(快运字段)默认为0; 0- 纸 1- 纤 2- 木 3- 托膜 4- 木托 99-其他 | C | |
DeliveryMethod | Int(1) | 送货方式(快运字段)默认为0; 0- 自提 1- 送货上门(不含上楼) 2- 送货上楼 | C |
5.返回参数(Return)
参数名称 | 类型 | 说明 | 必须要求 | |
---|---|---|---|---|
EBusinessID | String(10) | 用户ID | R | |
Order | OrderCode | String(30) | 订单编号 | R |
ShipperCode | String(10) | 快递公司编码 | R | |
LogisticCode | String(400) | 快递单号 | R | |
MarkDestination | String(20) | 大头笔 | O | |
OriginCode | String(20) | 始发地区域编码 | O | |
OriginName | String(20) | 始发地/始发网点 | O | |
DestinatioCode | String(20) | 目的地区域编码 | O | |
DestinatioName | String(20) | 目的地/到达网点 | O | |
SortingCode | String(20) | 分拣编码 | O | |
PackageCode | String(20) | 集包编码 | O | |
PackageName | String(50) | 集包地 | O | |
DestinationAllocationCentre | String(50) | 目的地分类 | O | |
Success | Bool(10) | 成功与否(true/false) | R | |
SignWaybillCode | String(15) | 签回单单号 | O | |
ResultCode | String(5) | 返回编码 | R | |
Reason | String(50) | 失败原因 | O | |
UniquerRequestNumber | String(50) | 唯一标识 | R | |
PrintTemplate | String | 面单打印模板内容(html格式) | O | |
EstimatedDeliveryTime | Date | 订单预计到货时间yyyy-mm-dd | O | |
SubCount | Int(5) | 子单数量 | O | |
SubOrders | String(400) | 子单单号 | O | |
SubPrintTemplates | String(2000) | 子单模板内容(html格式) | O | |
SignBillPrintTemplate | String(2000) | 签回单模板内容(html格式) | O | |
ReceiverSafePhone | String(20) | 收件人安全电话 | O | |
SenderSafePhone | String(20) | 收件人安全电话 | O | |
DialPage | String(50) | 拨号页面网址(转换成二维码可扫描拨号) | O |
6.请求报文(示例)
7.成功返回报文(示例)
{ "EBusinessID": "1237100", "Order": { "OrderCode": "012657700387", "ShipperCode": "HTKY", "LogisticCode": "50002498503427", "MarkDestination": "京-朝阳(京-1)", "OriginCode": "200000", "OriginName": "上海分拨中心", "PackageCode": "北京" }, "PrintTemplate": "打印模板HTML内容后面单独列出", "EstimatedDeliveryTime": "2016-03-06", "Success": true, "ResultCode": "100", "Reason": "成功" }
8.失败返回报文(示例)
{
"EBusinessID": "1237100",
"ResultCode": "106",
"Reason": "该订单号已下单成功",
"UniquerRequestNumber": "5e66486b-8fbc-4131-b875-9b13d2ad1354"
}
说明:未实名认证,未订购套餐,套餐可用查询量已经用完 都会返回此报文信息
9.分步讲解(C#版本)
9.1,请求数据包结构
9.2,C#调用代码示例
技术支持:QQ:510997342 //电商ID string eEBusinessID = "test1617571"; //电商加密私钥,快递鸟提供,注意保管,不要泄漏 string appKey= "554343b2-7252-439b-b4eb-1af42c8f2175"; //请求url string reqURL = "http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json"; //请求指令 string reqType="1007"; //2-json string dataType = "2"; //字符编码采用UTF-8 string charset = "UTF-8"; //JSON字符串string string jsonStr = "{ \"OrderCode\": \"012657018199\", \"ShipperCode\": \"SF\", \"PayType\": 1, \"MonthCode\": \"1234567890\", \"ExpType\": 1, \"Cost\": 1.0, \"OtherCost\": 1.0, \"Sender\": { \"Company\": \"LV\", \"Name\": \"Taylor\", \"Mobile\": \"15018442396\", \"ProvinceName\": \"上海\", \"CityName\": \"上海市\", \"ExpAreaName\": \"青浦区\", \"Address\": \"明珠路\" }, \"Receiver\": { \"Company\": \"GCCUI\", \"Name\": \"Yann\", \"Mobile\": \"15018442396\", \"ProvinceName\": \"北京\", \"CityName\": \"北京市\", \"ExpAreaName\": \"朝阳区\", \"Address\": \"三里屯街道\" }, \"Commodity\": [ { \"GoodsName\": \"鞋子\", \"GoodsQuantity\": 1, \"GoodsWeight\": 1.0 }, { \"GoodsName\": \"衣服\", \"GoodsQuantity\": 1, \"GoodsWeight\": 1.0 }, ], \"AddService\": [ { \"Name\": \" INSURE \", \"Value\": \"1000\" }, { \"Name\": \"COD\", \"Value\": \"1020\" \" CustomerID \": \"1234567890\" } ], \"Weight\": 1.0, \"Quantity\": 1, \"Volume\": 0.0, \"Remark\": \"小心轻放\" }" ; //把(jsonStr+APIKey)进行MD5加密 string md5Str=MD5(jsonStr + apiKey, charset); //把md5Str 进行Base64编码 string base64Str=base64(md5Str,charset); //进行URL编码 (utf-8) string datasign = HttpUtility.UrlEncode(base64Str, charset); //请求报文参数 string postStr = "RequestType=reqType&EBusinessID= eEBusinessID&RequestData=jsonStr &DataSign= datasign&DataType=dataType"; //通讯协议使用Http协议Post请求方式 返回轨迹数据 string post = SendPost(reqURL, postStr); //获取到的post数据就是快递鸟返回的完整报文,接下来自己写一个解析json的方法就能获取到里面的字段信息。
9.3,C#调用方法
///<summary> /// 字符串MD5加密 ///</summary> ///<param name="str">要加密的字符串</param> ///<param name="charset">编码方式</param> ///<returns>密文</returns> private string MD5(string str, string charset) { byte[] buffer = System.Text.Encoding.GetEncoding(charset).GetBytes(str); try { System.Security.Cryptography.MD5CryptoServiceProvider check; check = new System.Security.Cryptography.MD5CryptoServiceProvider(); byte[] somme = check.ComputeHash(buffer); string ret = ""; foreach (byte a in somme) { if (a < 16) ret += "0" + a.ToString("X"); else ret += a.ToString("X"); } return ret.ToLower(); } catch { throw; } } /// <summary> /// base64编码 /// </summary> /// <param name="str">内容</param> /// <param name="charset">编码方式</param> /// <returns></returns> private string base64(String str, String charset) { return Convert.ToBase64String(System.Text.Encoding.GetEncoding(charset).GetBytes(str)); } /// <summary> /// Post方式提交数据,返回网页的源代码 /// </summary> /// <param name="url">发送请求的 URL</param> /// <param name="postData">请求报文参数</param> /// <returns>远程资源的响应结果</returns> private string SendPost(string url, string postData) { string result = ""; byte[] byteData = Encoding.GetEncoding("UTF-8").GetBytes(postData.ToString()); try { HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url); request.ContentType = "application/x-www-form-urlencoded"; request.Referer = url; request.Accept = "*/*"; request.Timeout = 30 * 1000; request.UserAgent = "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 2.0.50727; .NET CLR 3.0.04506.648; .NET CLR 3.0.4506.2152; .NET CLR 3.5.30729)"; request.Method = "POST"; request.ContentLength = byteData.Length; Stream stream = request.GetRequestStream(); stream.Write(byteData, 0, byteData.Length); stream.Flush(); stream.Close(); HttpWebResponse response = (HttpWebResponse)request.GetResponse(); Stream backStream = response.GetResponseStream(); StreamReader sr = new StreamReader(backStream, Encoding.GetEncoding("UTF-8")); result = sr.ReadToEnd(); sr.Close(); backStream.Close(); response.Close(); request.Abort(); } catch (Exception ex) { result = ex.ToString(); } return result; }
10.关于签名
快递鸟和第三方电子商务公司系统进行对接,有一定的安全机制。采用 IP 认证加签名
的方式对接,具体方案如下:
防止数据被篡改
在 POST 请求中会传递 5 个必须(R)参数
RequestData==数据内容(URL 编码:UTF-8)
EBusinessID==用户 ID
RequestType=请求指令类型
DataSign== 数据内容签名:把(请求内容(未编码)+ApiKey)进行 MD5 加密,然后 Base64
编码,最后进行 URL(utf-8)编码
DataType==2(返回数据类型为 json)
注:
DataSign 生成后,对方接收到数据后,以同样的算法进行签名(推送接口 RequestType 为
101/102 不需要进行 URL 编码),生成摘要,对比两者的摘要是否相同,如果不同,说明传递过程中发生数据篡改。
调用接口的身份认证
注册成为快递鸟用户后,会生成对应的用户 ID 和 APIKey,用户 ID 相当于用户名,
APIKey 相当于密码。
12.注意事项
12.1 关于顺丰月结账号接口传值
MonthCode传值顺丰月结账号(PayType为1、2时不填,为3、4时必填),
PayType传值付款方式(包含:1-现付,2-到付,3-月结,4-第三方付),
客户号配置页需留两个栏位(需正确对应以上两个字段)由发货商家填写,商家自己开发的系统也建议保留配置页,万一账号更换了呢?
12.2 关于快递类型
顺丰速运快递类型如下:
快递类型 | ExpType传值 |
顺丰标快 | 1 |
顺丰特惠 | 2 |
电商特惠 | 3 |
四日件 | 4 |
顺丰次晨 | 5 |
顺丰即日 | 6 |
电商速配 | 7 |
医药常温 | 11 |
医药温控 | 12 |
物流普运 | 13 |
冷运到家 | 14 |
生鲜速配 | 15 |
大闸蟹专递 | 16 |
汽配吉运 | 17 |
重货快运 | 18 |
行邮专列 | 20 |
医药专运(常温) | 21 |
医药专运(温控) | 22 |
电商专配 | 28 |
即日2200 | 34 |
物资配送 | 35 |
汇票专送 | 36 |
证照专递产品 | 110 |
顺丰空配 | 112 |
专线普运 | 125 |
夜配 | 134 |
重货包裹 | 154 |
小票零担 | 155 |
医药常温(陆) | 195 |
医药快运 | 203 |
注:商家的顺丰月结账号是否能发对应的快递类型,请事先和顺丰速运分部人员确认,除1、2、5、6外,其他快递类型都需单独再签协议。
12.3 关于顺丰速运增值服务传值
保价
字段传值:"AddService": [{"Name":"INSURE ","Value":"1000"}]
代收货款
字段传值:"AddService":[{"Name":"COD","Value":"1000","CustomerID":"1234567891"}]
子母件
Quantity传值大于等于2表示子母件,并且会返回对应的SubCount子单数量、SubOrders子单单号、SubPrintTemplates子单html模板;
签回单
IsReturnSignBill传1表示需要签回单,并且会返回对应的SignBillPrintTemplate签回单html模板,默认为0不需要;
OperateRequire表示回单操作要求(如:签名、盖章、身份证复印件等);
预约快递员上门
IsNotice表示是否通知快递员上门揽件,0-通知,1-不通知,默认为1;
12.4 关于是否需要预约快递员上门揽件:
1、 如寄件点是全国各地不固定,需要快递员上门揽件则预约(此类情况务必对预约用户做限制,必须本人预约,通过手机验证码验证成功后方可预约,不然会造成用户恶意下单预约,导致顺丰速运投诉);
2、 如是固定几个地点发货,且每天都需要发货,可线下与快递员协商定时定点定人上门揽件,接口上不需要预约;
3、 如是固定地点发货,只是偶尔发几票,自己打印面单则随机预约其中一个订单,如需要快递员打印则全部预约(快递员是否能打印取决于顺丰速运当地网点);
注:如出现恶意预约,导致顺丰速运向快递鸟投诉超过3次的,快递鸟将停用用户此接口权限;
订阅物流节点短信通知
物流节点短信包含:寄件短信、派件短信、签收短信、问题件短信等;
字段传值:IsSendMessage 0-不需要,1-需要
短信通知是收费服务,需联系商务同事购买会员套餐或短信套餐后方可使用。
12.5, 电子面单模板样式
顺丰速运模板共5个规格,具体如下
² 二联150(默认模板,TemplateSize传值为空)
² 三联210(TemplateSize传值210)
² 二联180新(TemplateSize传值180)
² 二联150丰密面单(TemplateSize传值15001)
² 三联210丰密面单(TemplateSize传值21001)
:快递公司不支持的特殊字符:' " # & + % \ < > 请确认请求数据(包含收寄方姓名、电话、地址、商品名称等所有订单数据)中是否含有以上特殊字符;
电子面单下单接口订单号OrderCode不能重复使用,重复使用会报错且返回的面单是此订单号上次下单的内容;
默认的模板TemplateSize无需传值,非默认模板传对应模板尺寸,不可传不存在的模板尺寸代码;
下单成功后如不需要发货,直接撕掉面单即可,不需要取消(如果一定要取消可对接”电子面单取消接口”),快递员揽件后才收费,单号不收费;
不可派送表示派件地址不在顺丰速运服务范围,具体收派范围可在顺丰速运官网查看http://www.sf-express.com/cn/sc/dynamic_function/range/,可更换其他快递发货;
- 点赞
- 收藏
- 关注作者
评论(0)