如何通过快递100电子面单API来获取物流单号和打印面单？

在电商和物流系统中，集成电子面单功能可以大幅提升发货效率，本文将详细介绍如何使用快递100电子面单API快速实现下单、面单生成和打印功能。

一、电子面单API简介

电子面单是现代物流行业的核心技术之一，它通过API接口方式生成数字面单，取代了传统的手写面单方式。快递100为开发者提供了完善的电子面单API服务，支持60+主流快递公司，可以帮助开发者快速集成电子面单功能，满足企业的快速下单打单、回传物流单号的需求。

核心优势：

• 提高效率：快递批量打印面单，支持一单多件，无需人工录入单号，快速打单，提升效率。
• 降低成本：支持远程打印，共享打印机，将打印机的效率最大化，节省不必要的成本。
• 无缝集成：一次开发，对接60+快递公司，支持多个平台，多种业务类型，减少开发周期。
• 多模板支持：提供简单易用的模板编辑器，支持修改电子面单模板，满足不同场景下的打单需求。

二、前期准备工作

1. 注册快递100企业账号

首先，访问快递100官方网站注册企业版账号，在管理后台获取授权Key和secret，这个密钥是调用API的核心凭证。

2. 申请电子面单账号

需要联系合作快递公司的当地网点，申请电子面单月结账号，获取以下信息：

• partnerId：电子面单客户账户或月结账号
• partnerKey：电子面单密码（部分快递公司需要）
• partnerSecret：电子面单密钥（部分快递公司需要）
• partnerName：电子面单客户账户名称

部分快递公司支持线上申请，线上无法申请的请联系网点线下申请。线上申请地址： 电子面单账号在线申请

3. 准备打印设备

根据业务需求准备合适的打印机，快递100支持多种打印方式：

• 本地打印机：打印生成的面单图片/html
• 快递100云打印机：直接通过API调用云打印机打印

三、API接口详解

快递100提供了多个电子面单相关接口，以下是最核心的电子面单下单接口。通过快递公司或网点、菜鸟与淘宝提供的电子面单账号，进行快递下单和打单。支持只下单，或者生成图片/html使用本地打印设备打印输出面单，以及调用快递100云打印设备打印输出面单。

1. 请求基本信息

• 请求地址：https://api.kuaidi100.com/label/order
• 请求方式：HTTP POST或GET
• Content-Type：application/x-www-form-urlencoded

2. 请求参数说明

主要的请求参数如下表所示：

参数名	是否必填	类型	说明
method	是	string	业务类型（固定值：order）
key	是	string	授权码，从快递100后台获取
sign	是	string	32位大写签名，用于身份验证
t	是	string	时间戳，如：1576123932000
param	是	string	JSON字符串，由其他参数拼接

3. 签名生成方式

签名是API调用中的重要安全验证机制，生成规则如下：

// 签名计算公式
sign = MD5(param + t + key + secret)  // 32位大写，不需要加"+"号，secret在快递100管理后台获取

四、操作实例

1. 完整的API调用代码

以下是一个完整的Java示例，展示如何调用快递100电子面单API：

// 准备基础参数
String key = "您的授权key";
String secret = "您的secret";
String t = String.valueOf(System.currentTimeMillis());

// 构建param JSON
JSONObject param = new JSONObject();
param.put("partnerId", "您的月结账号");
param.put("partnerKey", "您的电子面单密码");
param.put("kuaidicom", "yunda"); // 快递公司编码，小写
param.put("tempId", "您的模板ID");

// 收件人信息
JSONObject recMan = new JSONObject();
recMan.put("name", "张三");
recMan.put("mobile", "13800138000");
recMan.put("printAddr", "广东省深圳市南山区科技园南区1号");
recMan.put("company", "测试公司");
param.put("recMan", recMan);

// 寄件人信息
JSONObject sendMan = new JSONObject();
sendMan.put("name", "李四");
sendMan.put("mobile", "13900139000");
sendMan.put("printAddr", "上海市浦东新区张江高科园区2号");
sendMan.put("company", "电商公司");
param.put("sendMan", sendMan);

// 订单信息
param.put("cargo", "测试商品");
param.put("count", 1);
param.put("weight", 0.5);
param.put("payType", "SHIPPER");
param.put("expType", "标准快递");
param.put("printType", "IMAGE"); // 生成图片短链

