Lingxing
切换旧版

创建 SP 广告

POST/basicOpen/adReport/manage/postSpAds

接口信息

API Path请求协议请求方式令牌桶容量
/basicOpen/adReport/manage/postSpAdsHTTPSPOST1

请求参数

profileIdstring必填
当前租户已授权的亚马逊广告店铺标识,使用正整数形式的字符串,避免长整数精度丢失。
adsarray<object>必填
待创建的商品推广广告列表,每次提交 1~1000 条。
最少1项
最多1000项
隐藏子属性
adGroupIdstring必填
广告所属广告组的唯一标识,使用数字字符串。当前服务要求正整数值,且须属于当前授权广告店铺。
adProductstring必填
SPONSORED_PRODUCTS 表示商品推广广告。
adTypestring必填
PRODUCT_AD 表示根据指定商品构建的广告创意。
creativeobject必填
商品推广广告的创意包装对象。
隐藏子属性
productCreativeobject必填
根据指定商品构建的创意,包含商品创意设置。
隐藏子属性
productCreativeSettingsobject必填
推广商品及可选的标题、聚焦视频配置。
隐藏子属性
advertisedProductobject必填
当前广告推广的商品,包含商品标识、标识类型及可选的全球商店配置。
隐藏子属性
globalStoreSettingobject
推广商品的全球商店配置,包含商品目录来源站点。
隐藏子属性
catalogSourceMarketplacestring
商品目录来源的亚马逊站点代码
US 表示美国站。该值用于指定目录来源,不等同于修改广告投放站点。可不传或传空字符串,非空值须为列出的可选值
可选值:
AE
AU
BE
BR
CA
DE
EG
ES
FR
GB
IE
IN
IT
JP
MX
NL
PL
SA
SE
SG
TR
US
ZA
productIdstring必填
推广商品的标识,与 productIdType 配套使用:ASIN 或卖家 SKU。当前服务要求非空字符串。
productIdTypestring必填
ASIN=亚马逊标准商品标识
SKU=卖家库存商品编码。
headlinestring
广告或视频创意使用的标题或自定义文本。
spotlightVideosobject
商品推广可选的视频创意配置;传入时须同时提供文本优化开关和视频列表。
隐藏子属性
optimizeTextboolean必填
true=允许亚马逊优化广告主提供的文本
false=不允许。
videosarray<object>必填
用于商品推广的视频素材列表,包含 1~5 个视频;每个视频须提供素材 ID 和版本。
最少1项
隐藏子属性
assetIdstring必填
素材库中视频素材的唯一标识。
assetVersionstring必填
素材库中视频素材对应的版本标识。
descriptionstring
视频素材内容的说明文本。
headlinestring必填
广告或视频创意使用的标题或自定义文本。
statestring必填
ENABLED=已启用
PAUSED=已暂停。已启用的广告仍需满足父级状态、商品资格等投放条件。

请求cURL示例

curl --location 'https://openapi.lingxing.com/basicOpen/adReport/manage/postSpAds?access_token=value&timestamp=value&sign=value&app_key=value' \
--header 'Content-Type: application/json' \
--data '{
    "profileId": "1234567890123456",
    "ads": [
        {
            "adGroupId": "1234567890123456",
            "adProduct": "SPONSORED_PRODUCTS",
            "adType": "PRODUCT_AD",
            "creative": {
                "productCreative": {
                    "productCreativeSettings": {
                        "advertisedProduct": {
                            "productId": "B000000001",
                            "productIdType": "ASIN"
                        }
                    }
                }
            },
            "state": "PAUSED"
        }
    ]
}'

返回结果

Json Object

