直播带货自动化发货：Python对接快递API实战指南

一、前置准备：环境搭建与API申请

在直播带货的高并发订单场景下，手动录入单号发货效率极低。本指南将使用Python脚本直接对接快递电子面单API，实现自动抓取订单、申请运单号、打印面单并回填发货状态的全流程自动化。

1.1 开发环境配置

首先确保本地已安装Python 3.8及以上版本。为了处理Excel订单数据和发起HTTP请求，我们需要安装pandas、openpyxl和requests库。请在终端或命令行中直接执行以下命令：

```bash pip install pandas openpyxl requests ```

1.2 快递API账号申请

本教程以快递100（Kuaidi100）为例，因为它支持主流快递公司的电子面单接口。访问https://www.kuaidi100.com/openapi/注册企业版账号。注册完成后，进入控制台获取customer（客户ID）和key（API密钥）。同时，需要在控制台开通“电子面单”服务权限，并绑定你的打印机（推荐使用云打印机或安装本地CUPS打印服务）。

二、数据准备：订单Excel模板规范

为了实现批量处理，我们需要将直播后台导出的订单整理为标准Excel格式。请在项目目录下创建一个名为orders.xlsx的文件，并严格按照以下表头设置第一行：

• order_id：订单编号（用于回填状态）
• receiver_name：收件人姓名
• receiver_phone：收件人电话
• receiver_address：收件人完整地址
• sku_name：商品名称
• weight：包裹重量（单位：KG，用于计算运费）

注意：地址字段不要省略省市区，API通常会根据完整地址自动匹配网点。

三、核心代码实现：API封装与逻辑处理

在项目目录下创建shipping_tool.py，我们将编写所有逻辑。代码分为配置部分、API请求封装部分和主循环部分。

3.1 基础配置与签名生成

在代码顶部，填入你申请到的API信息以及发货人的固定信息（即你的仓库地址）。

```python import requests import pandas as pd import hashlib import json import base64 import os import time 配置区域 API_CONFIG = { 'customer': '你的CustomerID', 替换为真实ID 'key': '你的APIKey', 替换为真实Key 'secret': '你的SecretKey', 如果有Secret请填入，部分接口仅用Key 'url': 'https://poll.kuaidi100.com/eorderapi.do' 电子面单标准接口 } SENDER_INFO = { 'name': '发货人姓名', 'mobile': '发货人手机号', 'province': '广东省', 'city': '深圳市', 'district': '南山区', 'address': '具体街道门牌号', 'company': '店铺名称' } 打印机设置，Windows下留空使用默认打印机 PRINTER_NAME = None ```

3.2 电子面单请求函数

该函数负责组装符合快递100规范的JSON数据，并发送POST请求。这里处理了参数签名和数据加密逻辑。

```python def get_waybill(order_data,快递公司编码): """ 请求电子面单接口 :param order_data: 单行订单数据 :param 快递公司编码: 如 'sf' (顺丰), 'yt' (圆通), 'zto' (中通) :return: 运单号和面单图片数据 """ param = { "cargo": order_data['sku_name'], "count": 1, "encode": "utf-8", "funcNo": "1002", 固定功能号 "partnerId": API_CONFIG['customer'], "partnerKey": API_CONFIG['key'], "phone": order_data['receiver_phone'], "printType": "IMAGE", 返回图片格式 "remark": "直播自动发货", "sender": SENDER_INFO, "receiver": { "name": order_data['receiver_name'], "mobile": order_data['receiver_phone'], "address": order_data['receiver_address'] }, "tempId": "0", 模板ID，通常在快递后台配置后填入 "weight": order_data['weight'] } 将参数转换为JSON字符串并进行URL编码或特定加密处理 注意：不同快递商接口细节略有不同，此处以通用逻辑为例 实际生产中需严格参照快递100最新文档的sign生成方式 request_data = { 'param': json.dumps(param), 'sign': hashlib.md5((json.dumps(param) + API_CONFIG['key']).encode('utf-8')).hexdigest(), 'customer': API_CONFIG['customer'] } try: response = requests.post(API_CONFIG['url'], data=request_data, timeout=10) result = response.json() if result.get('success') == True: 解析返回数据 waybill_no = result['data']['kuaidiNum'] 面单图片通常是base64编码 label_img_base64 = result['data']['label'] return waybill_no, label_img_base64 else: print(f"订单 {order_data['order_id']} 请求失败: {result.get('message')}") return None, None except Exception as e: print(f"网络请求异常: {e}") return None, None ```

