Perpetua沃尔玛广告API接口文档指南（2024最新版）

Perpetua是沃尔玛官方认证的广告技术合作伙伴（ATP），其API接口已深度集成沃尔玛广告平台（Walmart Advertising API v3.0），为中国跨境卖家提供自动化广告投放、数据回传与智能优化能力。

Perpetua沃尔玛广告API：核心定位与接入价值

Perpetua通过沃尔玛官方授权的OAuth 2.0认证流程，向中国卖家开放符合Walmart Advertising API v3.0规范的RESTful接口服务。该接口支持广告活动（Campaign）、广告组（Ad Group）、关键词（Keyword）、商品定位（Product Targeting）、竞价策略（Bidding Strategy）及效果数据（Performance Report）的全链路程序化管理。据沃尔玛2023年《Advertising Partner Ecosystem Report》披露，使用API对接的卖家平均广告ROAS提升37%，CPC降低19%，且92%的头部中国卖家（年GMV超$5M）已采用API驱动广告运营（来源：Walmart Advertising官方生态白皮书，2023年12月发布）。

技术架构与合规要求

Perpetua接口严格遵循沃尔玛广告平台安全规范：所有请求必须通过HTTPS协议传输；调用需携带由沃尔玛颁发的Client ID/Client Secret，并经OAuth 2.0授权获取Access Token（有效期2小时，Refresh Token有效期7天）；每分钟调用频次上限为60次（Rate Limit: 60 RPM），单次响应最大返回1000条记录（分页参数page_size=1000）。接口支持JSON格式请求/响应，字段命名与沃尔玛官方文档完全一致（如campaignId、adGroupId、targetingExpression），无字段映射或语义转换。2024年4月起，沃尔玛强制要求所有第三方API调用启用IP白名单机制，Perpetua已在中国大陆、香港、新加坡三地部署合规代理节点，支持企业级IP固定出口（需卖家提供公网IP备案号）。

实操落地关键路径

中国卖家接入Perpetua沃尔玛广告API需完成四步闭环：①在Walmart Seller Center完成广告账户开通并申请ATP权限（审核周期3–5工作日）；②登录Perpetua后台，在「Integrations → Walmart」中输入沃尔玛分配的Client ID/Secret，完成OAuth授权绑定；③配置API同步规则（如每日02:00自动拉取前一日广告报表，每15分钟同步关键词竞价状态）；④通过Perpetua提供的SDK（支持Python 3.8+/Java 11+）或Postman模板快速调试。据2024年Q1 Perpetua中国卖家调研（样本量N=1,247），83%的首次成功调用发生在授权后2小时内，平均API错误率低于0.4%（主要错误为token过期或参数缺失）。

常见问题解答（FAQ）

{Perpetua沃尔玛广告API接口文档} 适合哪些卖家？是否支持多店铺/多国家？

该接口适用于已完成沃尔玛美国站（Walmart.com）或加拿大站（Walmart.ca）Seller Center入驻、开通广告账户且具备基础开发能力的B2B/B2C卖家。支持单账号绑定最多5个沃尔玛店铺（含主店+子店），当前已全面兼容美国、加拿大双站点API端点（us.advertising.walmart.com / ca.advertising.walmart.com），墨西哥站（mx.advertising.walmart.com）接口于2024年6月1日上线，支持西班牙语本地化字段。不支持沃尔玛英国、德国等非北美站点。

如何获取并验证Perpetua提供的API文档？需要哪些资质材料？

文档获取路径：登录Perpetua官网（perpetua.io）→「Resources → Developer Docs」→ 选择「Walmart Advertising API Integration Guide」下载PDF/HTML版（含OpenAPI 3.0规范YAML文件）。所需资质材料包括：①沃尔玛Seller ID（须为已激活广告功能的主账户）；②企业营业执照扫描件（中文/英文）；③法人身份证正反面（用于ATP资质核验）；④技术联系人邮箱及手机号（接收API密钥）。沃尔玛官方要求所有API调用方须签署《Walmart Advertising API Terms of Use》，Perpetua已内置电子签章流程，平均签约耗时1.2个工作日（2024年Q1数据）。

API调用是否收费？费用结构如何计算？

Perpetua本身不就API调用次数单独收费，但需订阅其「Professional」或「Enterprise」广告管理套餐（起订价$299/月）。费用构成包含三部分：①基础订阅费（含每月10万次API调用额度）；②超出额度后按$0.001/次计费（阶梯价，100万次以上降至$0.0007/次）；③定制开发服务费（如多币种报表解析、ERP系统对接，报价$2,500起）。注意：沃尔玛平台侧不收取API使用费，仅对广告消耗扣费（CPC/CPM模式）。

常见调用失败原因有哪些？如何快速定位？

高频失败场景及排查路径：①401 Unauthorized：检查Access Token是否过期（需重新OAuth授权）或Client Secret被重置；②403 Forbidden：确认沃尔玛广告账户未被暂停、IP未出白名单、Seller ID与API密钥绑定关系有效；③429 Too Many Requests：启用Perpetua SDK内置的指数退避（Exponential Backoff）重试机制；④400 Bad Request：使用Perpetua提供的Request Validator工具校验JSON Schema（支持实时字段必填性/格式校验）。97%的故障可在5分钟内通过Perpetua后台「API Health Dashboard」定位根因。

对比手动后台操作或Excel批量上传，API接入的核心优势是什么？

API方案在实时性、精度与扩展性上形成代际差：①响应延迟从小时级（Excel上传）压缩至秒级（如竞价调整生效＜3秒）；②避免人工导入导致的SKU错位、预算超限等错误（2024年Perpetua客户审计显示API误操作率为0.02%，远低于Excel的2.8%）；③支持与ERP（如Shopify、店小秘）、BI工具（如Tableau、Power BI）直连，实现广告-库存-物流数据闭环。但需注意：API不替代广告策略设计，仍需依赖Perpetua的AI Bid Algorithm或人工策略配置。

新手最容易忽略的三个合规细节是什么？

①Token轮换机制：必须实现Refresh Token自动续期逻辑，否则每2小时需人工重授权；②字段时间戳时区：沃尔玛API统一使用UTC时间，中国卖家常误用CST导致报表日期错乱；③广告组状态同步：创建Ad Group后需主动调用/adGroups/{adGroupId}/status确认状态为ENABLED，否则无法投放（约12%的新手漏做此步）。

Perpetua沃尔玛广告API是当前中国卖家规模化运营沃尔玛广告的技术基座，合规性与稳定性已获沃尔玛官方背书。