【快递100功能开发】系统模块集成快递订阅推送服务(一)——构建项目和建表语句
需求说明
公司的物料订单,会由采购部维护快递单号,而仓库管理人员通过点击快递单号,可以在系统中查询快递单的详细物流轨迹信息。
目前有两个接口可供选择,一是订阅推送,二是实时查询。
官方文档: 快递订阅查询快递api接口技术文档
GitHub 实例(Java版本):https://github.com/kuaidi100-api/java-demo
在使用快递100的接口之前,需要注册一个快递100的账号,在企业管理的后台中,获取授权key以及customer,具体信息如下图:
构建项目
我使用的是maven构建项目,因此需要先导入坐标。
<!--快递100接口-->
<dependency>
<groupId>com.github.kuaidi100-api</groupId>
<artifactId>sdk</artifactId>
<version>1.0.4</version>
</dependency>
初始化数据库
我的需求是通过自动扫描物料表中的数据,然后批量,自动订阅。
首先创建一张表,保存从物料表中扫描到的所有订单数据。
- 快递单表sys_express(必须)
CREATE TABLE `sys_express` (
`express_id` bigint NOT NULL AUTO_INCREMENT COMMENT '快递ID',
`express_num` varchar(40) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递单号',
`company_code` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递公司编码',
`status` int NOT NULL DEFAULT '400' COMMENT '快递状态(3代表已签收)',
`sub_status` int NOT NULL DEFAULT '400' COMMENT '快递订阅状态(200代表订阅成功,400表示未订阅)',
`sub_param` varchar(2000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '订阅请求参数',
`sub_result` varchar(2000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '订阅返回参数',
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`sub_time` datetime DEFAULT NULL COMMENT '订阅时间',
`remark` varchar(40) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '备注信息',
PRIMARY KEY (`express_id`)
) ENGINE=InnoDB AUTO_INCREMENT=9 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='快递单主表';
- 快递单订阅推送报文表 sys_express_data(必须)
快递单订阅推送的报文,最好是保存入库,这样以后出现问题,可以和快递100联系,排查问题
CREATE TABLE `sys_express_data` (
`express_data_id` bigint NOT NULL AUTO_INCREMENT COMMENT '快递ID',
`express_num` varchar(40) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递单号',
`receive_text` varchar(4000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '订阅接收的报文',
`receive_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '接收时间',
`status` char(1) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '0' COMMENT '状态(0正常 1删除)',
PRIMARY KEY (`express_data_id`)
) ENGINE=InnoDB AUTO_INCREMENT=33 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='快递单订阅推送报文表';
- 快递轨迹表sys_express_info(必须)
快递单订阅推送的报文,需要进行解析,然后存入库中,最终展示在前台页面,也是这个表中的数据。
CREATE TABLE `sys_express_info` (
`info_id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
`express_num` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递单号',
`company_code` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递公司编码',
`status` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递状态',
`context` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '快递详情',
`time` datetime DEFAULT NULL COMMENT '时间',
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
PRIMARY KEY (`info_id`)
) ENGINE=InnoDB AUTO_INCREMENT=330 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='快递轨迹表';
- 快递单状态表(非必须)
快递单状态表,我也维护在数据库中
CREATE TABLE `sys_express_state` (
`state_id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
`state_code` smallint NOT NULL COMMENT '快递状态编码',
`state_desc` varchar(200) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '快递状态描述',
`state_text` varchar(200) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '快递状态的详细描述',
`status` char(1) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '0' COMMENT '状态(0正常 1删除)',
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
PRIMARY KEY (`state_id`)
) ENGINE=InnoDB AUTO_INCREMENT=46 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='快递单状态表';
-- ----------------------------
-- Records of sys_express_state
-- ----------------------------
INSERT INTO `sys_express_state` VALUES ('10', '1', '揽收', '快件揽件', '0', '2021-11-23 11:08:44');
INSERT INTO `sys_express_state` VALUES ('11', '101', '已下单', '已经下快件单', '0', '2021-11-23 11:08:59');
INSERT INTO `sys_express_state` VALUES ('12', '102', '待揽收', '待快递公司揽收', '0', '2021-11-23 11:09:25');
INSERT INTO `sys_express_state` VALUES ('13', '103', '已揽收', '快递公司已经揽收', '0', '2021-11-23 11:10:40');
INSERT INTO `sys_express_state` VALUES ('14', '0', '在途', '快件在途中', '0', '2021-11-23 11:11:20');
INSERT INTO `sys_express_state` VALUES ('15', '1001', '到达派件城市', '快件到达收件人城市', '0', '2021-11-23 11:11:40');
INSERT INTO `sys_express_state` VALUES ('16', '1002', '干线', '快件处于运输过程中', '0', '2021-11-23 11:11:56');
INSERT INTO `sys_express_state` VALUES ('17', '5', '派件', '快件正在派件', '0', '2021-11-23 11:12:36');
INSERT INTO `sys_express_state` VALUES ('18', '501', '投柜或驿站', '快件已经投递到快递柜或者快递驿站', '0', '2021-11-23 11:12:56');
INSERT INTO `sys_express_state` VALUES ('19', '3', '签收', '快件已签收', '0', '2021-11-23 11:13:19');
INSERT INTO `sys_express_state` VALUES ('20', '301', '本人签收', '收件人正常签收', '0', '2021-11-23 11:14:00');
INSERT INTO `sys_express_state` VALUES ('21', '302', '派件异常后签收', '快件显示派件异常,但后续正常签收', '0', '2021-11-23 11:14:24');
INSERT INTO `sys_express_state` VALUES ('22', '303', '代签', '快件已被代签', '0', '2021-11-23 11:14:41');
INSERT INTO `sys_express_state` VALUES ('23', '304', '投柜或站签收', '快件已由快递柜或者驿站签收', '0', '2021-11-23 11:15:00');
INSERT INTO `sys_express_state` VALUES ('24', '4', '退签', '此快件单已退签', '0', '2021-11-23 11:16:40');
INSERT INTO `sys_express_state` VALUES ('25', '401', '已销单', '此快件单已撤销', '0', '2021-11-23 11:16:58');
INSERT INTO `sys_express_state` VALUES ('26', '14', '拒签', '收件人拒签快件', '0', '2021-11-23 11:17:12');
INSERT INTO `sys_express_state` VALUES ('27', '6', '退回', '快件正处于返回发货人的途中', '0', '2021-11-23 11:17:39');
INSERT INTO `sys_express_state` VALUES ('28', '7', '转投', '快件转给其他快递公司邮寄', '0', '2021-11-23 11:18:00');
INSERT INTO `sys_express_state` VALUES ('29', '8', '清关', '快件清关', '0', '2021-11-23 11:18:23');
INSERT INTO `sys_express_state` VALUES ('30', '10', '待清关', '快件等待清关', '0', '2021-11-23 11:18:46');
INSERT INTO `sys_express_state` VALUES ('31', '11', '清关中', '快件正在清关流程中', '0', '2021-11-23 11:19:05');
INSERT INTO `sys_express_state` VALUES ('32', '12', '已清关', '快件已完成清关流程', '0', '2021-11-23 11:19:19');
INSERT INTO `sys_express_state` VALUES ('33', '13', '清关异常', '货物在清关过程中出现异常', '0', '2021-11-23 11:19:37');
INSERT INTO `sys_express_state` VALUES ('34', '14', '拒签', '收件人拒签快件', '0', '2021-11-23 11:19:54');
INSERT INTO `sys_express_state` VALUES ('35', '2', '疑难', '快件存在疑难', '0', '2021-11-23 11:20:10');
INSERT INTO `sys_express_state` VALUES ('36', '201', '超时未签收', '快件长时间派件后未签收', '0', '2021-11-23 11:20:27');
INSERT INTO `sys_express_state` VALUES ('37', '202', '超时未更新', '快件长时间没有派件或签收', '0', '2021-11-23 11:20:45');
INSERT INTO `sys_express_state` VALUES ('38', '203', '拒收', '收件人发起拒收快递,待发货方确认', '0', '2021-11-23 11:21:04');
INSERT INTO `sys_express_state` VALUES ('39', '204', '派件异常', '快件派件时遇到异常情况', '0', '2021-11-23 11:21:25');
INSERT INTO `sys_express_state` VALUES ('40', '205', '柜或驿站超时未取', '快件在快递柜或者驿站长时间未取', '0', '2021-11-23 11:21:40');
INSERT INTO `sys_express_state` VALUES ('41', '206', '无法联系', '无法联系到收件人', '0', '2021-11-23 11:21:59');
INSERT INTO `sys_express_state` VALUES ('42', '207', '超区', '超出快递公司的服务区范围', '0', '2021-11-23 11:22:13');
INSERT INTO `sys_express_state` VALUES ('43', '208', '滞留', '快件滞留在网点,没有派送', '0', '2021-11-23 11:22:27');
INSERT INTO `sys_express_state` VALUES ('44', '209', '破损', '快件破损', '0', '2021-11-23 11:22:44');
INSERT INTO `sys_express_state` VALUES ('45', '400', '自定义状态', '主表中未签收的快递单,均处于此状态', '0', '2021-11-25 14:26:39');
- 快递公司表 sys_express_company(非必须)
快递100的接口,快递公司是比较多的,大概有近千的快递公司。
可以把Excel文档下载下来,直接导入到数据库中。
CREATE TABLE `sys_express_company` (
`company_id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
`company_code` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '公司编码',
`company_name` varchar(80) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '' COMMENT '公司名称',
`status` char(1) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '0' COMMENT '状态(0正常 1停用)',
PRIMARY KEY (`company_id`)
) ENGINE=InnoDB AUTO_INCREMENT=1352 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='快递公司编码表';