# 第 1 步：连通性测试（免签名，仅运车 / 运宠域提供）
curl "https://yunxijuchuang.com/openapi/v2/car/ping"

# 第 2 步：真实业务请求（需 4 个鉴权头，签名算法见「签名算法」章节）
curl -X POST "https://yunxijuchuang.com/openapi/v2/express/price" \
  -H "Content-Type: application/json" \
  -H "X-App-Key: $APP_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE" \
  -d '{"from_city":"昆明市","to_city":"杭州市","weight":1.5}'

# 1) 连接测试（免签名，仅运车 / 运宠域提供）
curl "https://yunxijuchuang.com/openapi/v2/car/ping"

# 2) 真实业务请求（需 4 个鉴权头 + JSON body）
curl -X POST "https://yunxijuchuang.com/openapi/v2/express/price" \
  -H "Content-Type: application/json" \
  -H "X-App-Key: ak_8a20c0a00cce4d17" \
  -H "X-Timestamp: 1757824000" \
  -H "X-Nonce: A9B2C30E4F56" \
  -H "X-Signature: 7F3A9C..." \
  -d '{"from_city":"昆明市","to_city":"杭州市","weight":1.5}'

{ "code": 0, "message": "success", "request_id": "...",
  "data": { "service": "openapi-v2", "domain": "car", "time": "2026-09-14 15:10:31", "version": "v2" } }

// ① 成功（HTTP 200）
{ "code": 0, "message": "success", "request_id": "7c1a9f2e-0b41-4d55-9a1c-2f8e6b3d0451", "data": { ... } }

// ② 业务失败（HTTP 仍为 200，code 区分）
{ "code": 1008, "message": "未找到路线价格: 昆明市 → 拉萨市 (typeid=3)，请联系运营配置价格", "request_id": "...", "data": null }

// ③ 参数校验失败（HTTP 仍为 200）
{ "code": 422, "message": "参数验证失败", "request_id": "...",
  "data": { "errors": { "weight": ["重量必须大于 0.01"] } } }

// HTTP 429
{ "code": 429,
  "message": "超过接口调用限制（express.order/create 30 次/秒）",
  "request_id": "...",
  "data": null }

<?php
// 1. 请求体：键递归升序 ksort 后 JSON（不转义中文与斜杠）
$body = ['merchant_order_no' => 'YT20260914000001', 'channel_code' => '100057', 'weight' => 1.5];
ksort($body);
$bodyJson = json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// 2. 签名串 = app_key + timestamp + nonce + body_json（v2 含 nonce）
$appKey    = 'ak_8a20c0a00cce4d17';                   // 平台分配
$appSecret = 'sk_****************';                  // 平台分配，仅创建时展示一次
$timestamp = time();                                    // Unix 秒
$nonce     = bin2hex(random_bytes(8));                  // 随机串，长度 ≤ 64
$signStr   = $appKey . $timestamp . $nonce . $bodyJson;

// 3. HMAC-SHA256 → 大写十六进制
$sign = strtoupper(hash_hmac('sha256', $signStr, $appSecret));

// 4. 发送：Header 携带 4 个鉴权参数，Body 为 $bodyJson
//    X-App-Key: $appKey  X-Timestamp: $timestamp  X-Nonce: $nonce  X-Signature: $sign

