电商广告 API 对接实践：认证、分层与避坑指南

一、为什么电商广告 API 的对接总是“很绕”

对接过电商平台广告开放接口的开发者，几乎都经历过类似的挫败：文档翻了好几遍，请求却依旧返回 403；参数明明看起来都对，服务端却回 415。这类问题通常不是某个高深的技术难点，而是几个“反直觉”的现实叠加在一起：

1. 一个平台，多套接口并存。 大型电商平台的广告体系往往经历了多年演进，早期上线的旧版接口族与重构后的新版接口族同时对外提供服务：广告活动（Campaign）级别的高频操作走旧版路径，而广告组及其下属资源——关键词、定向、商品广告、否定词等——全部走新版路径。两套接口族不仅路径前缀不同，请求头约定、Content-Type 规则、响应结构也互不兼容。动手之前必须先判断“这次请求属于哪个接口族”，否则后面全是坑。
2. 请求头命名不统一。 旧版接口族要求携带“客户端 ID + 广告账号 ID”两个头部；新版接口族则要求“客户端 ID + 作用域（Scope）”。字段命名风格与取值来源完全不同。混用两者——比如把旧版的账号头塞进新版请求——服务端往往不会给出语义清晰的报错，只会冷冰冰地返回 403，极易被误判为权限配置问题。
3. Content-Type 不是普通的 application/json。 新版接口族为每个资源定义了专属的厂商自定义 MIME 类型，形如 application/vnd.<资源名>.<版本>+json：请求广告组、请求关键词、请求定向，各自对应不同的 MIME 值。写错 MIME，轻则 415（不支持的媒体类型），重则 400（请求体解析失败）。这种“一资源一 MIME”的 REST 实践并不常见，恰恰是对接中最容易被忽略的细节。
4. 实体之间存在严格的依赖链。 你不能凭空创建关键词——必须先创建广告活动，再创建广告组，最后才能在广告组下挂关键词或定向。跳过任何一步，都会收到“引用实体不存在”类的错误。理解并显式建模这条依赖链，是一切对接工作的前提。

二、先看清骨架：实体依赖关系全景

按实际对接顺序，完整的依赖链如下（广告组合为可选环节）：

OAuth 授权（获取 Access Token）
        │
        ▼
Profile 列表（获取账号 / 站点经营主体）
        │
        ▼（可选）
Portfolio 广告组合（预算分组容器）
        │
        ▼
Campaign 广告活动
        │
        ├──► AdGroup 广告组
        │        ├──► 商品广告（Product Ads）
        │        ├──► 关键词（Keywords）
        │        ├──► 定向目标（Targets）
        │        ├──► 否定关键词（Negative Keywords）
        │        └──► 否定定向（Negative Targets）
        │
        ├──► 活动级否定关键词
        └──► 活动级否定定向

各层职责一句话概括：Access Token 是全局准入凭证；Profile 决定“以哪个经营主体的身份操作”；Campaign 承载预算、竞价策略与投放周期等顶层配置；AdGroup 承载出价与匹配方式；关键词、定向、商品广告是实际投放载体；否定关键词与否定定向负责排除无效流量，且在组级与活动级各有一层，可实现粗细两档过滤。先把这张图印在脑子里，后面每一步都围绕它展开。

三、第一步：OAuth 授权与令牌管理

1. 标准授权码模式

广告类接口普遍要求在每次请求的 Authorization 头中携带 Bearer Access Token，获取流程遵循 OAuth 2.0 授权码模式：构造授权跳转 URL（携带 client_id、redirect_uri 与 scope，广告管理类 scope 通常形如 ads::campaign_management）→ 用户登录并授权 → 平台回调携带授权码 → 服务端用授权码换取 access_token 与 refresh_token。

# 用授权码换取令牌（示意）
def exchange_code(code: str, redirect_uri: str):
    return http.post(TOKEN_ENDPOINT, data={
        "grant_type": "authorization_code",
        "code": code,
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "redirect_uri": redirect_uri,
    })
# 刷新令牌（示意）
def refresh_token(refresh_token: str):
    return http.post(TOKEN_ENDPOINT, data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    })

2. 令牌管理的四个工程要点

• 有效期错配：access_token 通常只有一小时量级，refresh_token 长期有效，必须实现自动刷新，而非人工换码。
• 集中管理：令牌的获取、缓存与刷新应由独立的凭证服务统一负责，配合分布式锁防止并发刷新互相覆盖；在到期前 5～10 分钟主动刷新，避开业务高峰期的批量 401。
• 安全存储：client_secret 与 refresh_token 属于高危凭证，应存放在密钥管理类服务中加密保管，严禁明文提交进代码仓库。
• 失效兜底：捕获 401 后强制刷新并重试一次，同时把刷新失败接入告警，防止“令牌已坏却无人知晓”。

四、第二步：Profile 与区域路由

1. Profile 是“经营主体”维度的抽象。 一次授权可能覆盖多个店铺或多个区域站点，平台通过 Profile ID 区分这些主体；绝大多数业务请求都要在头部携带 Profile ID 作为账号作用域。授权完成后应第一时间拉取 Profile 列表，把 ID、区域、币种、时区等元数据落库缓存——这些元数据会直接影响后续的预算计算与报表口径。

2. 区域路由要点。 不同区域站点往往对应不同的服务端点，路由依据通常是“区域码 → 端点”映射表。三条实践建议：映射表必须配置化，放配置中心，平台调整端点时可热更新；Profile 缓存要设置合理 TTL，并在授权范围变化后主动失效；跨区域请求时，头部作用域与端点必须成对切换，只换其一同样会得到 403。

