目录

1.完成前期准备工作

2.API接口

3.请求参数（Headers）

4.请求参数（Body）

5.返回参数（Return）

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

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

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

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

10.关于签名

前言

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

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

图一

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

图二

 图二也是一张二联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）

4.请求参数（Body）

5.返回参数（Return）

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 关于快递类型

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

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