import hmac, hashlib, json, time, secrets
body = {"merchant_order_no": "YT20260914000001", "channel_code": "100057", "weight": 1.5}
body_json = json.dumps(body, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
timestamp = int(time.time())
nonce     = secrets.token_hex(8)   # 随机串，长度 ≤ 64
sign_str  = f"{app_key}{timestamp}{nonce}{body_json}"
sign = hmac.new(app_secret.encode(), sign_str.encode(), hashlib.sha256).hexdigest().upper()
# headers = {"X-App-Key": app_key, "X-Timestamp": str(timestamp), "X-Nonce": nonce, "X-Signature": sign}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(appSecret.getBytes(UTF_8), "HmacSHA256"));
// signStr = appKey + timestamp + nonce + bodyJson（UTF-8，不转义中文与斜杠）
String signature = Hex.encodeHexString(mac.doFinal(signStr.getBytes(UTF_8))).toUpperCase();

const crypto = require('crypto')

// 1. 请求体：键「递归升序」后再 JSON。
//    ⚠️ Node 的 JSON.stringify 不排序键（PHP 有 ksort、Python 有 sort_keys），
//       必须自己递归排序，否则签名串与平台不一致 → 一律 401 验签失败。
const sortDeep = (v) => Array.isArray(v) ? v.map(sortDeep)
  : (v && typeof v === 'object'
      ? Object.keys(v).sort().reduce((o, k) => (o[k] = sortDeep(v[k]), o), {})
      : v)
const body = { merchant_order_no: 'YT20260914000001', channel_code: '100057', weight: 1.5 }
const bodyJson = JSON.stringify(sortDeep(body))   // 默认不转义中文与斜杠

// 2. 签名串 = app_key + timestamp + nonce + body_json（v2 含 nonce；四段首尾直连、无分隔符）
const appKey = 'ak_8a20c0a00cce4d17'        // 平台分配
const appSecret = 'sk_****************'       // 平台分配，仅创建时展示一次
const timestamp = Math.floor(Date.now() / 1000)   // Unix 秒（勿用毫秒）
const nonce = crypto.randomBytes(8).toString('hex')  // 随机串，长度 ≤ 64
const signStr = `${appKey}${timestamp}${nonce}${bodyJson}`

// 3. HMAC-SHA256 → 大写十六进制
const sign = crypto.createHmac('sha256', appSecret)
  .update(signStr, 'utf8').digest('hex').toUpperCase()

// 4. 发送：Header 携带 X-App-Key / X-Timestamp / X-Nonce / X-Signature，Body 用 bodyJson

{
  "code": 0,
  "message": "success",
  "request_id": "7c1a9f2e-0b41-4d55-9a1c-2f8e6b3d0451",
  "data": {
    "total": 2,
    "sandbox": false,
    "quotes": [
      {
        "quote_no": "QUO20260914103000123",
        "channel_id": 2001, "channel_code": "100057",
        "platform_company_code": "SFSY", "platform_company_name": "顺丰速运",
        "platform_product_code": "SFSY-KD-01", "platform_product_name": "顺丰标快",
        "platform_channel_code": "100057", "platform_channel_name": "顺丰速运-标准渠道",
        "biz_type": "express", "settlement_mode": "online", "payment_type": "MONTH",
        "freight": 12.80, "insurance_fee": 3.00, "other_fee": 0, "total_fee": 15.80, "original_price": 18.00,
        "light_goods": 6000, "calc_fee_type": "discount", "supports_payment_confirm": true
      },
      {
        "quote_no": "QUO20260914103000456",
        "channel_id": 2010, "channel_code": "100112",
        "platform_company_code": "YTOD", "platform_company_name": "圆通速递",
        "platform_product_code": "YTOD-KD-01", "platform_product_name": "圆通标快",
        "platform_channel_code": "100112", "platform_channel_name": "圆通速递-电商特惠",
        "biz_type": "express", "settlement_mode": "online", "payment_type": "MONTH",
        "freight": 9.80, "insurance_fee": 0, "other_fee": 0, "total_fee": 9.80, "original_price": 12.00,
        "light_goods": 6000, "calc_fee_type": "ladder", "supports_payment_confirm": false
      }
    ]
  }
}

{
  "event_id": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "event": "express.status.changed",
  "timestamp": 1757824000,
  "order_no": "YT20260914000001",
  "merchant_order_no": "SHOP20260914001",
  "waybill_no": "SF1234567890",
  "status": "transit",
  "data": { "status_text": "运输中", "event_time": "2026-09-14 15:30:00" }
}

<?php
// 1) 原始 body → 数组（关键：必须重新编码，不能直接签名原字符串）
$raw     = file_get_contents('php://input');
$payload = json_decode($raw, true) ?: [];

// 2) 递归 ksort（与平台一致：字符串序）
$sort = function (array &$arr) use (&$sort) {
    ksort($arr, SORT_STRING);
    foreach ($arr as &$v) { if (is_array($v)) $sort($v); }
};
$sort($payload);
$bodyJson = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// 3) 构造 canonical 并计算签名
$appKey    = $_SERVER['HTTP_X_APP_KEY']   ?? '';
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$nonce     = $_SERVER['HTTP_X_NONCE']     ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$mySign    = strtoupper(hash_hmac('sha256', $appKey . $timestamp . $nonce . $bodyJson, $appSecret));

// 4) 恒定时间比较 + 时间戳容差
if (!hash_equals($mySign, $signature)) { http_response_code(401); exit('invalid signature'); }
if (abs(time() - (int) $timestamp) > 300)  { http_response_code(401); exit('expired'); }

// 5) 幂等：event_id 去重（缓存 / 唯一索引，TTL 建议 ≥ 7 天）
$eventId = $payload['event_id'] ?? '';
if (!$eventId || Cache::has('hook:' . $eventId)) { echo 'ok'; exit; }
Cache::put('hook:' . $eventId, 1, 86400 * 7);

// 6) 先落库、后异步处理，确保 15 秒内返回
dispatch(new HandleOpenApiEvent($payload));
http_response_code(200);
echo 'success';

canonical = app_key + timestamp + nonce + body_json
// body_json：请求体 JSON（键递归升序 ksort、不转义中文与斜杠）
signature = strtoupper(hash_hmac('sha256', canonical, app_secret))
// 示例
// app_key=ak_8a20c0a00cce4d17, timestamp=1757824000, nonce=A9B2C30E4F56
// signature=7F3A9C...（64 位大写十六进制）

{ "code": 0, "message": "success", "request_id": "a1b2c3d4-...", "data": { ... } }

// 失败（HTTP 200，业务码区分）
{ "code": 422, "message": "参数验证失败", "request_id": "a1b2c3d4-...", "data": { "errors": { "weight": ["重量必须大于 0.01"] } } }

{
  "from_province": "云南省", "from_city": "昆明市", "from_district": "盘龙区",
  "from_address": "北京路924号财智心景大厦", "from_name": "王先生", "from_phone": "13800001111",
  "to_province": "浙江省", "to_city": "杭州市", "to_district": "西湖区",
  "to_address": "三墩镇亲亲家园二期", "to_name": "李女士", "to_phone": "13900002222",
  "goods_type": "服装",
  "weight": 1.5,
  "insurance_value": 3000,
  "biz_type": "express",
  "settlement_mode": "online",
  "payment_type": "MONTH"
}

{
  "code": 0, "message": "success", "request_id": "7c1a9f2e-0b41-4d55-9a1c-2f8e6b3d0451",
  "data": {
    "total": 2,
    "sandbox": false,
    "quotes": [
      {
        "quote_no": "QUO20260914103000123",
        "channel_id": 2001, "channel_code": "100057",
        "platform_company_code": "SFSY", "platform_company_name": "顺丰速运",
        "platform_product_code": "SFSY-KD-01", "platform_product_name": "顺丰标快",
        "platform_channel_code": "100057", "platform_channel_name": "顺丰速运-标准渠道",
        "biz_type": "express", "biz_type_label": "express",
        "settlement_mode": "online", "settlement_mode_label": "monthly",
        "shipping_scenario": "standard",
        "payment_type": "MONTH", "payment_type_label": "monthly",
        "supported_pay_types": ["MONTH", "PRESENT"],
        "supports_insurance": true, "supports_cod": false,
        "supports_pickup": true, "supports_sign_return": false,
        "insurance_max_amount": 300000, "insurance_min": 1, "insurance_rate": 0.005,
        "goods_value": 3000, "insurance_fee": 3.00,
        "insurance_tip": "已按物品价值 3000 元申报保价，保价费 3 元，最高可保 300000 元。",
        "visibility": "all", "is_active": true, "remark": "",
        "estimated_days": 2, "delivery_type": "",
        "freight": 12.80, "other_fee": 0, "total_fee": 15.80, "original_price": 18.00,
        "first_weight": 1, "first_weight_price": 12.80,
        "additional_weight": 1, "additional_weight_price": 5.00,
        "weight": 1.5, "volume_weight": 0,
        "min_charge": 0, "max_weight": 60,
        "light_goods": 6000, "calc_fee_type": "discount",
        "supports_payment_confirm": true
      },
      {
        "quote_no": "QUO20260914103000456",
        "channel_id": 2010, "channel_code": "100112",
        "platform_company_code": "YTOD", "platform_company_name": "圆通速递",
        "platform_product_code": "YTOD-KD-01", "platform_product_name": "圆通标快",
        "platform_channel_code": "100112", "platform_channel_name": "圆通速递-电商特惠",
        "biz_type": "express", "settlement_mode": "online", "payment_type": "MONTH",
        "insurance_fee": 0, "goods_value": 0,
        "estimated_days": 2,
        "freight": 9.80, "other_fee": 0, "total_fee": 9.80, "original_price": 12.00,
        "light_goods": 6000, "calc_fee_type": "ladder",
        "supports_payment_confirm": false
      }
    ]
  }
}

{
  "merchant_order_no": "YT20260914000001",
  "channel_code": "100057",
  "biz_type": "express",
  "settlement_mode": "online",
  "payment_type": "MONTH",
  "sender_name": "王先生", "sender_phone": "13800001111",
  "sender_province": "云南省", "sender_city": "昆明市", "sender_district": "盘龙区",
  "sender_address": "北京路924号财智心景大厦1614",
  "receiver_name": "李女士", "receiver_phone": "13900002222",
  "receiver_province": "浙江省", "receiver_city": "杭州市", "receiver_district": "西湖区",
  "receiver_address": "三墩镇亲亲家园二期",
  "goods_name": "服装", "goods_type": "服装",
  "weight": 1.5, "quantity": 1, "insurance_value": 3000,
  "pickup_start_time": "2026-09-15 09:00:00", "pickup_end_time": "2026-09-15 11:00:00",
  "pay_confirm": "Y", "remark": "轻拿轻放"
}

{
  "code": 0,
  "message": "下单成功",
  "request_id": "5a2c8e1b-77d0-4a9c-8f31-9b2e5c7a0112",
  "data": {
    "order_no": "YT2609140000123456",
    "merchant_order_no": "YT20260914000001",
    "waybill_no": "SF1234567890123",
    "sandbox": false,
    "status": "submitted", "status_text": "取件中",
    "biz_type": "express", "payment_type": "MONTH", "settlement_mode": "online",
    "channel": {
      "channel_id": 2001, "channel_code": "100057",
      "company_code": "SFSY", "company_name": "顺丰速运"
    },
    "sender": { "name": "王先生", "phone": "138****1111", "city": "昆明市", "district": "盘龙区", "address": "北京路924号财智心景大厦1614" },
    "receiver": { "name": "李女士", "phone": "139****2222", "city": "杭州市", "district": "西湖区", "address": "三墩镇亲亲家园二期" },
    "goods": { "name": "服装", "type": "服装", "weight": 1.5, "volume": 0, "quantity": 1 },
    "fees": {
      "quote_total_fee": 15.80, "actual_total_fee": null,
      "difference_amount": 0, "difference_status": "none",
      "merchant_prepaid": 15.80, "merchant_actual": 0
    },
    "courier": { "name": "", "phone": "" },
    "times": {
      "created_at": "2026-09-14 10:30:12", "submitted_at": "2026-09-14 10:30:14",
      "pickup_start_time": "2026-09-15 09:00:00", "pickup_end_time": "2026-09-15 11:00:00",
      "signed_at": null, "delivered_at": null, "cancel_reason": ""
    }
  }
}

{
  "code": 0,
  "message": "支付确认发货成功",
  "request_id": "9b2e5c7a-0112-4c8e-9a41-7d3f0b6e2233",
  "data": {
    "order_no": "YT2609140000123456",
    "waybill_no": "SF1234567890123",
    "status": "pending_pickup",
    "status_text": "待揽收（已确认补差）",
    "confirmed": true,
    "sandbox": false
  }
}

{ "merchant_order_no": "YT20260914000001" }

{
  "code": 0, "message": "success", "request_id": "e41c7a90-2b6d-4f8a-9c10-3a5e7d2b6601",
  "data": {
    "order_no": "YT2609140000123456",
    "merchant_order_no": "YT20260914000001",
    "waybill_no": "SF1234567890123",
    "sandbox": false,
    "status": "transit", "status_text": "运输中",
    "biz_type": "express", "payment_type": "MONTH", "settlement_mode": "online",
    "channel": {
      "channel_id": 2001, "channel_code": "100057",
      "company_code": "SFSY", "company_name": "顺丰速运"
    },
    "sender": { "name": "王先生", "phone": "138****1111", "city": "昆明市", "district": "盘龙区", "address": "北京路924号财智心景大厦1614" },
    "receiver": { "name": "李女士", "phone": "139****2222", "city": "杭州市", "district": "西湖区", "address": "三墩镇亲亲家园二期" },
    "goods": { "name": "服装", "type": "服装", "weight": 1.5, "volume": 0, "quantity": 1 },
    "fees": {
      "quote_total_fee": 15.80, "actual_total_fee": 16.20,
      "difference_amount": 0.40, "difference_status": "supplement",
      "merchant_prepaid": 15.80, "merchant_actual": 16.20
    },
    "courier": { "name": "张师傅", "phone": "138****4321" },
    "times": {
      "created_at": "2026-09-14 10:30:12", "submitted_at": "2026-09-14 10:30:14",
      "pickup_start_time": "2026-09-15 09:00:00", "pickup_end_time": "2026-09-15 11:00:00",
      "signed_at": null, "delivered_at": null, "cancel_reason": ""
    }
  }
}

{
  "code": 0,
  "message": "取消成功",
  "request_id": "b7d0e411-8c62-4a3f-9e05-1d4c7a90bb02",
  "data": {
    "order_no": "YT2609140000123456",
    "merchant_order_no": "YT20260914000001",
    "waybill_no": "SF1234567890123",
    "sandbox": false,
    "status": "cancelled", "status_text": "已取消",
    "fees": { "quote_total_fee": 15.80, "actual_total_fee": null, "difference_amount": 0, "difference_status": "none" },
    "times": { "created_at": "2026-09-14 10:30:12", "cancel_reason": "客户临时取消寄件" }
  }
}

{ "waybill_no": "SF1234567890123", "sync": true }

{
  "code": 0, "message": "success", "request_id": "3f9a1c05-6e27-4b18-8d70-2c4f9a3e7755",
  "data": {
    "order_no": "YT2609140000123456",
    "waybill_no": "SF1234567890123",
    "status": "transit",
    "sync": { "success": true, "new_traces": 2, "status": "transit", "request_id": "TR20260915142231" },
    "total": 3,
    "traces": [
      { "trace_time": "2026-09-14 18:05:12", "location": "昆明市盘龙区", "description": "快件已揽收", "status": "已揽收" },
      { "trace_time": "2026-09-14 23:41:08", "location": "昆明转运中心", "description": "已发出，下一站【杭州转运中心】", "status": "运输中" },
      { "trace_time": "2026-09-15 14:22:31", "location": "杭州转运中心", "description": "已到达", "status": "运输中" }
    ]
  }
}

{
  "code": 0, "message": "success", "request_id": "c2e8b740-9f13-4d6a-b5c8-0e7a1f9d3321",
  "data": {
    "order_no": "YT2609140000123456",
    "waybill_no": "SF1234567890123",
    "status": "signed",
    "billed": true,
    "estimated": { "freight_fee": 12.80, "insurance_fee": 3.00, "other_fee": 0, "total_fee": 15.80 },
    "actual":    { "freight_fee": 13.20, "insurance_fee": 3.00, "other_fee": 0, "total_fee": 16.20 },
    "difference": { "amount": 0.40, "status": "supplement" },
    "weight": { "actual_weight": 1.58, "charge_weight": 2.0 },
    "merchant": { "prepaid_fee": 15.80, "actual_fee": 16.20, "difference": 0.40, "freight_fee": 13.20, "insurance_fee": 3.00, "other_fee": 0 },
    "user":     { "prepaid_fee": 18.00, "actual_fee": 18.50, "difference": 0.50, "freight_fee": 15.00, "insurance_fee": 3.50, "other_fee": 0 }
  }
}

{
  "order_no": "YT2609140000123456",
  "content": "外包装破损，内件商品有划痕，请协助处理",
  "images": ["https://cdn.merchant.com/evidence/1.jpg"]
}

{
  "event_id": "8f4d1a2b-0c3e-4f57-9a61-2b7c8d9e0f12",
  "event": "express.status.changed",
  "event_time": "2026-09-18 10:30:00",
  "is_replay": false,
  "seq": 3,
  "order_no": "EXP2026091800000123",
  "waybill_no": "7734567890123",
  "status": "picked_up",
  "status_text": "已取件",
  "channel_code": "100014",
  "channel_name": "STKD-标快-AAAR",
  "company_code": "STKD",
  "company_name": "申通快递",
  "pickup": { "courier_name": "张三", "courier_phone": "138****0000", "pickup_code": "123456", "site_name": "杭州西湖网点" },
  "data": {
    "status_before": "picking_up",
    "status_before_text": "取件中",
    "occurred_at": "2026-09-18 10:28:41",
    "description": "快递员已揽收，运单进入分拣中心"
  }
}

{
  "event_id": "1c7e5b90-4a2d-4e83-b7f1-6d9a3c5e2b44",
  "event": "express.fee.updated",
  "event_time": "2026-09-18 10:36:05",
  "is_replay": false,
  "seq": 4,
  "order_no": "EXP2026091800000123",
  "waybill_no": "7734567890123",
  "status": "picked_up",
  "status_text": "已取件",
  "channel_code": "100014",
  "channel_name": "STKD-标快-AAAR",
  "company_code": "STKD",
  "company_name": "申通快递",
  "pickup": {},
  "data": {
    "fee_type": "overweight",
    "fee_type_text": "超重补收",
    "charge_weight": 2.50,
    "freight_fee": 14.00,
    "insurance_fee": 3.00,
    "other_fee": 0.00,
    "total_fee": 17.00,
    "difference_amount": 1.20,
    "difference_status": "supplement",
    "occurred_at": "2026-09-18 10:35:12"
  }
}

{
  "event_id": "2d9f0a31-5c8b-4a17-9e42-73c1b8d5a960",
  "event": "express.pickup.updated",
  "event_time": "2026-09-18 09:52:11",
  "is_replay": false,
  "seq": 2,
  "order_no": "EXP2026091800000123",
  "waybill_no": "7734567890123",
  "status": "picking_up",
  "status_text": "取件中",
  "channel_code": "100014",
  "channel_name": "STKD-标快-AAAR",
  "company_code": "STKD",
  "company_name": "申通快递",
  "pickup": {
    "courier_name": "张三",
    "courier_phone": "138****0000",
    "pickup_code": "123456",
    "site_name": "杭州西湖网点",
    "pickup_status": "arrived",
    "pickup_status_text": "已上门",
    "estimated_pickup_time": "2026-09-18 10:30:00"
  },
  "data": { "occurred_at": "2026-09-18 09:50:03" }
}

{
  "event_id": "5b3c7e02-9f14-4d68-a0c7-2e8f4b6d1a35",
  "event": "express.order.changed",
  "event_time": "2026-09-18 11:05:20",
  "is_replay": false,
  "seq": 5,
  "order_no": "EXP2026091800000123",
  "waybill_no": "7734567890999",
  "status": "in_transit",
  "status_text": "运输中",
  "channel_code": "100014",
  "channel_name": "STKD-标快-AAAR",
  "company_code": "STKD",
  "company_name": "申通快递",
  "pickup": {},
  "data": {
    "change_type": "waybill_changed",
    "change_type_text": "换单",
    "waybill_no_before": "7734567890123",
    "channel_code_before": "",
    "channel_name_before": "",
    "occurred_at": "2026-09-18 11:03:58"
  }
}

{
  "event_id": "9e1b4d76-2a30-4c85-8f9b-1d7e5a0c3b62",
  "event": "express.trace.updated",
  "event_time": "2026-09-18 14:20:33",
  "is_replay": false,
  "seq": 6,
  "order_no": "EXP2026091800000123",
  "waybill_no": "7734567890123",
  "status": "in_transit",
  "status_text": "运输中",
  "channel_code": "100014",
  "channel_name": "STKD-标快-AAAR",
  "company_code": "STKD",
  "company_name": "申通快递",
  "pickup": {},
  "data": {
    "traces": [
      { "occurred_at": "2026-09-18 11:40:00", "status": "in_transit", "status_text": "运输中", "description": "快件已离开【杭州转运中心】，发往【上海转运中心】", "site_name": "杭州转运中心" },
      { "occurred_at": "2026-09-18 14:18:00", "status": "in_transit", "status_text": "运输中", "description": "快件已到达【上海转运中心】", "site_name": "上海转运中心" }
    ]
  }
}

{
  "event_id": "6a0d2f84-7b91-4e35-bc08-3f5a1d9e7c20",
  "event": "express.workorder.updated",
  "event_time": "2026-09-18 16:02:47",
  "is_replay": false,
  "seq": 7,
  "order_no": "EXP2026091800000123",
  "waybill_no": "7734567890123",
  "status": "in_transit",
  "status_text": "运输中",
  "channel_code": "100014",
  "channel_name": "STKD-标快-AAAR",
  "company_code": "STKD",
  "company_name": "申通快递",
  "pickup": {},
  "data": {
    "work_order_no": "WO20260918000001",
    "work_order_status": "processing",
    "work_order_status_text": "处理中",
    "direction": "service",
    "content": "已反馈网点核实，预计 2 小时内回复",
    "occurred_at": "2026-09-18 16:01:10"
  }
}

<?php
// ① 验签：算法与入站请求签名完全一致（详见「接入指引 → 回调机制与验签」）
$raw     = file_get_contents('php://input');
$payload = json_decode($raw, true) ?: [];

$sort = function (array &$a) use (&$sort) { ksort($a, SORT_STRING); foreach ($a as &$v) { if (is_array($v)) $sort($v); } };
$body = $payload; $sort($body);
$canonical = ($_SERVER['HTTP_X_APP_KEY'] ?? '') . ($_SERVER['HTTP_X_TIMESTAMP'] ?? '') . ($_SERVER['HTTP_X_NONCE'] ?? '')
           . json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
if (!hash_equals(strtoupper(hash_hmac('sha256', $canonical, $appSecret)), $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}

// ② 幂等：按 event_id 去重（本地缓存 / 唯一索引，TTL 建议 ≥ 7 天）
$eventId = $payload['event_id'] ?? '';
if (!$eventId || Cache::has('express:' . $eventId)) { echo 'ok'; exit; }
Cache::put('express:' . $eventId, 1, 86400 * 7);

// ③ 顺序：同一 order_no 内按 seq 升序处理（迟到事件直接忽略）
$orderNo = $payload['order_no'] ?? '';
$seq     = (int) ($payload['seq'] ?? 0);
$maxSeq  = (int) Cache::get('express:seq:' . $orderNo, 0);
if ($seq <= $maxSeq) { echo 'ok'; exit; }            // 迟到的旧事件：忽略
if ($seq > $maxSeq + 1) {                             // seq 跳跃：登记 pending，或用「订单查询」兜底
    // Cache::put('express:pending:' . $orderNo . ':' . $seq, $payload, 3600);
}
Cache::put('express:seq:' . $orderNo, $seq, 86400 * 7);

// ④ 先落库、后异步处理，15 秒内返回 2xx
dispatch(new HandleExpressEvent($payload, (bool) ($payload['is_replay'] ?? false)));
http_response_code(200);
echo 'success';

# 方式一（推荐）：在开放平台控制台「推送监控」中，按订单号 / 时间范围 / 事件类型触发「补推」，
#   即可收到 is_replay=true 的真实报文，用于验证验签、幂等与顺序处理逻辑。

# 方式二：用 cURL 模拟一次回调请求（签名需按 canonical 规则自行计算）
curl -X POST "https://your-domain.com/webhook/express" \
  -H "Content-Type: application/json" \
  -H "X-App-Key: {app_key}" -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}" -H "X-Signature: {signature}" \
  -H "X-Request-Id: 8f4d1a2b-0c3e-4f57-9a61-2b7c8d9e0f12" \
  -d '{ "event_id": "8f4d1a2b-0c3e-4f57-9a61-2b7c8d9e0f12", "event": "express.status.changed", "seq": 3, "order_no": "EXP2026091800000123", "status": "picked_up", "status_text": "已取件" }'

// 推荐返回
{ "success": true }

// 注意：平台仅校验 HTTP 状态码（2xx），非 2xx 或超时会触发重试直至死信

{ "code": 0, "message": "success", "request_id": "...",
  "data": { "service": "openapi-v2", "domain": "car", "time": "2026-09-14 12:10:31", "version": "v2" } }

{
  "code": 0, "message": "success", "request_id": "a1b2c3d4-1111-4a2b-9c3d-4e5f60718293",
  "data": {
    "quote_id": "Q20260914121031A1B2C3D4",
    "expire_time": "2026-09-14 12:15:31",
    "query_time": "2026-09-14 12:10:31",
    "category": { "category_id": 1, "category_name": "轿车", "type_id": 11, "type_name": "小型轿车" },
    "route": {
      "from_province": "云南省", "from_city": "昆明市", "from_district": "盘龙区",
      "to_province": "广东省", "to_city": "深圳市", "to_district": "南山区",
      "transit_time": "2-3天"
    },
    "price": {
      "base_price": 1260.00, "original_price": 1800.00,
      "discount_rate": 0.7, "discount_text": "7折", "discount_amount": 540.00,
      "wood_frame_fee": 200.00, "delivery_fee": 300.00,
      "total_price": 1760.00, "original_total": 2300.00
    },
    "price_detail": {
      "base_price_source": "city_price", "discount_source": "merchant_levels",
      "discount_note": "只有基础运费打折，增值费不打折", "merchant_level_id": 3, "channel_type_id": null
    },
    "options": {
      "packing_method": [{ "value": 1, "name": "木架包装", "fee": 200 }, { "value": 0, "name": "无", "fee": 0 }],
      "delivery_type": [{ "value": 1, "name": "送货上门", "fee": 300 }, { "value": 2, "name": "网点自提", "fee": 0 }],
      "has_other_items": [{ "value": 1, "name": "有" }, { "value": 0, "name": "无" }]
    }
  }
}

{
  "code": 0, "message": "success", "request_id": "b7d0e411-8c62-4a3f-9e05-1d4c7a90bb02",
  "data": {
    "order_no": "YT202609141215337421",
    "merchant_order_no": "MY202609140001",
    "order_status": "waiting_pay", "payment_status": "unpaid",
    "paid_amount": 0, "need_pay_amount": 1760.00,
    "is_test": false,
    "price": { "base_price": 1260.00, "original_price": 1800.00, "discount_rate": 0.7, "packing_fee": 200.00, "delivery_fee": 300.00, "total_price": 1760.00 },
    "category": { "category_id": 1, "category_name": "轿车", "type_id": 11, "type_name": "小型轿车" },
    "appointment_time": "2026-09-15 09:00",
    "created_at": "2026-09-14 12:15:33"
  }
}

{
  "code": 0, "message": "success",
  "data": {
    "order_no": "YT202609141215337421", "transport_no": "YTWL202609141216083190",
    "order_status": "paid", "payment_status": "paid", "payment_method": "balance",
    "paid_amount": 1760.00, "payment_time": "2026-09-14 12:16:08", "balance_after": 28240.00
  }
}

{
  "code": 0, "message": "success",
  "data": {
    "order_no": "YT202609141215337421",
    "order_status": "cancelled",
    "cancel_time": "2026-09-14 13:02:11",
    "cancel_reason": "客户临时取消",
    "empty_run_fee": 200.00,
    "paid_amount": 1760.00,
    "refund_amount": 1560.00,
    "refund_status": "refunded"
  }
}

{
  "code": 0, "message": "success",
  "data": {
    "order_no": "YT202609141215337421", "pay_amount": 300.00,
    "paid_amount": 300.00, "remaining_amount": 120.00,
    "payment_status": "partial", "pay_method": "balance",
    "paid_at": "2026-09-14 13:20:05", "balance_after": 27940.00,
    "message": "部分支付成功，仍待付: ¥120.00"
  }
}