韵达快递对接测试

最新推荐文章于 2024-12-25 22:50:27 发布

原创最新推荐文章于 2024-12-25 22:50:27 发布 · 984 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#spring #java #intellij idea #postman #json

物流sdk对接专栏收录该内容

2 篇文章

订阅专栏

这篇博客详细介绍了如何进行韵达快递的API对接测试，包括注册、认证、订阅API、导入jar包等准备工作，并重点讲解了预估运费、电子面单下单、散件下单及取消散件订单接口的测试开发，涉及Java环境下的接口调用和测试结果分析。

部署运行你感兴趣的模型镜像

韵达快递对接测试

1 对接准备

1.1 注册

使用手机号即可注册

1.2 认证

需要进行企业认证，输入公司名称，公司地址，所属行业，统一社会信用代码，三件合一证件

等待审核，审核成功之后进行控制台

显示基本信息（生产环境、测试环境），以及订阅列表

其中APPKEY，APPSECRET最为重要。

1.3 订阅API

点击新增订阅，可订阅API，共有10条，我是全部订阅

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-04va2JSJ-1650538090712)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220421095623627.png)]

1.4 导入jar包

下载jar包，kfpt-sdk-java地址为：https://openapi.yundaex.com/openapi-gateway/SDK-JAVA/kfpt-sdk-1.0.0.jar

java源码下载地址：https://openapi.yundaex.com/openapi-gateway/SDK-JAVA/kfpt-sdk.zip

PHP下载地址：https://openapi.yundaex.com/openapi-gateway/SDK-JAVA/openapi-demo-php-1.0.0.php

1.5 准备完成，进行联调测试

2 测试开发

2.1 依赖注入

将jar包导入resources下的lib中，在pom.xml注入

<!--尝试对接韵达-->
        <dependency>
            <groupId>yunda.sdk</groupId>
            <artifactId>yd</artifactId>
            <version>1.0</version>
            <scope>system</scope>
            <systemPath>${project.basedir}/src/main/resources/lib/kfpt-sdk-1.0.0.jar</systemPath>
        </dependency>

2.2 预估运费接口

该接口只有一级地址–一级地址，还有重量，三个参数，对接要慎重

2.2.1 预估运费参数

package com.hc.store.yunda;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author chajintao
 * @date 2022/4/21 9:06
 */
@ApiModel("预估运费参数")
@Data
public class YdFreightParam {
    @ApiModelProperty("寄件人省份/直辖市")
    private String startCity;
    @ApiModelProperty("收件人省份/直辖市")
    private String endCity;
    @ApiModelProperty("重量（kg）")
    private String weight;
}

2.2.2 @Test

@RequestMapping("/dd")
    public String dd(){
        YdFreightParam yd = new YdFreightParam();
        yd.setStartCity("山东省");
        yd.setEndCity("安徽省");
        yd.setWeight("2.00");

        String serverUrl = "https://openapi.yundaex.com/openapi-api/v1/order/getFreightInfo";

        String jsonParams = JSON.toJSONString(yd);
        String result = OpenApiHttpUtils.doPostJson(serverUrl,jsonParams,appKey,appSecret);
        System.out.println(result);
        return result;
    }

2.2.3 result

{
    "code": "0000",
    "message": "请求成功",
    "result": true,
    "data": 17.0
}

2.3 电子面单下单接口

2.3.1 下单参数

参数	类型	必填	说明
appid	String	true	合作社appid(等同于app-key)
partner_id	String	true	韵达白马账户（合作网点提供）
secret	String	true	联调密码（合作网点）
orders	List	true	订单详情

2.3.2 订单详情参数

参数		类型	长度	必填	参数说明
order_serial_no		String	32	true	订单唯一序列号 `由字母、数字、下划线组成，必须保证唯一，请对特殊符号进行过滤`
khddh		String	32	true	大客户系统订单的订单号`可与订单唯一序列号相同`
sender	Object			true	寄件人信息
	name	String	16	true	寄件人姓名
	company	String	32	false	寄件人公司
	province	String	16	false	寄件人省份
	city	String	16	false	寄件人市
	county	String	16	false	寄件人区/县
	address	String	125	true	详细地址 `必须添加省市区并以半角逗号隔开`
	phone	String	16	false	固定电话 `固定电话或移动电话至少填一项`
	mobile	String	16	false	手机号
receiver	Object			true	收件人
	name	String	16	true	收件人姓名
	company	String	32	false	收件人公司
	province	String	16	false	收件人省份
	city	String	16	false	收件人市
	county	String	16	false	收件人区/县
	address	String	64	true	详细地址 `必须添加省市区并以半角逗号隔开`
	phone	String	16	false	固定电话`固定电话或移动电话至少填一项`
	mobile	String	16	false	手机号
