【韵达开放平台快递物流查询API对接流程】

作为一家深受用户信赖的快递物流服务商，韵达通过开放平台为用户提供高效的快递物流查询API。本篇博客将详细介绍该API的对接流程及相关技术细节，旨在帮助开发者快速完成接入工作，提升业务效率。

---

API简介

物流查询API

韵达开放平台提供标准化的API接口，旨在为客户和平台实现高效的数据交互。通过物流查询服务，用户可轻松获取快件的实时物流信息，优化自身业务流程。

• 核心功能：
  • 物流轨迹查询：通过物流单号获取快件的详细轨迹信息。

---

对接流程

1. 注册用户

首先，需要在韵达开放平台完成注册。注册链接

小提示：建议使用企业邮箱注册，以便及时接收平台的重要通知和信息。

---

2. 企业认证

通过企业认证后，可获得完整接口的访问权限，包括物流轨迹查询、订单服务等功能模块。

注意事项：

• 确保提交的认证资料真实有效；
• 企业认证可能需要一定时间，请合理规划开发周期。

---

3. 联调测试

在正式上线前，需在平台提供的测试环境中进行联调测试，确保接口能够稳定运行。

测试建议：

• 测试环境：使用开放平台提供的沙箱环境；
• 数据校验：对测试数据和接口返回值进行验证，确保符合文档要求；
• 沟通协调：保持与技术支持团队的良好沟通，快速解决问题。
  

---

4. 发布上线

完成联调测试后，与平台技术团队确认细节，进入正式环境。上线后，定期监控接口的调用状态，确保服务稳定运行。

---

API鉴权说明

韵达API采用签名认证机制，旨在确保接口调用安全。以下是签名的生成规则及代码示例。

一、简介

JAVA开发引入kfpt-sdk-java.jar包，使用方式和jar下载地址见下方 [五、请求示例JAVA DEMO]

PHP开发引入 openapi-demo-php.php, 使用方式和php文件下载地址见下方 [六、请求示例PHP DEMO]

二、鉴权说明

通过开放平台创建应用完毕之后，为每个应用都会分配一组唯一的app-key和app-secret
假如：
app-key = 999999
app-secret = 04d4ad40eeec11e9bad2d962f53dda9d

三、生成签名sign

①所有业务接口服务 请求方式均为 POST， 请求参数类型Content-Type=application/json
②sign 签名字符生成规则为 MD5( RequstBody(请求参数对象).toJSONString() + “_” + app-secret);

③例如 物流查询接口， 请求参数http body 内容JSON 字符串jsonReqBody:

{“mailno”:“3120052228790”}

app-secret = 04d4ad40eeec11e9bad2d962f53dda9d
那么签名字符串生成为 sign = MD5(jsonReqBody_04d4ad40eeec11e9bad2d962f53dda9d)

四、生成请求消息头

** HTTP headers 增加两个鉴权参数**

① app-key 参数放在头信息中传输（创建应用分配的appkey）
② sign 参数放在头信息中传输 （生成的32位小写的 MD5加密签名串）

五、请求示例JAVA DEMO

package com.yundasys;
public class Main {
    /**
     * 创建应用分配的appkey
     */
    final static String appKey = "999999";
    /**
     * 创建应用分配的appsecret
     */
    final static String appSecret = "04d4ad40eeec11e9bad2d962f53dda9d";

    public static void main(String[] args) {
        //http 工具类通用方法
        String serverUrl = "https://u-openapi.yundasys.com/openapi/outer/logictis/query";
        String sourceContent = "{\"mailno\":\"3120052228790\"}";
        System.out.println(OpenApiHttpUtils.doPostJson( serverUrl, sourceContent, appKey, appSecret));
    }
}

---

物流轨迹服务

通过物流单号实时获取快件物流信息。

接口描述

韵达提供物流轨迹查询接口，对接物流轨迹查询接口需先对接订阅接口。订阅成功后则有权限获取订阅运单的所有物流轨迹信息。

注意：

1. 调用查询的运单号必须先订阅（物流轨迹订阅），否则无法查询到轨迹信息
2. 订阅成功后60天为有效期
3. 只支持单个查询
4. 申请使用物流轨迹查询接口，请联系韵达网点协助通过飞书联系市场营销中心李世纪（90195708），申请接口权限。

基础环境

测试环境

https://u-openapi.yundasys.com/openapi/outer/logictis/query

正式环境

https://openapi.yundaex.com/openapi/outer/logictis/query

测试数据：

• app-key: 999999
• app-secret: 04d4ad40eeec11e9bad2d962f53dda9d

基础入参

统一为POST方式，UTF-8编码
Content-Type为 application/json

Headers

参数	类型	长度	必填	参数说明
app-key	String	6	true	开放平台发放
sign	String	32	true	签名说明参看附录《鉴权说明》
req-time	long	13	true	当前时间戳（毫秒）

