阿里妈妈API调用必须经OAuth2授权获取access_token并严格签名：先跳转授权、换token、带Bearer头请求；订单同步用taobao.tbk.order.details.get，按tk_status状态机处理（12付款→13结算），防重入、加事务、校验签名。
阿里妈妈 API 的 PHP 调用必须走 OpenResty + OAuth2 授权流
直接用 file_get_contents 或 curl 拼 URL 请求阿里妈妈开放平台接口，99% 会返回 {"code":4001,"msg":"invalid app_key"} 或 {"code":4003,"msg":"invalid sign"} —— 不是因为签名错，而是根本没走授权流程。阿里妈妈（现归属淘宝联盟）所有订单、佣金类接口（如 taobao.tbk.order.details.get）强制要求 OAuth2 授权后获取的 access_token，且该 token 有效期仅 2 小时，必须配套刷新机制。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 先在阿里妈妈开放平台创建应用，拿到
app_key和app_secret，并配置回调域名（不能是 localhost） - 用户首次访问你的推广页时，跳转到
https://oauth.taobao.com/authorize?response_type=code&client_id={app_key}&redirect_uri={encoded_url} - 收到回调
code后，用curlPOST 到https://oauth.taobao.com/token换取access_token（注意：需传grant_type=authorization_code、code、redirect_uri、client_id、client_secret） - 后续所有接口请求头必须带
Authorization: Bearer {access_token}，且参数需按淘系规则参与签名（不是简单 Hmac-SHA256，要排序+拼接+URL encode）
同步淘宝客订单要用 taobao.tbk.order.details.get，别碰 taobao.tbk.report.get
taobao.tbk.report.get 是旧版报表接口，数据延迟大（常滞后 2–7 天）、字段残缺（无实际付款金额、无子订单拆分）、不支持按时间范围精确拉取，已不适用于实时对账。真正能用于订单与佣金同步的是 taobao.tbk.order.details.get，它返回结构化订单明细，含 pay_price、commission_amount、create_time、tk_status（关键！区分“付款”“结算”“冻结”状态）。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 每次调用最多拉 100 条，必须用
page_no和page_size分页，且start_time/end_time范围不能超过 7 天（否则报错illegal parameter） -
tk_status值为 12 表示“付款成功”，13 表示“结算成功”，只有状态为 13 才可确认佣金到账；状态为 3（订单关闭）或 4（维权中）的订单必须标记为异常，不可计入收益 - 接口返回的
order_id是淘宝侧订单号，不是你自己的订单 ID，需建立映射表关联到你系统中的用户和商品 - 务必校验
sign字段：服务端用app_secret对返回参数按字典序拼接再 HMAC-SHA256，防止中间人篡改响应
PHP 签名生成容易漏掉 URL 编码和参数排序
阿里系所有 API 签名规则是：把所有请求参数（包括 app_key、method、timestamp 等系统级参数）按 key 字典序升序排列 → 拼成 key1value1key2value2... 形式 → 再对整个字符串做 hash_hmac('sha256', $str, $app_secret)。但 PHP 开发者常在这里翻车：
- 没对 value 做
rawurlencode()（不是urlencode()），导致含中文或斜杠的参数签名失败 - 把
sign参数本身也混入签名计算，实际签名时不包含sign字段 - 用
time()生成timestamp，但服务器时间与阿里服务器偏差超 15 分钟就直接拒绝（建议用 NTP 校准或从https://api.m.taobao.com/rest/api3.do?method=mtop.common.getTimestamp获取标准时间） - POST 请求体里混用 JSON 和 form-data，阿里妈妈只认
application/x-www-form-urlencoded，JSON 会返回invalid request
佣金同步必须处理重复推送和状态跃迁
淘宝联盟的订单状态不是线性推进的：一笔订单可能从 12（付款）→ 13（结算）→ 3（关闭），也可能 12 → 4（维权）→ 13（维权结束重结算）。如果你只按“最新状态覆盖”，就会把已结算的佣金又清零。更麻烦的是，同一笔订单可能因网络重试被多次推送到你的回调地址（尤其使用 taobao.tbk.order.track 订阅模式时）。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
order_id + tk_status组合做唯一索引，避免重复插入；更新前先查当前状态，只允许向更高业务意义的状态跃迁（如 12 → 13 允许，13 → 12 不允许） - 不要依赖单次拉取结果做最终判断，需维护本地订单状态机：初始为 0，收到 12 写入待结算，收到 13 更新为已结算，收到 3/4 则标记为异常并人工核验
- 每小时定时调用
taobao.tbk.order.details.get补漏（尤其关注tk_status=13且本地未标记的订单），补漏窗口设为最近 48 小时即可，太长效率低 - 所有写库操作必须加事务，且更新前用
SELECT ... FOR UPDATE锁住对应订单行，防止并发写覆盖
最麻烦的其实是时间戳精度和状态解释——淘宝返回的 create_time 是字符串格式（如 "2024-05-20 14:23:01"），但 tk_status 变更时间不单独返回，只能靠轮询间隔去推测；而不同类目佣金结算周期不同，有些要等 30 天后才变 13，这些没法绕开，得在业务逻辑里硬扛。