weight		Double	10,3	false	物品重量
size		String	16	false	物品大小(单位米)
value		Double	10,2	false	货物金额
collect_branch		String	8	false	揽件网点编码
collection_value		Double	10,2	false	代收货款金额 `目前仅用于cod订单，cod订单必填`
other_charges		Double	10,2	false	其他费用
items		List		false	商品信息集合
item	name	Stirng	100	false	商品名称 `cod订单必填`
	number	String	8	false	数量
	remark	String	32	false	说明
special		String		false	商品类型`保留字段，暂时不用(见商品类型字段)`
remark		String		false	备注
cus_area1		String	255	false	可以自定义显示信息1，打印在客户自定义区域1，换行请用\n
cus_area2		String	255	false	可以自定义显示信息2，打印在客户自定义区域2，换行请用\n
wave_no		String	255	false	客户波次号，按照此号进行批量打印校验，批量下单时，此波次号需要相同
order_type		String	64	true	运单类型`参数值对照order_type字典表`可固定为common
isProtectPrivacy		String	4	false	判断订单是否是隐私订单，如果是隐私订单把收件人姓名和电话进行脱敏处理（1表示是，0表示否）`隐私面单业务对接需与韵达方确认业务需求`
platform_source		varchar	24	false	平台来源
node_id		String	10	true	350（默认）
multi_pack					一票多件
	mulpck	varchar	255	false	是否一票多件`一票多件必填是：填1；否：空，不填 (必须走增值服务才能生效{"type":"MUL","markingValue":{"value":10(总单量)}})`
	total	int	11	false	总包裹数量：当最后一件时，传输此值
	endmark	tinyint	2	false	结束标记,当最后一件时,传输此值 0:否，1:是
markingInfos		varchar	255	false	增值服务标签`增值服务必填，json字符串`

2.3.4 返回参数

参数	类型	必填	参数说明
result	boolean	true	是否成功
code	String	true	响应编码
message	String	true	响应内容
data	Object	true	返回对象信息

data字段说明

参数	参数说明
order_serial_no	客户订单号
mailno	运单号
pdf_info	pdf参数信息（根据客户的需求返回json格式数据或对json格式进行加密后的数据）
status	返回状态，1表示成功，0表示失败
msg	成功或者错误的提示信息

2.3.5 暂无法完成

2.4 散件下单（新）

2.4.1 下单参数

package com.hc.store.yunda;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.List;

/**
 * @author chajintao
 * @date 2022/4/13 8:51
 */
@Data
@ApiModel("散件下单（新）参数")
public class YdPushOrderParam {

    @ApiModelProperty("合作商app-key")
    private String appid;
    @ApiModelProperty("合作商订单号")
    private String orderid;
    @ApiModelProperty("运单回传地址url")
    private String backurl;
    @ApiModelProperty(value = "取件开始时间", notes = "(yyyy-MM-dd HH:mm:ss)")
    private String sendstarttime;
    @ApiModelProperty("取件结束时间")
    private String sendendtime;
    @ApiModelProperty("物品重量")
    private Double weight;
    @ApiModelProperty(value = "货物大小（米）", notes = "用半角的逗号来分隔长宽高")
    private String size;
    @ApiModelProperty("货物金额")
    private Double value;
    @ApiModelProperty("运费")
    private Double freight;
    @ApiModelProperty("保险费")
    private Double premium;
    @ApiModelProperty("其他费用")
    private Double other_charges;
    @ApiModelProperty("原样返回字段")
    private String backparam;
    @ApiModelProperty(value = "商品类型", notes = "0文件类，1电子产品类，2办公用品类，服装鞋帽，箱包类，" +
            "3化妆品，美容产品类，4珠宝，手表，眼镜，贵重饰品类，5食品，保健药品类，6工艺品类（包括瓷器，茶具，烹饪用品），" +
            "7玩具乐器类，8其他类")
    private String special;
    @ApiModelProperty("备注")
    private String remark;
    @ApiModelProperty("商品信息集合")
    private List<Item> items;
    @ApiModelProperty("寄件人信息")
    private YdOrderPlaceBean sender;
    @ApiModelProperty("收件人信息")
    private YdOrderPlaceBean receiver;
}

2.4.2 收寄件人信息参数

package com.hc.store.yunda;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author chajintao
 * @date 2022/4/13 8:52
 */