codeinteger必填
平台业务状态码,0 表示成功
示例 0
messagestring必填
响应消息
示例 success
error_detailsarray<any>必填
参数校验等错误详情
示例 []
request_idstring必填
请求链路标识
示例 example-request-id
response_timestring必填
响应时间
示例 2026-10-19 12:00:00
dataobject必填
响应数据。
隐藏子属性
apiResultarray<object>必填
每项结果通过原始下标对应请求中的广告;应检查每项结果码,批量或工具调用可能包含失败项。以下展示创建成功项,失败项可能仅含 code、index 和 description。
隐藏子属性
adGroupIdstring必填
广告所属广告组的唯一标识,使用数字字符串。当前服务要求正整数值,且须属于当前授权广告店铺。
adIdstring必填
亚马逊生成的广告唯一标识。使用字符串保存,避免长整数精度丢失。
adProductstring必填
SPONSORED_PRODUCTS 表示商品推广广告。
示例 SPONSORED_PRODUCTS
adTypestring必填
PRODUCT_AD 表示根据指定商品构建的广告创意。
示例 PRODUCT_AD
campaignIdstring必填
广告所属广告活动的唯一标识,为只读返回字段。
creationDateTimestring必填
广告创建时间,采用带时区的日期时间格式。示例中的 -07:00 表示当地时间为协调世界时减 7 小时。
creativeobject必填
商品推广广告的创意包装对象。
隐藏子属性
productCreativeobject必填
根据指定商品构建的创意,包含商品创意设置。
隐藏子属性
productCreativeSettingsobject必填
推广商品及可选的标题、聚焦视频配置。
隐藏子属性
advertisedProductobject必填
当前广告推广的商品,包含商品标识、标识类型及可选的全球商店配置。
隐藏子属性
globalStoreSettingobject必填
推广商品的全球商店配置,包含商品目录来源站点。
隐藏子属性
catalogSourceMarketplacestring必填
商品目录来源的亚马逊站点代码
US 表示美国站。该值用于指定目录来源,不等同于修改广告投放站点。
可选值:
AE
AU
BE
BR
CA
DE
EG
ES
FR
GB
IE
IN
IT
JP
MX
NL
PL
SA
SE
SG
TR
US
ZA
示例 AE
productIdstring必填
推广商品的标识,与 productIdType 配套使用:ASIN 或卖家 SKU。当前服务要求非空字符串。
productIdTypestring必填
ASIN=亚马逊标准商品标识
SKU=卖家库存商品编码。
示例 ASIN
resolvedProductIdstring必填
与推广商品关联的解析后商品标识,为只读返回字段。
resolvedProductIdTypestring必填
解析后商品标识的类型
ASIN=亚马逊标准商品标识
SKU=卖家库存商品编码。
示例 ASIN
headlinestring必填
广告或视频创意使用的标题或自定义文本。
spotlightVideosobject必填
商品推广可选的视频创意配置;传入时须同时提供文本优化开关和视频列表。
隐藏子属性
optimizeTextboolean必填
true=允许亚马逊优化广告主提供的文本
false=不允许。
videosarray<object>必填
用于商品推广的视频素材列表,包含 1~5 个视频;每个视频须提供素材 ID 和版本。
隐藏子属性
assetIdstring必填
素材库中视频素材的唯一标识。
assetVersionstring必填
素材库中视频素材对应的版本标识。
descriptionstring必填
视频素材内容的说明文本。
headlinestring必填
广告或视频创意使用的标题或自定义文本。
globalAdIdstring必填
管理当前站点广告的全球广告标识;可选返回字段,本次示例未返回。
lastUpdatedDateTimestring必填
广告最后更新时间,采用带时区的日期时间格式,保留原始时区偏移。
marketplaceScopestring必填
SINGLE_MARKETPLACE 表示单站点广告。
示例 SINGLE_MARKETPLACE
marketplacesarray<any>必填
string 数组,广告适用的亚马逊零售站点代码,应与所属广告组相同或为其子集;当前定义为单站点,US 表示美国站。
可选值:
AE
AU
BE
BR
CA
DE
EG
ES
FR
GB
IE
IN
IT
JP
MX
NL
PL
SA
SE
SG
TR
US
ZA
statestring必填
ARCHIVED=已永久归档且不可重新启用
ENABLED=已启用
PAUSED=已暂停。
示例 ARCHIVED
statusobject必填
广告的实际投放状态及其原因。该对象不同于广告主设置的 state,本次响应只包含原因列表。
隐藏子属性
deliveryReasonsarray<any>必填
string 数组,实际投放状态对应的原因列表,可为空数组,最多 50 项。OTHER 表示其他原因,无法据此确定具体原因。
可选值:
ADVERTISER_ARCHIVED
ADVERTISER_OUT_OF_BUDGET
ADVERTISER_OUT_OF_POSTPAY_CREDIT_LIMIT
ADVERTISER_OUT_OF_POSTPAY_MONTHLY_BUDGET
ADVERTISER_OUT_OF_PREPAY_BALANCE
ADVERTISER_PAUSED
ADVERTISER_PAYMENT_FAILURE
ADVERTISER_POLICING_PENDING_REVIEW
ADVERTISER_POLICING_SUSPENDED
AD_ARCHIVED
AD_CREATION_FAILED
AD_CREATION_IN_PROGRESS
AD_EXTENSION_ARCHIVED
AD_EXTENSION_PAUSED
AD_EXTENSION_POLICING_PENDING_REVIEW
AD_EXTENSION_POLICING_SUSPENDED
AD_GROUP_ARCHIVED
AD_GROUP_INCOMPLETE
AD_GROUP_LOW_BID
AD_GROUP_PAUSED
AD_GROUP_PENDING_REVIEW
AD_GROUP_POLICING_PENDING_REVIEW
AD_GROUP_REJECTED
AD_INELIGIBLE
AD_MISSING_DECORATION
AD_MISSING_IMAGE
AD_NOT_DELIVERING
AD_PAUSED
AD_POLICING_PENDING_REVIEW
AD_POLICING_SUSPENDED
BRAND_INELIGIBLE
CAMPAIGN_ARCHIVED
CAMPAIGN_END_DATE_REACHED
CAMPAIGN_INCOMPLETE
CAMPAIGN_OUT_OF_BUDGET
CAMPAIGN_PAUSED
CAMPAIGN_PENDING_REVIEW
CAMPAIGN_PENDING_START_DATE
CAMPAIGN_REJECTED
CREATIVE_MISSING_ASSET
CREATIVE_PENDING_REVIEW
CREATIVE_REJECTED
LANDING_PAGE_INELIGIBLE
LANDING_PAGE_NOT_AVAILABLE
MODERATION_ADULT_NOVELTY_POLICY_VIOLATION
MODERATION_ADULT_PRODUCT_POLICY_VIOLATION
MODERATION_ADULT_SOFTLINES_POLICY_VIOLATION
MODERATION_CLAIM_WEIGHTLOSS_POLICY_VIOLATION
MODERATION_CONTENT_NUDITY_POLICY_VIOLATION
MODERATION_CONTENT_PROVOCATIVE_POLICY_VIOLATION
MODERATION_CONTENT_SMOKING_POLICY_VIOLATION
MODERATION_CRITICAL_EVENTS_POLICY_VIOLATION
MODERATION_ERROR_404
MODERATION_GRAPHICAL_SEXUAL_IMAGES_POLICY_VIOLATION
MODERATION_HFSS_PRODUCT_POLICY_VIOLATION
MODERATION_LANGUAGE_OFFENSIVE_POLICY_VIOLATION
MODERATION_NOT_COMPLIANT_TO_AD_POLICY
MODERATION_SMOKING_RELATED_POLICY_VIOLATION
NOT_BUYABLE
NOT_IN_BUYBOX
NOT_IN_POLICY
NO_INVENTORY
NO_PURCHASABLE_OFFER
OTHER
OUT_OF_REWARD_BUDGET
OUT_OF_STOCK
PIR_RULE_EXCLUDED
PORTFOLIO_ARCHIVED
PORTFOLIO_END_DATE_REACHED
PORTFOLIO_OUT_OF_BUDGET
PORTFOLIO_PAUSED
PORTFOLIO_PENDING_START_DATE
SECURITY_SCAN_PENDING_REVIEW
SECURITY_SCAN_REJECTED
SPEND_LIMIT_EXCEEDED
STATUS_UNAVAILABLE
TARGET_ARCHIVED
TARGET_BLOCKED
TARGET_PAUSED
TARGET_POLICING_SUSPENDED
deliveryStatusstring必填
DELIVERING=正在投放
NOT_DELIVERING=未投放
UNAVAILABLE=状态不可用。本次真实响应未返回,不能仅凭原因列表补造此字段。
示例 DELIVERING
codestring必填
SUCCESS 表示当前广告创建成功。
示例 SUCCESS
indexinteger必填
对应请求广告数组中的原始下标,从 0 开始。
totalinteger必填
统一响应中的总数,本创建接口未设置分页总数,默认为0
示例 0

