快递订单与物流轨迹 API

打印组件下单出纸后，把运单报到这里。ERP 用商家订单号回填物流单号；用户只有电话时，用轨迹接口查物流节点。

根地址　https://api.py99999.com
鉴权　请求头 X-Print-Token = 打印组件「API配置 → 服务」里的 Token（至少 16 位）
探测　/health 无需令牌；业务接口无令牌返回 401
看板　/kd/ 按日列出已打印运单号、电话、地区

1. 怎么取订单

优先用下单时的商家订单号（ERP 的 orderId / ts）：

GET https://api.py99999.com/api/express/orders?orderId=EO0051908345227
X-Print-Token: 你的令牌

按收件手机：

GET https://api.py99999.com/api/express/prints?phone=13800138000
X-Print-Token: 你的令牌

最近一条 / 按运单号：

GET https://api.py99999.com/api/express/orders/latest
GET https://api.py99999.com/api/express/orders/JDVC38937527156

2. 查询参数

参数说明
orderId / order_id / customerOrderId / ts商家订单号（传给京东下单的那个）
phone / mobile / customer_phone收件手机，忽略横线空格，可后 11 位
waybill / waybillCode京东运单号，支持包含匹配
name / customer_name收件人姓名包含
limit条数，默认 50，最多 200

别名路径：/api/express/prints、/api/express/waybills，行为相同。

3. 成功响应

HTTP 200，code = 0。ERP 回填取 items[].waybillCode（物流单号）、phone（电话）、receiverAddress（地区/地址）。

{
  "code": 0,
  "count": 1,
  "source": "cloud",
  "items": [
    {
      "phone": "13800138000",
      "waybillCode": "JDVC38937527156",
      "receiverName": "张三",
      "receiverAddress": "四川省达州市大竹县金利多东湖苑",
      "cargoName": "1. 5D  手串  4.43",
      "remark": "",
      "status": "已入队打印",
      "createdAt": "2026-10-30T16:20:17+08:00",
      "printedAt": "2026-10-30T16:20:19+08:00",
      "jobId": "...",
      "printer": "HPRT N31",
      "carrier": "jdl",
      "orderId": "EO0051908345227",
      "trace": "erp-pull → HPRT N31"
    }
  ]
}

4. 字段说明

字段含义
phone收件手机
waybillCode京东物流单号（回填 ERP）
receiverName收件人
receiverAddress收件地区/详细地址
orderId商家订单号
cargoName货品摘要
status本机状态，如已入队打印
createdAt / printedAt下单 / 出纸时间

按运单号查且没有记录时返回 HTTP 404。令牌错误返回 401 {"error":"unauthorized"}。

5. 按手机号查物流轨迹

京东标准轨迹按运单号查询。本接口先用手机号对上已出运单，再返回京东轨迹节点（nodes）。

GET https://api.py99999.com/api/express/trace?phone=13800138000
X-Print-Token: 你的令牌
{
  "code": 0,
  "count": 1,
  "source": "cloud",
  "items": [
    {
      "phone": "13800138000",
      "waybillCode": "JDVC38937527156",
      "receiverName": "张三",
      "receiverAddress": "四川省达州市大竹县金利多东湖苑",
      "status": "运输中",
      "trace": "运输中",
      "nodes": [
        { "time": "2026-10-30 10:00:00", "description": "已揽收", "operator": "大竹营业部" },
        { "time": "2026-10-30 12:00:00", "description": "运输中", "operator": "成都分拨" }
      ]
    }
  ]
}

ERP 展示取 items[].nodes[] 的 time / description。没有运单返回 HTTP 404。别名 /api/express/tracking。刚出纸时节点可能为空，打印电脑会定时向京东刷新后上报。

curl

curl -s "https://api.py99999.com/api/express/trace?phone=13800138000" ^
  -H "X-Print-Token: 你的令牌"

JavaScript

const r = await fetch(
  "https://api.py99999.com/api/express/trace?phone=" + encodeURIComponent(phone),
  { headers: { "X-Print-Token": token } }
);
const data = await r.json();
const nodes = data.items?.[0]?.nodes || [];

PHP

$ch = curl_init("https://api.py99999.com/api/express/trace?phone=" . urlencode($phone));
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-Print-Token: " . $token],
]);
$data = json_decode(curl_exec($ch), true);
$nodes = $data["items"][0]["nodes"] ?? [];

6. 调用示例（回填运单号）

curl

curl -s "https://api.py99999.com/api/express/orders?orderId=EO0051908345227" ^
  -H "X-Print-Token: 你的令牌"

JavaScript

const r = await fetch(
  "https://api.py99999.com/api/express/orders?orderId=" + encodeURIComponent(orderId),
  { headers: { "X-Print-Token": token } }
);
const data = await r.json();
const waybill = data.items?.[0]?.waybillCode;
const phone = data.items?.[0]?.phone;
const address = data.items?.[0]?.receiverAddress;

PHP

$ch = curl_init("https://api.py99999.com/api/express/orders?orderId=" . urlencode($orderId));
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-Print-Token: " . $token],
]);
$data = json_decode(curl_exec($ch), true);
$waybill = $data["items"][0]["waybillCode"] ?? "";

7. 注意

完整说明见 打印组件 API.md。