@Data
@ApiModel("收寄信息")
public class YdOrderPlaceBean {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("公司")
    private String company;
    @ApiModelProperty("省份")
    private String province;
    @ApiModelProperty("市")
    private String city;
    @ApiModelProperty("区县")
    private String county;
    @ApiModelProperty("详细地址")
    private String address;
    @ApiModelProperty("邮编")
    private String postcode;
    @ApiModelProperty("固定电话（固话、手机号必填一项）")
    private String phone;
    @ApiModelProperty("手机号")
    private String mobile;

}

2.4.3 商品信息参数

package com.hc.store.yunda;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author chajintao
 * @date 2022/4/13 8:49
 */
@Data
@ApiModel("商品信息")
public class Item {
    @ApiModelProperty("商品名称")
    private String name;
    @ApiModelProperty("商品数量")
    private String number;
    @ApiModelProperty("商品备注")
    private String remark;
    
}

2.4.4 @Test

@RequestMapping("/push")
    public String pushOrder() {

        String serverUrl = "https://openapi.yundaex.com/openapi-api/v1/order/pushOrder";

        Item item = new Item();
        item.setName("衣服");
        item.setNumber("1");
        item.setRemark("袜子");

        List<Item> items = new ArrayList<>();
        items.add(item);

        YdOrderPlaceBean receiver = new YdOrderPlaceBean();
        receiver.setAddress("青浦区盈港东路6679号");
        receiver.setCity("上海市");
        receiver.setCompany("");
        receiver.setProvince("上海市");
        receiver.setCounty("青浦区");
        receiver.setName("李四");
        receiver.setMobile("17601205970");

        YdOrderPlaceBean sender = new YdOrderPlaceBean();

        sender.setAddress("青浦区盈港东路7766号");
        sender.setCity("上海市");
        sender.setCompany("string");
        sender.setProvince("上海市");
        sender.setCounty("青浦区");
        sender.setName("李四");
        sender.setMobile("17601205970");

        SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");



        YdPushOrderParam orderParam = new YdPushOrderParam();

        orderParam.setItems(items);
        orderParam.setReceiver(receiver);
        orderParam.setSender(sender);

        orderParam.setAppid("000001");
        orderParam.setBackparam("散单测试");
        orderParam.setBackurl("http://www.baidu.com");

        orderParam.setOrderid(UUID.randomUUID().toString().replace("-", ""));
        orderParam.setOther_charges(0.0);
        orderParam.setFreight(10.0);
        orderParam.setPremium(1.0);
        orderParam.setRemark("是测试，不要接");

        orderParam.setSendendtime(simpleDateFormat.format(new Date()));

        orderParam.setSendstarttime(simpleDateFormat.format(new Date()));

        orderParam.setSize("0.12,0.23,0.11");
        orderParam.setSpecial("0");
        orderParam.setValue(126.5);
        orderParam.setWeight(0.0);

        String jsonParams = JSON.toJSONString(orderParam);
        System.out.println(JSON.toJSONString(orderParam));

        String re = OpenApiHttpUtils.doPostJson(serverUrl,jsonParams,appKey,appSecret);

        return re;
    }

2.4.5 result

{
    "code": "0000",
    "message": "请求成功",
    "result": true,
    "data": {
        "orderid": "97063e9ea22c4d2da77369af995fd946",
        "backparam": "散单测试"
    }
}

2.6 取消散件订单（新）

2.6.1 参数

package com.hc.store.yunda;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author chajintao
 * @date 2022/4/21 9:22
 */
@ApiModel("散单取消参数")
@Data
public class YdCancelParam {

    @ApiModelProperty(value = "app_key", required = true)
    private String appid;
    @ApiModelProperty(value = "原样返回字段", required = false)
    private String backparam;
    @ApiModelProperty(value = "订单号", required = true)
    private String orderid;

}

2.6.2 @Test

@RequestMapping("/cancel")
    public String cancel(){

        String serverUrl = "https://openapi.yundaex.com/openapi-api/v1/order/cancelOrder";
        YdCancelParam yd = new YdCancelParam();

        yd.setAppid("000001");
        yd.setBackparam("取消散单测试");
        yd.setOrderid("97063e9ea22c4d2da77369af995fd946");

        String jsonParams = JSON.toJSONString(yd);

        String result = OpenApiHttpUtils.doPostJson(serverUrl,jsonParams,appKey,appSecret);
        System.out.println(result);

        return result;
    }

2.6.3 result

{
    "code": "0000",
    "message": "请求成功",
    "result": true,
    "data": {
        "orderid": "97063e9ea22c4d2da77369af995fd946",
        "backparam": "取消散单测试"
    }
}