已处理 待处理 {{opt.name}}

已处理 待处理

分析中 已回复 待规划 {{opt.name}}

分析中 已回复 待规划

亚马逊商品详情接口完全指南：从 PA-API 到 SP-API 的全链路实战

亚马逊作为全球最大的电商平台，其商品数据是跨境卖家、数据分析师、导购平台最核心的生产资料。但与国内平台不同，亚马逊的接口体系更为复杂——没有"一个接口包打天下"的方案，而是按使用场景拆分为联盟推广接口（PA-API）和卖家服务接口（SP-API）两大体系。本文将系统梳理亚马逊商品详情接口的全貌，并附可直接落地的代码示例。

一、亚马逊详情接口的两大体系

亚马逊的商品详情能力分散在两个完全不同的开放平台中，定位、权限、数据维度差异巨大：

二、PA-API 5.0：联盟推广场景的首选

PA-API 是亚马逊为联盟会员提供的官方数据接口，适合不需要卖家权限、只做商品展示和导购的场景。

2.1 接口基础信息

2.2 核心请求参数

表格

2.3 AWS Signature V4 签名（Python 完整示例）

PA-API 使用 AWS Signature Version 4 认证，签名逻辑较复杂，建议直接使用 AWS SDK：

Python

import json
import boto3
from botocore.config import Config

# 配置凭证
ACCESS_KEY = 'YOUR_ACCESS_KEY'
SECRET_KEY = 'YOUR_SECRET_KEY'
PARTNER_TAG = 'yourtag-20'
REGION = 'us-east-1'  # PA-API 固定区域

def get_paapi_client():
    config = Config(
        region_name=REGION,
        retries={'max_attempts': 3, 'mode': 'standard'}
    )
    return boto3.client(
        'paapi5',
        aws_access_key_id=ACCESS_KEY,
        aws_secret_access_key=SECRET_KEY,
        config=config
    )

def get_items_by_asin(asin_list):
    """
    根据 ASIN 列表获取商品详情
    单次最多 10 个 ASIN
    """
    client = get_paapi_client()
    
    payload = {
        'ItemIds': asin_list[:10],  # 最多 10 个
        'ItemIdType': 'ASIN',
        'Resources': [
            'Images.Primary.Large',
            'Images.Variants.Large',
            'ItemInfo.Title',
            'ItemInfo.ByLineInfo',
            'ItemInfo.Features',
            'ItemInfo.ProductInfo',
            'Offers.Listings.Price',
            'Offers.Listings.SavingBasis',
            'CustomerReviews.StarRating',
            'BrowseNodeInfo.BrowseNodes'
        ],
        'PartnerTag': PARTNER_TAG,
        'PartnerType': 'Associates',
        'Marketplace': 'www.amazon.com'
    }
    
    try:
        response = client.get_items(**payload)
        return response
    except Exception as e:
        print(f"请求失败: {e}")
        return None

# 调用示例
result = get_items_by_asin(['B08N5WRWNW', 'B0BSHF7WHW'])
print(json.dumps(result, indent=2, default=str))

2.4 返回数据结构解析

PA-API 5.0 返回结构清晰，核心字段如下 ：

{
    "ItemsResult": {
        "Items": [
            {
                "ASIN": "B08N5WRWNW",
                "DetailPageURL": "https://www.amazon.com/dp/B08N5WRWNW...",
                "ItemInfo": {
                    "Title": {
                        "DisplayValue": "Apple iPhone 15 Pro Max (256 GB) - Natural Titanium"
                    },
                    "ByLineInfo": {
                        "Brand": {
                            "DisplayValue": "Apple"
                        },
                        "Manufacturer": {
                            "DisplayValue": "Apple Computer"
                        }
                    },
                    "Features": {
                        "DisplayValues": [
                            "6.7-inch Super Retina XDR display",
                            "A17 Pro chip"
                        ]
                    },
                    "ProductInfo": {
                        "Color": {
                            "DisplayValue": "Natural Titanium"
                        },
                        "Size": {
                            "DisplayValue": "256 GB"
                        }
                    }
                },
                "Images": {
                    "Primary": {
                        "Large": {
                            "URL": "https://m.media-amazon.com/images/...",
                            "Height": 500,
                            "Width": 500
                        }
                    },
                    "Variants": [...]
                },
                "Offers": {
                    "Listings": [
                        {
                            "Price": {
                                "DisplayAmount": "$1,199.00",
                                "Amount": 1199.00,
                                "Currency": "USD"
                            },
                            "SavingBasis": {
                                "Amount": 1199.00
                            }
                        }
                    ]
                },
                "CustomerReviews": {
                    "StarRating": {
                        "DisplayValue": "4.7",
                        "Value": 4.7
                    },
                    "Count": 15234
                }
            }
        ]
    }
}

关键字段说明：
    
    
    
    
    
        表格

 

• 单次最多查询 10 个 ASIN
• ItemSearch 单次最多返回 100 条（10 页 × 10 条）
• 价格不含运费，如需计算"落地价"，需遍历 Offers 中的每个报价，将商品价格 + 运费取最小值
• 180 天内无联盟成交的账号，API 权限会被暂停

