C#开发 丰密面单打印接口

# 目录

1.完成前期准备工作

2.API接口

3.请求参数（Headers）

4.请求参数（Body）

5.返回参数（Return）

6.请求完整报文（示例）

7.成功返回报文（示例）

8.失败返回报文（示例）

9.分步讲解（C#版本）

**10.顺丰电子面单打印模板内容（HTML）**

11.关于签名

# 前言

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

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

## **图一**

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

## **图二**

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

# 1.完成前期准备工作

**1.1,去快递鸟[免费注册](http://kdniao.com/reg)一个对接账号**

**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,调试工具：去调试（使用快递鸟账号登录）

# 6.请求报文（示例）

{ "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": "小心轻放" }

# 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#调用方法

///

    /// 字符串MD5加密 ///

    ///要加密的字符串

    ///编码方式

    ///密文

    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;

        }

    } ///

    /// base64编码 ///

    /// 内容

    /// 编码方式

    ///

    private string base64(String str, String charset)

    { return Convert.ToBase64String(System.Text.Encoding.GetEncoding(charset).GetBytes(str));

} ///

    /// Post方式提交数据，返回网页的源代码 ///

    /// 发送请求的 URL

    /// 请求报文参数

    /// 远程资源的响应结果

    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.顺丰电子面单打印模板内容（HTML）**

   

   

   

   

   

   

   

   

   

   

   

   

   

1 / 1             子单号  555555555 母单号  888888888888     运单号  5622033142418     签回单号  3552033142418

顺丰标快 目的地：     010

   

   

   

   

   

   

收方:	北京北京市朝阳区******     杨**  1590****89

   

   

   

   

   

   

   

   

   

月结帐号：3434555 支付方式：寄付月结     声明价值：0     签单返回单号：${SignWaybillCode}     操作要求：${OperateRequire}	代收货款：￥0元 卡号：
	运费：- 费用合计：-

   

   

   

   

   

   

   

   

寄方:

广东省东莞市清溪镇******         鞋袜厂13288****80     原寄地：339

收件员： 寄件日期：2020-02-05 11:34:24

收方签署: 日期：

   

   

   

   

   

   

子单号 234234234     234234     243234324

   

   

   

   

   

   

   

   

寄 方:

广东省东莞市清溪镇******         鞋袜厂13288****80

收 方:

北京北京市朝阳区******         杨**1590****89

   

   

   

   

   

   

   

   

   

   

   

   

   

   

   

   

数量	托寄物	备注
	婴儿用品
订单号     2355334314		费用合计： \- 元

复制以上HTML内容保存为html格式的文件，可以查看模板效果。

# 11.关于签名

快递鸟和第三方电子商务公司系统进行对接，有一定的安全机制。采用 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-第三方付），

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

**注：**商家的顺丰月结账号是否能发对应的快递类型，请事先和顺丰速运分部人员确认，除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/，可更换其他快递发货；