广告接口对接中的关键细节与实现路径

广告投放系统的接口对接向来以“细节多、坑位密”著称。很多开发者在初次接入时，往往会在鉴权头、媒体类型、接口版本这几处反复踩坑，调试成本远超预期。本文从实际对接顺序出发，先讲清楚最容易出问题的几个技术要点，再按调用链路逐步展开，给出一份可落地的实现路径。

一、三个最容易出错的技术要点

1.1 接口并非单一体系，而是多套并存

广告接口在版本演进过程中形成了两套并行的调用体系，二者的职责边界清晰但风格不统一：

• 广告活动（Campaign）层级的创建走的是较新的 v1 体系，路径形如 /adsApi/v1/...；
• 广告组（AdGroup）及其下属资源（关键词、商品广告、定向、否定关键词等）则走 Sponsored Products 的 v3 体系，路径形如 /sp/...。

这两套体系在请求头字段、Content-Type 取值、响应结构上都不一致。如果开发者想当然地按一套规则贯穿到底，通常会在中途收到 403 或 415 错误。因此第一步要做的不是写代码，而是先建立一张“资源—接口体系”的映射表，明确每个操作归属哪套体系。

1.2 请求头有两套命名，混用即失败

鉴权相关字段的命名是另一个高频失误点：

• v1 体系使用 Amazon-Ads-ClientId 与 Amazon-Ads-AccountId 这一组字段；
• SP v3 体系使用 Amazon-Advertising-API-ClientId 与 Amazon-Advertising-API-Scope 这一组字段。

两组字段名相似但完全不同，一旦在错误的体系里使用了另一套字段，服务端无法识别身份信息，会直接返回 403。实践中建议在 HTTP 客户端封装层按接口体系注入对应请求头，而不是在业务代码里手写，从结构上杜绝混用。

1.3 Content-Type 必须使用专属媒体类型

这是最容易被忽略、也最隐蔽的一点：SP v3 体系不接受 application/json。每个资源都有自己专属的 vendor MIME 类型，例如关键词资源使用 application/vnd.spKeyword.v3+json，其他资源也各有对应的媒体类型。

如果写成通用 JSON 类型，服务端要么返回 415（媒体类型不支持），要么返回 400（请求体解析失败）。更麻烦的是，这类错误信息往往不够直观，容易让人误以为是字段拼写问题。建议把每个资源对应的媒体类型整理成常量表，与接口路径一起维护。

二、整体创建依赖关系

广告结构的创建存在明确的先后依赖，顺序错乱会导致资源引用失败。整体链路如下（投资组合为可选项）：

LWA 授权
  → 获取账户信息（GET /v2/profiles）
    → 创建投资组合（POST /portfolios，可选）
      → 创建广告活动（POST /adsApi/v1/create_campaigns）
        → 创建广告组（POST /sp/adGroups）
          → 创建商品广告（POST /sp/productAds）
          → 创建关键词（POST /sp/keywords）
          → 创建定向（POST /sp/targets 或批量 PUT）
          → 创建否定关键词（POST /sp/negativeKeywords）
          → 创建否定定向（POST /sp/negativeTargets）
        → 创建广告活动级否定关键词（POST /sp/campaignNegativeKeywords）
        → 创建广告活动级否定定向（POST /sp/campaignNegativeTargets）

这张图的要点在于：广告组是绝大多数子资源的父节点，必须先拿到广告组 ID 才能继续；而广告活动级的否定资源挂在广告活动下，与广告组平级。理清父子关系后，代码里的调用顺序自然就确定了。

三、分步实现要点

3.1 授权与账户信息获取

第一步完成 LWA 授权换取访问令牌，随后调用账户信息接口获取 profileId。这个 ID 在后续几乎所有请求中都要用到，对应 v1 体系的 Amazon-Ads-AccountId 和 v3 体系的 Amazon-Advertising-API-Scope。建议将令牌与 profile 信息统一缓存在配置层，并做好过期刷新，避免每次调用都重新授权。

3.2 创建广告活动

广告活动走 v1 体系，请求头使用第一组字段。请求体通常包含活动名称、预算、投放状态、投放类型等字段。注意此处不要误用 v3 的媒体类型，保持 v1 体系的通用 JSON 格式即可。创建成功后记录返回的活动 ID，作为后续所有子资源的父级引用。

3.3 创建广告组

广告组切换到 v3 体系，请求头换成第二组字段，Content-Type 使用广告组资源对应的 vendor MIME。请求体中需引用上一步的活动 ID，并指定默认出价等参数。这一步是整条链路的分水岭——此后的所有操作都使用 v3 的规则。

3.4 创建关键词与商品广告

关键词与商品广告同样在 v3 体系下，分别使用各自的媒体类型。关键词请求体包含关键词文本、匹配类型、出价等；商品广告需要引用商品标识与广告组 ID。两者可以并行提交，但都必须等待广告组创建完成。

3.5 定向与否定资源

定向资源支持单条创建与批量提交两种方式，批量场景下使用 PUT 更高效。否定关键词与否定定向分为广告组级和广告活动级两个层次，注意区分路径与父级 ID 的归属，不要混用。

四、工程化建议

对接这类多体系接口，单靠记忆字段很容易出错，建议从工程层面做约束：

1. 封装请求层：按接口体系拆分两个客户端，各自维护请求头、基础路径与媒体类型，业务代码只调用封装后的方法。
2. 资源常量表：把每个资源的路径、媒体类型、所属体系整理成配置，集中管理。
3. 顺序编排：把创建链路抽象为有向依赖的任务编排，父资源成功后自动触发子资源创建，失败时保留上下文便于重试。
4. 错误分类处理：403 优先排查请求头，415/400 优先排查媒体类型，把常见错误码与排查方向写成文档，降低团队排障成本。

结语

广告接口对接的难点不在于业务逻辑复杂，而在于多套体系并存带来的规则碎片化。把接口归属、请求头、媒体类型这三件事在动手之前梳理清楚，再按依赖关系编排调用顺序，大部分“莫名其妙”的报错都可以提前规避。工程化的封装与常量管理，则是让这套对接在长期维护中保持稳定的关键。