// 生成签名
String signStr = param.toString() + t + key + secret;
String sign = MD5Util.md5(signStr).toUpperCase();

// 构建请求参数
Map<String, String> params = new HashMap<>();
params.put("method", "order");
params.put("key", key);
params.put("sign", sign);
params.put("t", t);
params.put("param", param.toString());

// 发送POST请求
String result = HttpClientUtil.post("https://api.kuaidi100.com/label/order", params);

2. 响应结果处理

调用API后，会返回JSON格式的结果：

成功响应示例：

{
  "result": true,
  "returnCode": "200",
  "message": "成功",
  "data": {
    "kuaidinum": "1234567890123",
    "label": "https://print.kuaidi100.com/xxx...",
    "taskId": "xxxxxxx"
  }
}

常见错误代码：

返回代码	含义	解决方法
200	提交成功	/
30001	参数错误	检查参数格式和必填项
30002	验证签名失败	检查加密方式，param +t+key+ secret的顺序进行MD5加密，加密后字符串转32位大写,不用加上“+”号
30003	账号信息不正确	检查key是否正确
30004	账号单量不足	单量不足需要充值
30005	快递公司返回异常	按照描述可以自行检查是否参数缺失或者错误

五、打印方式详解

快递100电子面单API支持多种打印方式，适应不同业务场景：

1. 打印类型参数

通过设置 printType 参数选择不同的打印方式：

• NON：只下单不打印（默认值）

• IMAGE：生成图片短链，可下载后使用本地打印机打印

• HTML：生成HTML短链，可在浏览器中打印

• CLOUD：使用快递100云打印机直接打印（需要配备云打印机并设置siid参数）

2. 云打印集成

如果使用快递100云打印机，需要额外设置以下参数：

java
param.put("printType", "CLOUD");
param.put("siid", "您的打印机设备编码"); // 必填
param.put("direction", "0"); // 打印方向：0-正方向，1-反方向

3. 自定义打印接口

对于有特殊打印需求的场景，快递100还提供了自定义打印接口，可以打印发货单等其他类型文档：

• 接口地址：https://poll.kuaidi100.com/printapi/printtask.do

• method参数：printOrder

六、高级功能与注意事项

1. 子单与回单功能

• 子单功能：当一件包裹需要分成多个子包裹时，可以设置 needChild=1 和 count 大于1

• 回单功能：需要回单服务时，设置 needBack=1，返回的回单号见 returnNum 字段

2. 电商平台授权

如果使用淘宝、菜鸟、拼多多等电商平台的电子面单，需要进行平台授权：

java
param.put("net", "taobao"); // 淘宝授权
// 或
param.put("net", "cainiao"); // 菜鸟授权
// 或
param.put("net", "pinduoduoWx"); // 拼多多授权

3. 错误处理与调试建议

1. 测试环境：先在测试环境下进行模拟调用，熟悉接口行为
2. 参数验证：确保所有必填参数均已正确填写
3. 签名检查：验证签名生成算法是否正确，特别是参数顺序和大小写
4. 网络超时：设置合理的超时时间，并实现重试机制
5. 日志记录：完整记录请求和响应数据，便于排查问题

七、常见问题解答

Q1：如何获取快递公司编码？

A：快递公司编码一律用小写字母，如 “yunda” 表示韵达，完整列表请参考快递100参数字典。

Q2：电子面单申请被拒绝怎么办？

A：确认月结账号是否有效，或联系快递网点确认电子面单功能是否已开通。

Q3：如何实现面单复打？

A：快递100提供了专门的复打接口，可以在提交打印请求2天内的打印任务进行复打（最多10次）。

总结

通过快递100电子面单API，开发者可以快速、高效地集成电子面单功能到自己的系统中。关键在于理解API的调用流程、签名机制和各参数的含义。建议先在测试环境充分验证，然后再部署到生产环境。

快递100API文档提供了详细的参数字典和错误代码说明，在开发过程中遇到问题时，查阅官方文档是首选的解决方法。

希望本文能帮助您顺利完成快递100电子面单API的集成工作，如有任何问题，欢迎在评论区留言讨论。