三、SP-API Catalog Items API：卖家级全量数据

如果你的业务是亚马逊卖家运营、ERP 同步、竞品监控、品牌分析，必须使用 SP-API。这是亚马逊面向卖家的官方开发者接口，数据最全、权限最严。

3.1 接口基础信息

3.2 核心请求参数

3.3 完整调用示例（Python）

SP-API 的认证比 PA-API 更复杂，需要 LWA Token + AWS SigV4 双重签名：

import requests
import boto3
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
import json

# 配置
LWA_CLIENT_ID = 'YOUR_LWA_CLIENT_ID'
LWA_CLIENT_SECRET = 'YOUR_LWA_CLIENT_SECRET'
REFRESH_TOKEN = 'YOUR_REFRESH_TOKEN'
AWS_ACCESS_KEY = 'YOUR_AWS_ACCESS_KEY'
AWS_SECRET_KEY = 'YOUR_AWS_SECRET_KEY'
ROLE_ARN = 'YOUR_IAM_ROLE_ARN'  # 如使用 IAM Role
REGION = 'us-east-1'
MARKETPLACE_ID = 'ATVPDKIKX0DER'  # 美国站

def get_lwa_access_token():
    """获取 LWA Access Token"""
    url = 'https://api.amazon.com/auth/o2/token'
    payload = {
        'grant_type': 'refresh_token',
        'refresh_token': REFRESH_TOKEN,
        'client_id': LWA_CLIENT_ID,
        'client_secret': LWA_CLIENT_SECRET
    }
    response = requests.post(url, data=payload)
    return response.json()['access_token']

def get_catalog_item(asin, access_token):
    """
    调用 SP-API Catalog Items API 获取商品详情
    """
    endpoint = f'https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items/{asin}'
    
    params = {
        'marketplaceIds': MARKETPLACE_ID,
        'includedData': 'images,price,description,attributes,salesRanks',
        'locale': 'en_US'
    }
    
    # 构建 AWS SigV4 签名请求
    request = AWSRequest(method='GET', url=endpoint, params=params)
    request.headers.add_header('x-amz-access-token', access_token)
    request.headers.add_header('x-amz-date', boto3.utils.datetime.datetime.utcnow().strftime('%Y%m%dT%H%M%SZ'))
    
    # 使用 boto3 的 SigV4Auth 签名
    credentials = boto3.Session(
        aws_access_key_id=AWS_ACCESS_KEY,
        aws_secret_access_key=AWS_SECRET_KEY,
        region_name=REGION
    ).get_credentials()
    
    sigv4 = SigV4Auth(credentials, 'execute-api', REGION)
    sigv4.add_auth(request)
    
    # 发送请求
    response = requests.get(endpoint, params=params, headers=dict(request.headers))
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f"请求失败: {response.status_code}, {response.text}")
        return None

# 调用示例
token = get_lwa_access_token()
product = get_catalog_item('B08N5WRWNW', token)
print(json.dumps(product, indent=2))

3.4 返回数据结构解析

SP-API 返回的商品数据比 PA-API 丰富得多，核心字段如下 ：

{
    "asin": "B08N5WRWNW",
    "attributes": {
        "title": [{"value": "Apple iPhone 15 Pro Max (256 GB) - Natural Titanium"}],
        "brand": [{"value": "Apple"}],
        "bullet_point": [
            {"value": "6.7-inch Super Retina XDR display"},
            {"value": "A17 Pro chip with 6-core GPU"}
        ],
        "item_dimensions": [{
            "height": {"value": 6.33, "unit": "inches"},
            "width": {"value": 3.06, "unit": "inches"}
        }],
        "color": [{"value": "Natural Titanium"}],
        "size": [{"value": "256 GB"}]
    },
    "images": {
        "primary": {
            "large": {
                "url": "https://m.media-amazon.com/images/...",
                "height": 500,
                "width": 500
            }
        },
        "variants": [...]
    },
    "dimensions": [...],
    "productTypes": [...],
    "salesRanks": [
        {
            "marketplaceId": "ATVPDKIKX0DER",
            "classificationRanks": [
                {
                    "classificationId": "7072561011",
                    "title": "Cell Phones",
                    "link": "https://www.amazon.com/...",
                    "rank": 3
                }
            ]
        }
    ],
    "summaries": [...],
    "relationships": {
        "variations": [
            {
                "asin": "B0BSHF7WHW",
                "color": "Blue Titanium"
            }
        ]
    }
}

关键字段说明：
    
    
 

四、批量查询与搜索接口

4.1 PA-API 批量查询

PA-API 的 GetItems 支持单次最多 10 个 ASIN 批量查询：

payload = {
    'ItemIds': ['B08N5WRWNW', 'B0BSHF7WHW', 'B0C...'],  # 最多 10 个
    'Resources': [...],
    'PartnerTag': PARTNER_TAG,
    'PartnerType': 'Associates',
    'Marketplace': 'www.amazon.com'
}
response = client.get_items(**payload)

