【韵达开放平台快递物流查询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

业务参数

请求示例

{
    "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": 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）能进一步提升开发效率。希望本篇博客能为你的开发过程提供帮助，祝你顺利完成项目！