C#实现打印丰密面单 顺丰电子面单打印

举报
老杨占线 发表于 2020/04/18 18:40:28 2020/04/18
【摘要】 丰密面单,就是隐藏了用户个人信息的顺丰快递面单。该面单可将寄、收件人名字、手机、地址等部分信息隐藏,让个人信息不再直接暴露。

目录

1.完成前期准备工作

2.API接口

3.请求参数(Headers)

4.请求参数(Body)

5.返回参数(Return)

6.请求完整报文(示例)

7.成功返回报文(示例)

8.失败返回报文(示例)

9.分步讲解(C#版本)

10.关于签名

 

前言

丰密面单,就是隐藏了用户个人信息的顺丰快递面单。该面单可将寄、收件人名字、手机、地址等部分信息隐藏,让个人信息不再直接暴露。

我们先看2张面单效果图。

 

图一

image.png

 

 图一是一张二联150MM的电子面单模板,寄件人和收件人手机是可见的。

 

图二

image.png

 

 图二也是一张二联150MM的电子面单模板,寄件人和收件人手机是标星不看见的。这样的面单安全可靠,主要是保护客户隐私,强烈推荐客户使用,下面我们就来讲解实现过程。

 

1.完成前期准备工作

1.1,去快递鸟免费注册一个对接账号

1.2,免费获得一个apiKey(接口权限验证需要)

1.3,完成实名认证流程

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)

参数名称类型说明必须要求
RequestDataString请求内容需进行URL(utf-8)编码,请求内容JSON格式,须和DataType一致必填
EBusinessIDString用户ID,查看用户ID和ApiKey必填
RequestTypeString请求指令类型:1007必填

DataSignString签名数据,(Body+ApiKey)进行MD5加密,再进行Base64编码,最后进行URL(utf-8)编码必填
DataTypeString求、返回数据类型:2-json ,默认Json选填

 

4.请求参数(Body)

参数名称类型说明是否必须
MemberIDString(50)ERP系统、电商平台等系统或平台类型用户的会员ID或店铺账号等唯一性标识,用于区分其用户O
CustomerNameString(50)电子面单客户号,需要下载《快递鸟电子面单客户号参数对照表.xlsx》,参考对应字段传值O
CustomerPwdString(30)O
SendSiteString(30)O
SendStaffString(30)C
MonthCodeStringC
CustomAreaString(500)商家自定义区域C
WareHouseIDString(30)发货仓编码O
TransTypeInt(1)运输方式 1- 陆运 2- 空运 不填默认为1O
ShipperCodeString(10)快递公司编码 详细编码参考《快递鸟接口支持快递公司编码.xlsx》R
LogisticCodeString(30)快递单号(仅宅急送可用)O
ThrOrderCodeString(50)第三方订单号 (ShipperCode为JD且ExpType为1时必填)C
OrderCodeString(30)订单编号(自定义,不可重复)R
PayTypeInt(1)邮费支付方式:1-现付,2-到付,3-月结,4-第三方支付(仅SF支持)R
ExpTypeString(2)快递类型:1-标准快件 ,详细快递类型参考《快递公司快递业务类型.xlsx》R
IsReturnSignBillInt(1)是否要求签回单 1- 要求 0-不要求O
OperateRequireString(20)签回单操作要求(如:签名、盖章、身份证复印件等)O
CostCost Double(5)快递运费O
OtherCostDouble(5)其他费用O
ReceiverCompanyString(30)收件人公司O
NameString(30)收件人R
TelString(20)电话与手机,必填一个R
MobileString(20)
PostCodeString(10)收件人邮编c
ProvinceNameString(20)收件省 (如广东省,不要缺少“省”;如是直辖市,请直接传北京、上海等; 如是自治区,请直接传广西壮族自治区等)R
CityNameString(20)收件市(如深圳市,不要缺少“市”; 如果是市辖区,请直接传北京市、上海市等)R
ExpAreaNameString(20)收件区/县(如福田区,不要缺少“区”或“县”)R
AddressString(100)收件人详细地址R
SenderCompanyString(30)发件人公司O
NameString(30)发件人R
TelString(20)电话与手机,必填一个R
MobileString(20)
PostCodeString(10)发件地邮编(ShipperCode为EMS、YZPY、YZBK时必填)C
ProvinceNameString(20)发件省 (如广东省,不要缺少“省”; 如是直辖市,请直接传北京、上海等; 如是自治区,请直接传广西壮族自治区等)R
CityNameString(20)发件市(如深圳市,不要缺少“市; 如是市辖区,请直接传北京市、上海市等”)R
ExpAreaNameString(20)发件区/县(如福田区,不要缺少“区”或“县”)R
AddressString(100)发件人详细地址R
IsNoticeInt(1)是否通知快递员上门揽件 0- 通知 1- 不通知 不填则默认为1O
StartDateDate上门取货时间段:"yyyy-MM-dd HH:mm:ss"格式化,本文中所有时间格式相同O
EndDateDateO
WeightDouble(10,3)包裹总重量kg 当为快运的订单时必填,不填时快递鸟将根据各个快运公司要求传对应的默认值C
QuantityInt(2)包裹数(最多支持30件) 一个包裹对应一个运单号,如果是大于1个包裹,返回则按照子母件的方式返回母运单号和子运单号R
VolumeDouble(20,3)包裹总体积m3 当为快运的订单时必填,不填时快递鸟将根据各个快运公司要求传对应的默认值C
RemarkString(60)备注O
AddServices
AddServiceNameString(20)增值服务名称
(数组形式,可以有多个增值服务)
C
ValueString(30)增值服务值C
CustomerIDString(30)客户标识(选填)O
Commoditys
CommodityGoodsNameString(100)商品名称R
GoodsCodeString(100)商品编码O
GoodsquantityInt(5)商品数量O
GoodsPriceDouble(10)商品价格O
GoodsWeightDouble(10,3)商品重量kgO
GoodsDescString(50)商品描述O
GoodsVolDouble(15,3)商品体积m3O
IsReturnPrintTemplateString(1)返回电子面单模板:0-不需要;1-需要O
IsSendMessageInt(1)是否订阅短信:0-不需要;1-需要O
TemplateSizeString(10)模板规格(默认的模板无需传值,非默认模板传对应模板尺寸)  