返回成功示例

{
    "code": 0,
    "message": "success",
    "error_details": [],
    "request_id": "example-request-id",
    "response_time": "2026-10-19 12:00:00",
    "data": {
        "apiResult": [
            {
                "adGroupId": "1234567890123456",
                "adId": "1234567890123456",
                "adProduct": "SPONSORED_PRODUCTS",
                "adType": "PRODUCT_AD",
                "campaignId": "1234567890123456",
                "creationDateTime": "2026-10-20T00:00:00Z",
                "creative": {
                    "productCreative": {
                        "productCreativeSettings": {
                            "advertisedProduct": {
                                "globalStoreSetting": {
                                    "catalogSourceMarketplace": "AE"
                                },
                                "productId": "B000000001",
                                "productIdType": "ASIN",
                                "resolvedProductId": "example",
                                "resolvedProductIdType": "ASIN"
                            },
                            "headline": "Example headline",
                            "spotlightVideos": {
                                "optimizeText": false,
                                "videos": [
                                    {
                                        "assetId": "asset-id-placeholder",
                                        "assetVersion": "1",
                                        "description": "example",
                                        "headline": "Example headline"
                                    }
                                ]
                            }
                        }
                    }
                },
                "globalAdId": "example",
                "lastUpdatedDateTime": "2026-10-20T00:00:00Z",
                "marketplaceScope": "SINGLE_MARKETPLACE",
                "marketplaces": [
                    "US"
                ],
                "state": "PAUSED",
                "status": {
                    "deliveryReasons": [
                        "example"
                    ],
                    "deliveryStatus": "DELIVERING"
                },
                "code": "SUCCESS",
                "index": 0
            }
        ]
    },
    "total": 0
}

附加说明

  • profileId 必须属于当前授权企业。标识使用字符串传递,避免长整数精度丢失。
  • 在 Query 中传入 access_token、app_key、timestamp、sign。修改请求体或鉴权参数后须重新计算签名,签名传输时只进行一次 URL 编码。
  • 先检查顶层 code,再逐项检查 data.apiResult[].code。顶层成功不代表每项均创建成功;index 是请求数组中从0开始的原始下标。
  • 示例仅说明数据结构,不是经过真实创建验证的返回。调用前替换标识及投放配置;字段说明中的源接口样本信息来自上游接口定义。
  • 返回字段表描述创建成功项,实际字段取决于创意类型及上游返回,失败项可能只包含结果码和下标。