3.3 本地打印与文件保存

获取到Base64格式的面单图片后，需要将其解码为PDF或图片文件，并调用系统命令进行打印。

```python def save_and_print_label(img_base64, order_id): """ 将Base64图片保存为本地文件并打印 """ 创建output目录 if not os.path.exists('output'): os.makedirs('output') file_path = f"output/{order_id}.png" try: 解码并保存图片 img_data = base64.b64decode(img_base64) with open(file_path, 'wb') as f: f.write(img_data) print(f"面单已保存: {file_path}") 调用系统打印命令 if os.name == 'nt': Windows系统 os.startfile(file_path, "print") else: macOS 或 Linux 假设使用lpr命令，需提前安装cups cmd = f"lpr -P {PRINTER_NAME} {file_path}" if PRINTER_NAME else f"lpr {file_path}" os.system(cmd) print(f"已发送打印指令: {order_id}") return True except Exception as e: print(f"打印失败: {e}") return False ```

四、主程序入口：批量处理逻辑

编写主函数读取Excel，遍历每一行进行发货，并生成结果报表。

```python def main(): input_file = 'orders.xlsx' output_file = 'shipping_result.xlsx' 读取Excel try: df = pd.read_excel(input_file) print(f"成功读取 {len(df)} 条订单，开始处理...") except FileNotFoundError: print(f"未找到文件: {input_file}") return 初始化结果列 df['logistics_no'] = '' 运单号 df['status'] = '' 处理状态 假设默认使用顺丰发货，实际可根据SKU列判断快递商 default_express_code = 'sf' for index, row in df.iterrows(): order_id = row['order_id'] print(f"正在处理订单: {order_id} ...") 1. 获取电子面单 waybill_no, label_img = get_waybill(row, default_express_code) if waybill_no and label_img: 2. 打印面单 print_success = save_and_print_label(label_img, order_id) if print_success: df.at[index, 'logistics_no'] = waybill_no df.at[index, 'status'] = '已发货' TODO: 在此处添加调用直播平台API回填发货状态的代码 update_platform_status(order_id, waybill_no) else: df.at[index, 'status'] = '打印失败' else: df.at[index, 'status'] = '面单申请失败' 避免请求过快触发限流 time.sleep(0.5) 保存结果 df.to_excel(output_file, index=False) print(f"处理完成！结果已保存至 {output_file}") if __name__ == "__main__": main() ```

五、操作步骤与注意事项

5.1 运行脚本

将上述代码完整复制到shipping_tool.py中，并将orders.xlsx放在同级目录。在终端运行：

```bash python shipping_tool.py ```

5.2 常见错误排查

• 签名错误：请检查API_CONFIG中的Key是否正确，且MD5加密逻辑是否与快递官方文档完全一致。部分新接口可能使用SHA256。
• 打印无反应：Windows系统下确保os.startfile关联了默认图片查看器且该查看器支持打印快捷键。Linux/Mac用户需确保已安装cups并配置了打印机。
• 地址解析失败：检查Excel中的地址是否包含省市区，如果地址过于简略，快递API无法分配正确的网点，会导致返回1001错误。

5.3 进阶优化建议

目前的脚本使用单线程顺序执行。如果直播订单量瞬间激增（如几千单），建议使用concurrent.futures.ThreadPoolExecutor进行多线程并发请求，将打印任务放入队列中异步执行，以大幅提升处理速度。同时，务必在代码中加入异常重试机制，避免因网络抖动导致单条订单失败而中断整批任务。