二联150丰密面单(TemplateSize传值15001)

三联210丰密面单(TemplateSize传值21001)

二联150(默认模板,TemplateSize传值为空)

三联210(TemplateSize传值210)

二联180新(TemplateSize传值180)

O
PackingTypeInt(2)包装类型(快运字段)默认为0; 0- 纸 1- 纤 2- 木 3- 托膜 4- 木托 99-其他C
DeliveryMethodInt(1)送货方式(快运字段)默认为0; 0- 自提 1- 送货上门(不含上楼) 2- 送货上楼C

 

5.返回参数(Return)

参数名称类型说明必须要求
EBusinessIDString(10)用户IDR
OrderOrderCodeString(30)订单编号R
ShipperCodeString(10)快递公司编码R
LogisticCodeString(400)快递单号R
MarkDestinationString(20)大头笔O
OriginCodeString(20)始发地区域编码O
OriginNameString(20)始发地/始发网点O
DestinatioCodeString(20)目的地区域编码O
DestinatioNameString(20)目的地/到达网点O
SortingCodeString(20)分拣编码O
PackageCodeString(20)集包编码O
PackageNameString(50)集包地O
DestinationAllocationCentreString(50)目的地分类O
SuccessBool(10)成功与否(true/false)R
SignWaybillCodeString(15)签回单单号O
ResultCodeString(5)返回编码R
ReasonString(50)失败原因O
UniquerRequestNumberString(50)唯一标识R
PrintTemplateString面单打印模板内容(html格式)O
EstimatedDeliveryTimeDate订单预计到货时间yyyy-mm-ddO
SubCountInt(5)子单数量O
SubOrdersString(400)子单单号O
SubPrintTemplatesString(2000)子单模板内容(html格式)O
SignBillPrintTemplateString(2000)签回单模板内容(html格式)O
ReceiverSafePhoneString(20)收件人安全电话O
SenderSafePhoneString(20)收件人安全电话O
DialPageString(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,请求数据包结构

image.png

 

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.关于顺丰月结账号接口传值

MonthCode传值顺丰月结账号(PayType为1、2时不填,为3、4时必填),

PayType传值付款方式(包含:1-现付,2-到付,3-月结,4-第三方付),

客户号配置页需留两个栏位(需正确对应以上两个字段)由发货商家填写,商家自己开发的系统也建议保留配置页,万一账号更换了呢?

12.关于快递类型


    • 顺丰速运快递类型如下:

快递类型

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.关于顺丰速运增值服务传值


    • 保价

                   字段传值:"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/,可更换其他快递发货;



【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。