调用顺丰丰桥API必须使用access_token鉴权，通过/client_id、client_secret调/auth/token获取；addWaybill接口字段校验严格，需注意phone、weight等格式；签名须对各value单独urlencode后拼接再sha256+hmac；回执操作必须使用waybill_no而非waybill_code。
调用顺丰丰桥 API 前必须确认的鉴权方式
丰桥 API 不接受直接传 app_key + app_secret，必须用 access_token（有效期 2 小时），且该 token 需通过 /auth/token 接口用 client_id、client_secret 和 grant_type=client_credentials 换取。很多人卡在这步，因为文档里把“丰桥开放平台”的 client_id 和旧版“丰巢”或“丰运”的账号混为一谈——它们不通用。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 登录 丰桥开放平台，在「应用管理」里确认你创建的是「电子运单」类应用，且已通过审核
-
client_id和client_secret只在首次创建应用时显示一次，务必存好，后台不再展示明文 - 别用 cURL 直接拼 JSON body 发 token 请求——PHP 的
http_build_query()会自动 urlencode，但丰桥要求Content-Type: application/x-www-form-urlencoded，且参数不能嵌套
创建电子运单：注意 addWaybill 接口的必填字段和格式陷阱
丰桥的 addWaybill 接口（POST /waybill/add）对字段校验极严，常见失败不是签名错，而是字段缺失或类型不符。比如 receiver.phone 必须是 11 位纯数字，带“-”或“+86”直接报错；weight 必须是整数（单位克），传 1.5 或字符串 "1500" 都被拒。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 发件人/收件人地址必须拆成
province、city、district、detail四个字段，不能只填address（旧版接口允许，丰桥不行） -
pay_method填1（寄付）或2（到付），填字符串"1"会失败——接口实际校验的是 int 类型 - 测试时先用
is_test=1参数，否则真实下单后无法撤回，且测试单不产生费用
签名生成必须严格按丰桥规则，PHP 容易漏掉 URL 编码环节
丰桥要求对所有请求参数（含 access_token）做字典序排序后，拼接成 key1=value1&key2=value2 字符串，再用 sha256 + client_secret 签名。PHP 开发者常踩的坑是：用 http_build_query() 拼参后直接 hash，但该函数对中文和特殊字符做了 urlencode，而丰桥要求「值本身要 URL 编码，但拼接前不能重复编码」——即每个 value 要先 urlencode()，再拼 &，再 hash_hmac('sha256', $str, $client_secret)。
示例关键片段：
$params = [
'app_key' => $app_key,
'timestamp' => time(),
'format' => 'json',
'v' => '1.0',
'access_token' => $access_token,
// ...其他业务参数
];
// 先对每个 value 单独 urlencode
$encoded_params = [];
foreach ($params as $k => $v) {
$encoded_params[$k] = is_string($v) ? urlencode($v) : $v;
}
ksort($encoded_params);
$str_to_sign = http_build_query($encoded_params, '', '&', PHP_QUERY_RFC3986);
$sign = hash_hmac('sha256', $str_to_sign, $client_secret);
获取回执时别依赖响应里的 waybill_code，要用 waybill_no
调用 addWaybill 成功后，返回的 JSON 里有 waybill_code 和 waybill_no 两个字段。前者是丰桥内部单号（类似 UUID），后者才是快递员扫码、物流跟踪、客户查单用的真实运单号（12 位数字）。很多开发者误把 waybill_code 当作回执凭证去调 /waybill/print 或查物流，结果一直 404。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 保存回执必须存
waybill_no，它才是后续所有操作（打印、轨迹查询、撤单）的主键 - 如果需要电子面单 PDF，调
/waybill/print时传waybill_no+print_type=1（热敏纸），别传waybill_code - 回执 PDF 内容含二维码，扫描后跳转顺丰官网，但该二维码解码后是
sfex://waybill?no=XXXX，非标准 HTTP 链接，别试图用 curl 抓取
丰桥 API 的难点不在代码量，而在字段语义和流程耦合度高——比如改一个收件人电话，得先撤单再重下，而撤单接口又依赖原始下单返回的 waybill_code。这些链路断点，文档里都藏在「注意事项」小字里，不跑通全流程根本意识不到。
