快手联盟API必须服务端签名调用，签名含timestamp、nonce、method、path、body五要素并严格顺序，PHP须用hash_hmac('sha256')；收益数据需先查汇总再拉单日明细；流量接口返回三层嵌套结构需判空解析；cURL须设超时与重试机制。
快手联盟 API 的 PHP 调用必须走服务端签名，不能前端直连
快手联盟所有数据接口（如 /rest/kuaishou/union/earnings/detail、/rest/kuaishou/union/traffic/stat）强制要求服务端发起请求，并对参数做 HMAC-SHA256 签名。直接在浏览器或 JS 里调用会返回 {"code":401,"msg":"Invalid signature"} —— 这不是鉴权失败，是签名校验没过。
关键点在于：签名必须包含 timestamp（秒级时间戳）、nonce（随机字符串）、method（全大写 HTTP 方法）、path（API 路径，不含 query 参数）、body（POST 请求体的原始 JSON 字符串，空请求则为空字符串），且顺序不能错。
- PHP 必须用
hash_hmac('sha256', $signStr, $secretKey)计算签名，不能用 base64_encode(md5()) 或其他变体 -
nonce每次请求必须唯一，建议用bin2hex(random_bytes(8))，重复会导致{"code":400,"msg":"Nonce already used"} - 请求头必须带
Content-Type: application/json和Authorization: KUAISHOU <access_token></access_token>，其中access_token是通过授权码换来的长期 token，不是临时 code
获取广告收益数据要分两步：先查日期范围，再拉明细
快手不支持一次性拉取跨月或超 30 天的收益数据。/rest/kuaishou/union/earnings/detail 接口只接受单日 date 参数（格式为 "2024-05-20"），且最多返回当天 1000 条记录。如果你有大量订单，得自己循环日期 + 分页处理。
更实际的做法是先调 /rest/kuaishou/union/earnings/summary 拿到某日汇总（含 total_income、settled_income），确认数据存在且可访问，再按需拉明细。
立即学习“PHP免费学习笔记（深入）”；
- 明细接口返回字段中，
income是分成后金额（单位：分），advertiser_name可能为空，需用ad_id关联广告计划查名称 - 如果返回
"code":200但"data":[]，大概率是该日无结算数据，或账号未开通对应权限（如“收益明细”需单独申请） - 不要用
date传今天，快手 T+1 出数，今天调昨天的数据才稳定
流量数据接口返回结构嵌套深，解析时容易漏字段
调用 /rest/kuaishou/union/traffic/stat 获取播放、点击、转化等指标，返回的 data 是三层嵌套：data → list → [0] → stats → [0] → value。最外层 list 是按维度（如 date、ad_id）分组的结果，每组内 stats 才是具体指标数组，每个指标含 key（如 "play_count"）和 value（数值）。
常见错误是直接遍历 $res['data']['list'] 就结束，结果拿到一堆空数组。PHP 解析时务必加判空：
if (isset($res['data']['list']) && is_array($res['data']['list'])) {
foreach ($res['data']['list'] as $group) {
if (!isset($group['stats']) || !is_array($group['stats'])) continue;
foreach ($group['stats'] as $stat) {
if ($stat['key'] === 'click_count') {
$clicks = (int)$stat['value'];
}
}
}
}
-
date维度下stats数量固定（约 12 个指标），但ad_id维度下可能只有 3–5 个，取决于你选的指标参数 - 接口默认只返回最近 7 天，想查更早需显式传
start_date和end_date，且跨度不能超 30 天 - 返回的
value是字符串，不是数字，强转前先is_numeric()判一下，避免"--"导致(int)"--"变成 0
PHP cURL 请求必须设 timeout 和 retry，快手网关不稳定
快手联盟 API 响应时间波动大，实测 P95 耗时常超 3 秒，偶发 502 或连接超时。用默认 cURL 设置（无 CURLOPT_TIMEOUT）容易卡住进程，尤其批量拉多日数据时。
- 必须设
CURLOPT_TIMEOUT => 10和CURLOPT_CONNECTTIMEOUT => 3，否则单次失败会拖垮整批请求 - 对
502、503、curl error 7（Failed to connect）这类网络错误，建议自动重试 2 次，间隔 1 秒，用usleep(1000000) - 别用
file_get_contents()，它不支持自定义 header 签名，也控制不了超时 - 如果连续 3 次
429 Too Many Requests，说明触发限流，需暂停 30 秒再继续，快手没公开限流规则，但实测 QPS > 2 就容易被压
签名逻辑、日期偏移、字段嵌套、网络容错——这四块不提前踩一遍，跑半天可能只拿到空数组或一堆 401。快手的文档里没写的细节，基本都藏在这几个地方。