五、第三步：用“适配层”驯服多版本接口

这是整个对接中最值得投入设计的一环。既然两套接口族在头部与 Content-Type 上互不兼容，就不应让业务代码直接面对这些差异。推荐在业务层与平台接口之间增加一层适配层（防腐层），职责有三：头部适配（按接口族维护头部构造规则，业务代码只传“资源 + 主体”）、MIME 注册表（把资源到 Content-Type 的映射集中管理，禁止散落硬编码）、响应归一（两套接口族字段命名与分页方式不同，统一转换为内部模型）。

MIME_REGISTRY = {
    "campaigns": "application/json",                  # 旧版族：普通 JSON
    "adGroups":  "application/vnd.adgroups.v3+json",  # 新版族：厂商自定义 MIME
    "keywords":  "application/vnd.keywords.v3+json",
    "targets":   "application/vnd.targets.v3+json",
}
def build_headers(resource: str, profile_id: str, token: str) -> dict:
    headers = {"Authorization": f"Bearer {token}"}
    if resource == "campaigns":            # 旧版接口族
        headers["X-Client-Id"] = CLIENT_ID
        headers["X-Ad-Account-Id"] = profile_id
    else:                                  # 新版接口族
        headers["X-Client-Id"] = CLIENT_ID
        headers["X-Ad-Scope"] = profile_id
    headers["Content-Type"] = MIME_REGISTRY[resource]
    return headers

（说明：头部字段名与 MIME 值均为示意，实际命名以目标平台文档为准。）

适配层的最大收益在于演进隔离：当平台把旧版族能力逐步迁移到新版族、或字段命名再次调整时，变更被压缩在适配层内部，业务层与数据模型无需改动。

六、第四步：按依赖链创建广告实体

1. 顺序固定，先上后下：Campaign → AdGroup → 子资源（商品广告 / 关键词 / 定向 / 否定词）。建议把依赖链显式建模为状态机：每个 Campaign 记录“骨架是否就绪”，只有就绪后才允许创建子资源，避免并发任务乱序踩空。
2. 批量优先：几乎所有资源都提供批量创建接口。逐条循环调用既慢又易触发限流，应按批次聚合请求，同时注意单批数量上限，超限则自动分片。
3. 处理“部分成功”：批量接口的返回通常是逐条结果数组——可能一部分成功、一部分失败。必须逐条解析状态码与错误信息，失败项落库并支持单独补发，而不是整批回滚重跑。
4. 幂等与防重：网络超时后盲目重试极易造成重复建活动。若平台提供幂等键或请求 ID 机制，务必启用；否则先在本地记录“发起中”状态，超时后先查询确认，再决定是否重试。
5. 状态与数据同步：创建成功只是起点。实体的启停、预算调整需要双向同步；报表类数据（曝光、点击、花费）通常存在数小时级延迟，不要用管理接口的数据搭建“实时大盘”，应以异步报表任务为准。

七、错误定位速查与稳定性设计

1. 高频错误对照表

状态码	高频原因	排查动作
401	access token 过期	触发刷新流程后重试
403	混用两套接口族的头部；作用域与 Profile 不匹配；账号未完成对应授权	逐字段核对头部与接口族的对应关系
400	MIME 正确但请求体不符合该版本 schema	对照文档逐字段比对，注意两套族的命名风格差异
415	Content-Type 不符合该资源要求	核对 MIME 注册表
429	触发平台限流	指数退避重试并降低并发
5xx	平台侧瞬时异常	退避重试，持续失败则熔断并告警

2. 稳定性三板斧

• 退避要有抖动：指数退避叠加随机抖动，避免同一批失败请求在相同时间点集体重试，造成限流雪崩；若响应带有重试提示，则优先遵循。
• 重试要有边界：仅对幂等且瞬时性的错误重试；创建类操作默认不自动重试，必须走“先查后补”路径。
• 观测要成体系：每次请求记录请求 ID、接口族、资源类型、状态码与耗时，结构化日志统一接入日志服务，对错误率、延迟、限流次数配置告警。这类通用能力可直接复用云上现成组件（例如百度智能云提供的日志服务与监控告警），把精力留给业务本身。

3. 削峰与配额：同步创建高峰可用消息队列缓冲，让消费速率匹配平台配额；客户端按 Profile 维度自设并发配额，防止单个账号的突发流量拖垮整体调度。

八、工程化落地建议

1. 分层清晰：凭证层（OAuth 与刷新）→ 路由层（Profile、区域、MIME）→ 客户端层（各资源操作）→ 业务层（投放策略），层与层之间用内部模型通信。
2. 配置与代码分离：端点、路由映射、MIME 注册表、限流阈值全部配置化，平台侧一变，改配置即可生效。
3. 沙箱先行：先在测试环境打通含否定词在内的全链路资源再切生产；活动级否定词这类低频资源最容易被遗漏，恰恰要在沙箱里覆盖。
4. 契约测试：对两套接口族分别固化请求与响应样例做回归测试，防止平台侧不兼容变更悄悄破坏线上流程。
5. 演进预案：接口版本迁移是常态，保持内部模型稳定、把变更压在适配层，是对接系统长期存活的关键。

九、小结

电商广告 API 的对接难点，本质上不是“接口难调”，而是“体系复杂”：多版本并存、认证头分裂、MIME 个性化、依赖链严格。应对思路同样清晰——先把依赖链与账号主体模型建对，再用适配层隔离平台差异，最后用限流、重试、观测三板斧保证线上稳定。把这三件事做扎实，剩下的就只是按文档逐个资源填充实现的工作量问题了。