Chinaunix首页 | 论坛 | 博客
  • 博客访问: 5645
  • 博文数量: 4
  • 博客积分: 0
  • 博客等级: 民兵
  • 技术积分: 50
  • 用 户 组: 普通用户
  • 注册时间: 2017-06-24 10:47
文章分类
文章存档

2021年(2)

2019年(2)

我的朋友

分类: 其他平台

2021-01-28 18:13:50

电商平台及ISV商家对物流api接口的需求有很多,今天我们主要分享的就是快递鸟快递单号查询接口的对接指南,快递单号查询接口对接的应用场景有很多,很多场景会遇到,最主要的就是电商网站用户打开“我的订单”时调用此API显示物流信息详情,电商管理后台的物流系统,客服在对账前查询所有运单的签收状态,并追踪问题,电商平台对商家物流管控,要求必须在多久快递必须发出要看到揽件状态,多久必须收到货物看到签收状态,根据这些状态对商家管控从而提高用户的整体满意度。
全球物流单号查询API接口旨在为电商、电商平台、物流工具、打单工具、仓储系统、移动APP等系统提供专业、稳定、优质的API 接口服务,满足不同用户的物流管理需求。支持国内外600多家物流商的接口,可以一次性对接,方便省心。

1.完成前期准备工作

1.1,去快递鸟官网一个账号

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

1.3,完成实名认证流程,

1.4,订购一个免费套餐,


2.API接口


2.1,测试调用地址:

2.2,正式调用地址:

2.3,请求方式:POST

2.4,编码格式(utf-8):application/x-www-form-urlencoded;charset=utf-8

2.5,返回类型:JSON

2.6,调试页面:

2.7,调试工具:(使用快递鸟账号登录)


3.请求参数(Headers)


参数名称 类型 说明 必须要求
RequestData String 请求内容需进行URL(utf-8)编码,请求内容JSON格式,须和DataType一致 必填
EBusinessID String 用户ID, 必填
RequestType String 请求指令类型:1002  必填

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



4.请求参数(Body)

参数名称 类型 说明 必须要求
OrderCode String 订单编号 选填
ShipperCode String 快递公司编码,中通:ZTO 必填
LogisticCode String 物流运单号 必填

 

5.返回参数(Return)

参数名称 类型 说明 必须要求
EBusinessID String 用户ID  必填
ShipperCode String 快递公司编码  必填
LogisticCode String 物流运单号 选填
Success String 成功与否 必填
Reason String 失败原因 选填
State String 物流状态:2-在途中,3-签收,4-问题件 必填
Traces  String 时间  
AcceptTime String   必填
AcceptStation String 描述  选填
Remark String 备注 必填



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

RequestData=%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27ZTO%27%2c%27LogisticCode%27%3a%2778120038107849%27%7d&EBusinessID=1617571&
RequestType=1002&DataSign=YzBmYTViYmExZmFhOGY1ZTY3MWY5OGFjYWRhNWVjNjU%3d&DataType=2


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

复制代码

{
"LogisticCode": "78120038107849",
"ShipperCode": "ZTO",
"Traces": [{
"AcceptStation": "【济源市】 【济源】(0391-6965909) 的 张霞(18839032214) 已揽收",
"AcceptTime": "2020-01-16 18:30:33"
}, {
"AcceptStation": "【济源市】 快件离开 【济源】 已发往 【深圳中心】",
"AcceptTime": "2020-01-16 18:36:41"
}, {
"AcceptStation": "【新乡市】 快件已经到达 【新乡中转】",
"AcceptTime": "2020-01-16 22:45:49"
}, {
"AcceptStation": "【新乡市】 快件离开 【新乡中转】 已发往 【深圳中心】",
"AcceptTime": "2020-01-16 22:47:48"
}, {
"AcceptStation": "【深圳市】 快件已经到达 【深圳中心】",
"AcceptTime": "2020-01-18 04:05:46"
}, {
"AcceptStation": "【深圳市】 快件离开 【深圳中心】 已发往 【深圳龙华】",
"AcceptTime": "2020-01-18 08:34:46"
}, {
"AcceptStation": "【深圳市】 快件已经到达 【深圳龙华】",
"AcceptTime": "2020-01-18 13:14:10"
}, {
"AcceptStation": "【深圳市】 【深圳龙华】 的陈智龙-王颖(13923773902) 正在第1次派件, 请保持电话畅通,并耐心等待(95720为中通快递员外呼专属号码,请放心接听)",
"AcceptTime": "2020-01-18 16:38:35"
}, {
"AcceptStation": "【深圳市】 快件已由【丰巢的鑫茂花园A区(丰巢智能快递柜)】代签收, 如有问题请电联(13923773902 / 4000633333,18025858922), 感谢您使用中通快递, 期待再次为您服务!",
"AcceptTime": "2020-01-18 17:32:15"
}],
"State": "3",
"EBusinessID": "1617571",
"Success": true
}

 
复制代码

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

复制代码
{
"LogisticCode": "295734066970",
"ShipperCode": "ZTO",
"Traces": [],
"State": "0",
"EBusinessID": "1264783",
"Reason": "业务错误[没有可用套餐]",
"Success": false }
复制代码

说明:未实名认证,未订购套餐,套餐可用查询量已经用完 都会返回此报文信息
 / 

9.无轨迹返回报文(示例)

复制代码
{
"LogisticCode": "295734066970",
"ShipperCode": "ZTO",
"Traces": [],
"State": "0",
"EBusinessID": "1264783",
"Reason": "暂无轨迹信息",
"Success": true }
复制代码


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

10.1,请求数据包结构

在这里插入图片描述

10.2,C#调用代码示例

复制代码
//电商ID
string eEBusinessID = "test1617571";
 //电商加密私钥,快递鸟提供,注意保管,不要泄漏
string appKey= "554343b2-7252-439b-b4eb-1af42c8f2175";
 //请求url
string reqURL = "";
//请求指令 
string reqType="1002";
//2-json 
string dataType = "2"; 
//字符编码采用UTF-8 
string charset = "UTF-8"; 
//JSON字符串string 
string jsonStr = 
"{\"OrderCode\":\"\",\"ShipperCode\":\"SF\",\"LogisticCode\":\"118461988807\"}" ;
//把(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的方法就能获取到里面的字段信息。  
复制代码

10.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;
    }
复制代码


11.中通快递查询接口应用效果


 





12.关于签名

快递鸟和第三方电子商务公司系统进行对接,有一定的安全机制。采用 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 相当于密码。 
复制代码

13.返回码定义

编码 说明
100 成功
101 缺少必要参数
102 校验问题
103 格式问题
阅读(678) | 评论(0) | 转发(0) |
给主人留下些什么吧!~~