17TRACK包裹追踪

技能简介

该技能通过17TRACK API v2.2接口，在本地维护包裹列表并跟踪物流状态变化。数据存储于工作区下的SQLite数据库，支持轮询同步与可选的Webhook推送两种更新方式。

业务背景

跨境电商与供应链团队需实时掌握多平台订单物流动态，传统人工查询效率低下且易遗漏异常。本工具在本地建立包裹数据库，通过API对接与Webhook推送双通道更新，将分散的物流信息聚合为可管理的资产，支撑库存调度与客户服务决策。

落地案例：某进口贸易商使用本工具管理日均200+国际包裹：运营人员执行添加命令录入单号及商品标签，系统自动识别承运商并写入SQLite数据库；后台轮询任务每6小时同步轨迹，遇清关延误或派送异常时自动触发通知。技术团队配置Webhook接收17TRACK主动推送，减少无效API调用以控制配额消耗，财务月末导出数据核对物流成本。

能做什么

• 注册并存储多个物流单号到本地数据库
• 自动识别或手动指定承运商代码
• 轮询获取最新物流轨迹
• 接收并处理17TRACK主动推送的Webhook更新
• 标记已送达、派送中、异常扣关等关键状态
• 管理追踪启停与本地数据清理

使用说明

环境准备

1. 从17TRACK官网获取API Token
2. 设置环境变量：export TRACK17_TOKEN=your_token_here
3. 确认系统已安装Python 3

安装指令

# 初始化数据存储（可重复执行）
python3 {baseDir}/scripts/track17.py init

基础操作

1. 添加包裹：python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "商品名称"（若自动识别承运商失败，追加--carrier 3011指定代码）
2. 查看列表：python3 {baseDir}/scripts/track17.py list
3. 同步更新：python3 {baseDir}/scripts/track17.py sync
4. 查询详情：python3 {baseDir}/scripts/track17.py status 1或status "单号"

Webhook部署（可选）

1. 启动服务：python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789
2. 配置17TRACK后台指向该地址（建议配合反向代理）
3. 或离线处理：cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook

其他命令：停止追踪stop、恢复追踪retrack、删除本地记录remove、查看API配额quota

输入与输出

见下方输入与输出表格。

风险提示

• TRACK17_TOKEN等敏感信息切勿明文暴露于日志或对话中
• Webhook服务直接暴露公网存在请求伪造风险，建议通过Tailscale Funnel或Nginx反向代理加固
• SQLite文件默认存放于工作区packages目录，多实例并发访问可能产生锁冲突
• 免费API额度有限，高频轮询易触发限流
• 承运商代码需查阅17TRACK文档，错误代码会导致追踪失败

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/tristanmanchester/track17/SKILL.md
来源类型：GitHub仓库