京东物流API鉴权必须用SHA256签名（非MD5或HMAC-SHA256），需按字典序拼接含app_key、timestamp等参数的字符串，app_secret前置后HMAC-SHA256加密并转大写；查轨迹须同时传logisticCode和京东标准carrierCode；电子面单地址须用京东行政区编码且address不含行政字样；PHP调用需严格JSON格式及Content-Type头。
京东物流 API 的鉴权方式必须用 sha256 签名，不是 md5 或 HMAC-SHA256
京东物流开放平台强制要求所有请求使用 sha256 + app_key + app_secret + 请求参数（按字典序拼接）生成签名，签名字段叫 sign。很多人直接套用其他平台习惯，用 md5 或丢掉参数排序，结果一直返回 "code":40001,"msg":"签名错误"。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 所有请求参数（含
method、app_key、timestamp、业务参数等）必须先去除空值，再按 key 字典序升序排列，拼成key1=value1&key2=value2形式 -
app_secret拼在最前面，整体做hash_hmac('sha256', $string, $app_secret)—— 注意不是sha256($string . $app_secret) - 签名结果转大写十六进制字符串，填入
sign参数 - 时间戳
timestamp必须是毫秒级（round(microtime(true) * 1000)），且与京东服务器时间差不能超 5 分钟
查快递轨迹用 jdl.open.trace.query，但必须传 logisticCode 和 carrierCode
京东物流不接受单靠运单号查询，必须同时提供承运商编码。常见错误是只传 logisticCode（如 “JDVA202405123456789”），结果返回 "code":40004,"msg":"参数缺失" 或轨迹为空。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
-
carrierCode是京东定义的承运商代码，不是快递公司全称，例如：京东物流是JDL，中通是ZTO，圆通是YTO，申通是STO—— 这些必须从京东后台「承运商管理」或文档附录查，不能猜 - 如果不知道承运商，可先调
jdl.open.logistics.query（需订单号+商家订单号）反查，但该接口权限需单独申请 - 轨迹返回的
data.traceList是倒序（最新状态在前），注意别直接取[0]当最新节点，要按ftime排序 - 部分物流单号在京东系统里可能延迟同步，查不到时别急着重试，等 2–3 分钟再查
申请电子面单必须先调 jdl.open.waybill.apply，且 sender/receiver 字段校验极严
面单申请失败最常见的原因是地址字段格式不对：京东要求 province、city、county 必须用京东标准行政区编码（不是高德/百度的），且 address 不能含“省”“市”“区”字样，否则返回 "code":40012,"msg":"收件人地址不合法"。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 行政区划必须调京东的
jdl.open.area.get接口查编码，比如“北京市朝阳区”对应province=110000、city=110100、county=110105 -
address字段只留街道门牌（如 “建国路8号SOHO现代城C座1201”），删掉所有“北京市”“朝阳区”等前缀 - 联系人手机号必须带
+86前缀，固话要带区号（如+86-010-XXXXXXX），否则验签通过但面单生成失败 - 面单申请成功后，
waybillCode是实际运单号，printUrl是 PDF 面单直链 —— 该链接 24 小时内有效，过期需重新申请
PHP cURL 调用时必须设 Content-Type: application/json，且 json_encode 后不能手动加引号
京东所有开放 API 都要求 POST 请求体为 raw JSON，但很多 PHP 同学用 http_build_query 或给 json_encode() 结果再套一层 "，导致报错 "code":40003,"msg":"JSON解析失败"。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE))，不要json_encode(json_encode($data)) - 必须显式设置 header：
['Content-Type: application/json', 'Accept: application/json']，缺一不可 - 京东接口响应一定是 JSON，但某些网络环境会返回空响应或 502，建议加
curl_setopt($ch, CURLOPT_FAILONERROR, true)并捕获curl_error($ch) - 生产环境务必加
timeout（推荐CURLOPT_TIMEOUT => 15），京东偶发响应慢，卡死会导致整个订单流程阻塞
最麻烦的其实是承运商映射和地址标准化——这两个点没对齐，后面所有接口都会反复失败，而且错误提示很模糊。别跳过这步。