4.2 PA-API 关键词搜索

SearchItems 支持按关键词搜索商品列表 ：

payload = {
    'Keywords': 'wireless earbuds',
    'SearchIndex': 'Electronics',
    'ItemCount': 10,
    'Resources': [...],
    'PartnerTag': PARTNER_TAG,
    'PartnerType': 'Associates',
    'Marketplace': 'www.amazon.com'
}
response = client.search_items(**payload)

注意：ItemSearch 有硬性的 100 条结果上限（10 页 × 10 条）。如需突破限制，可采用：

• 遍历子类目 BrowseNode
• 按价格区间分段查询
• 按品牌分别查询
• 多排序方式去重合并

4.3 SP-API 批量查询

SP-API 的 searchCatalogItems 支持按关键词、品牌、类目等条件搜索，返回商品列表后再逐个调用 getCatalogItem 获取详情。

五、第三方数据服务商：当官方 API 不够用

亚马逊官方 API 有严格的权限门槛和频率限制，很多场景下需要借助第三方数据服务商 ：

• 需要历史价格/排名数据 → Keepa
• 需要销量估算和选品 → Jungle Scout / Helium 10
• 需要评论情感分析 → 各平台基本都有
• 注意合规性：第三方服务商的数据来源必须合法，避免使用黑产数据

六、六大业务场景落地指南

场景 1：跨境选品与竞品监控

• 接口： PA-API GetItems + Keepa 历史数据
• 逻辑： 监控目标 ASIN 的价格、BSR、评论数变化，发现市场机会
• 频率： 价格/BSR 建议每日采集，评论数可每周汇总

场景 2：导购返利与内容电商

• 接口： PA-API GetItems / SearchItems
• 核心字段： DetailPageURL（含联盟追踪参数）、Offers.Listings.Price、Images
• 注意： 必须使用含 PartnerTag 的推广链接，否则无法追踪佣金

场景 3：ERP 商品中台同步

• 接口： SP-API getCatalogItem
• 核心字段： attributes、images、relationships.variations
• 逻辑： 将亚马逊商品数据标准化为内部 SKU 模型，统一供给多平台

场景 4：价格监控与预警系统

• 接口： PA-API GetItems（批量）或 Keepa API
• 逻辑： 建立价格基线，促销价低于阈值时触发告警
• 注意： PA-API 价格不含运费，如需"落地价"需额外计算

场景 5：多平台铺货（亚马逊 → 独立站 / 其他平台）

• 接口： SP-API getCatalogItem + PA-API GetItems
• 注意点：图片需下载转存自有 CDN（亚马逊图片 URL 有防盗链）属性需映射到目标平台类目五点描述（Bullet Point）需清洗格式

场景 6：品牌分析与反跟卖监控

• 接口： SP-API getCatalogItem + Reports API
• 逻辑： 监控自有品牌 ASIN 的卖家数量、价格分布、Buy Box 占比

七、踩坑清单与最佳实践

1. 权限申请是最大门槛

• PA-API： 必须完成 180 天内 3 笔联盟成交，否则 API 会被暂停
• SP-API： 必须拥有亚马逊卖家账户或通过开发者审核，IAM 角色配置复杂，建议参考官方 IAM 配置文档

2. AWS Signature V4 签名容易出错

• 时间戳必须使用 UTC 时间，格式为 YYYYMMDD'T'HHMMSS'Z'
• x-amz-date 与签名中的日期必须一致
• 建议使用 AWS SDK（boto3）自动生成签名，不要手写

3. 图片处理

• 亚马逊图片 URL 有时效性，且部分域名有防盗链
• 跨境铺货场景必须下载图片到自有对象存储（S3 / OSS / COS）
• 注意图片版权，避免侵权风险

4. 缓存与限流策略

• PA-API 有请求配额限制（免费层约每秒 1~5 次），高频场景必须做缓存
• 价格/库存建议缓存 15~30 分钟，商品基础信息可缓存 2~24 小时
• 批量查询优先用 GetItems（单次 10 个 ASIN），减少请求次数

5. 多站点适配

• 不同站点的 Marketplace 和 marketplaceIds 不同：美国站：www.amazon.com / ATVPDKIKX0DER英国站：www.amazon.co.uk / A1F83G8C2ARO7P日本站：www.amazon.co.jp / A1VC38T7YXB528
• 多站点运营时，需维护站点映射表

6. 异常处理

• ASIN 无效或商品下架时，接口返回 InvalidParameterValue 或空 Items 数组
• 必须做好降级策略：接口异常时读取缓存数据
• 429 限流时，按 Retry-After 头等待后重试

7. 合规红线

• 禁止爬虫： 亚马逊 robots.txt 明确禁止商业爬虫，且 2024 年已有"搬家软件"爬取数据被判不正当竞争的案例
• 数据缓存限制： PA-API 要求缓存数据不超过 24 小时
• 推广链接规范： 必须使用含 PartnerTag 的官方推广链接，禁止篡改或隐藏追踪参数

八、总结：如何选择适合你的接口？

如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。