业务参数

参数	类型	必填	参数说明
mailno	String	true	运单号

请求示例

{
    "mailno":"340987657890876"
}

java代码

import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public class YundaLogisticsQuery {

    private static final String TEST_URL = "https://u-openapi.yundasys.com/openapi/outer/logictis/query";
    private static final String PROD_URL = "https://openapi.yundaex.com/openapi/outer/logictis/query";

    private static final String APP_KEY = "999999"; // 测试用app-key
    private static final String APP_SECRET = "04d4ad40eeec11e9bad2d962f53dda9d"; // 测试用app-secret

    private static final OkHttpClient client = new OkHttpClient();

    public static void main(String[] args) {
        String mailno = "340987657890876"; // 测试运单号
        try {
            String response = queryLogistics(TEST_URL, mailno);
            System.out.println("接口响应: " + response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * 调用韵达物流轨迹查询接口
     *
     * @param url    接口地址（测试或生产环境）
     * @param mailno 运单号
     * @return 接口响应内容
     * @throws IOException 异常
     */
    public static String queryLogistics(String url, String mailno) throws IOException {
        // 设置请求头
        long currentTimeMillis = System.currentTimeMillis();
        String sign = generateSign(mailno, currentTimeMillis);

        // 构造请求体
        Map<String, String> requestBody = new HashMap<>();
        requestBody.put("mailno", mailno);

        ObjectMapper objectMapper = new ObjectMapper();
        String jsonRequestBody = objectMapper.writeValueAsString(requestBody);

        // 构建请求
        Request request = new Request.Builder()
                .url(url)
                .addHeader("Content-Type", "application/json")
                .addHeader("app-key", APP_KEY)
                .addHeader("sign", sign)
                .addHeader("req-time", String.valueOf(currentTimeMillis))
                .post(RequestBody.create(jsonRequestBody, MediaType.parse("application/json")))
                .build();

        // 发起请求
        try (Response response = client.newCall(request).execute()) {
            if (response.body() != null) {
                return response.body().string();
            }
            return "No response body!";
        }
    }

    /**
     * 生成签名
     *
     * @param mailno        运单号
     * @param reqTimeMillis 请求时间戳（毫秒）
     * @return 签名
     */
    private static String generateSign(String mailno, long reqTimeMillis) {
        // 签名算法：sign = MD5(mailno + app-secret + req-time)
        String rawData = mailno + APP_SECRET + reqTimeMillis;
        return md5(rawData);
    }

    /**
     * MD5加密
     *
     * @param data 原始字符串
     * @return 加密后的字符串
     */
    private static String md5(String data) {
        try {
            java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5");
            byte[] array = md.digest(data.getBytes("UTF-8"));
            StringBuilder sb = new StringBuilder();
            for (byte b : array) {
                sb.append(String.format("%02x", b));
            }
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

返回参数

参数	类型	必填	参数说明
result	boolean	true	是否成功
code	String	true	响应编码
message	String	true	响应内容
data	Object	true	返回对象信息
result	boolean	true	响应状态
time	String	true	时间
mailno	String	true	运单号
remark	String	true	备注
status	String	true	节点状态
steps	List	true	轨迹参数

返回示例

{
	"result": true,
	"code": "0000",
	"message": "请求成功",
    "data":{
    "mailno":"1200000000001",
    "result":"true",
    "time":"2020-01-03 17:32:16",
    "remark":"韵达快运 SERVER-R,查询接口中仅保留最近60天内的数据，如需要查询更早的记录，请访问韵达官方网站：www.yundaex.com ，谢谢！",
    "status":"SIGNED",
    "steps":[
        {
            "time":"2019-08-03 18:13:36",
            "station":"509227",
            "station_name":"香港海港韵达公司吐露港分部",
            "station_type":"1",
            "action":"GOT",
            "description":"【香港特区】香港海港韵达公司吐露港分部 已揽收",
        },
        {
            "time":"2019-08-05 21:48:33",
            "station":"509582",
            "station_name":"广东深圳公司中心分拨分部",
            "station_type":"1",
            "action":"GOT",
            "description":"【深圳市】广东深圳公司中心分拨分部 已揽收",
        }
    ]
}
}

韵达快递单号查询的其他方案

如果需要同时对接多家快递公司（如中通、圆通、韵达等），逐一对接可能增加开发复杂度。可以考虑集成类似快递100API的服务，它集成了超过2100家国内外快递公司，能够一次性完成多个快递公司的物流查询。

• 快递100API优势：
  • 提供统一的接口规范；
  • 支持多快递公司物流查询、电子面单等功能。

官方工具链接：快递100API调试工具

---

总结

韵达开放平台的快递物流查询API为开发者提供了灵活高效的解决方案，而通过对接多快递公司平台（如快递100API）能进一步提升开发效率。希望本篇博客能为你的开发过程提供帮助，祝你顺利完成项目！