报告API

开发者可以使用报告API下载销售、收入和订阅报表。

• 创建安全配置文件
• 将安全配置文件映射到API
• 请求LWA访问令牌
  • 1.发送令牌请求
  • 2.保存响应
  • 3.处理任何错误响应
• 如何使用访问令牌
• 报告API URL
• 请求报表文件URL
  • 语法
  • 示例
  • 错误
• 使用S3 URL下载报表
  • 错误消息：
• 报告API常见问题解答
• 销售报表字段
  • 收入和付款报表字段
  • 订阅报表字段
  • 订阅概览可下载报表字段
  • 市场信息
• API数据安全

要使用开发者控制台API，您需要创建安全配置文件并将该安全配置文件映射到API。安全配置文件是用于为API访问生成访问令牌的机制。

创建安全配置文件

要创建安全配置文件，请执行以下步骤：

1. 登录亚马逊开发者控制台账户。如果您还没有账户，系统将提示您创建账户。
2. 在主导航中，单击应用与服务。
3. 单击子菜单中的API访问。

4. 单击API的名称。

   

5. 单击创建新的安全配置文件按钮。
6. 针对新配置文件输入“安全配置文件名称”和“安全配置文件描述”，然后单击保存。
7. 保存您的客户端ID和客户端密钥（在Web设置选项卡中），因为您需要此信息才能访问销售报告API。

   

将安全配置文件映射到API

要将安全配置文件映射到API，请执行以下步骤：

1. 返回到API访问页面。
2. 单击API名称以选择API。
3. 从下拉列表中选择新的安全配置文件。
4. 选择附加以将安全配置文件与此API关联。API名称和附加的安全配置文件将添加到Security Profile(s) in use（使用中的安全配置文件）面板。

   

现在可以使用客户端ID和客户端密钥请求Login With Amazon (LWA) 访问令牌。

请求LWA访问令牌

借助客户端ID和客户端密钥，按照以下步骤使用Login With Amazon API请求Login with Amazon访问令牌：

1.发送令牌请求

将POST请求发送到https://api.amazon.com/auth/o2/token，其中包含以下标头和内容：

• 标头： Content-Type: application/x-www-form-urlencoded
• 内容：
  • client_id： 在创建安全配置文件的步骤7中保存的客户端ID。
  • client_secret： 在创建安全配置文件的步骤7中保存的客户端密钥。
  • grant_type： 设置为client_credentials。
  • scope： 将值设置为appstore::apps:readwrite（对于报告API，则设置为adx_reporting::appstore:marketer）。

示例JSON内容：

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.<客户端ID>",
    "client_secret": "<客户端密钥>",    
    "scope": "appstore::apps:readwrite"
}

示例cURL请求：

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.<客户端ID>&client_secret=<客户端密钥>&scope=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

2.保存响应

响应如下所示：

{
    "access_token": "Atc|MAEBI...",
    "scope": "appstore::apps:readwrite",
    "token_type": "bearer",
    "expires_in": 3600
}

• access_token： 访问令牌。
• expires_in： 访问令牌到期之前的秒数。
• scope： 将为appstore::apps:readwrite（对于报告API，则为adx_reporting::appstore:marketer）。
• token_type： 将始终为bearer。

3.处理任何错误响应

如果令牌请求导致了错误，则响应消息正文包含以下错误消息之一：

如何使用访问令牌

获得有效的访问令牌后，请向具有Authorization标头集的报告API发送请求。Authorization标头的值为Bearer <访问令牌>，其中，<访问令牌>是来自请求LWA访问令牌的响应中的access_token字段的值。该访问令牌是一个以“Atc|”开头的长字符串。

示例cURL请求：

curl -v -X GET "<有关URL格式请参看下面>"   -H  "Authorization: Bearer Atc|MAEBIKfsULrH7jSzvJTV8UmiHWr9M86O3JRmv4t1hqoCBriSMEP5Gsey_FiBxteZ8oxGd6abGuOFga8fwnMhmSD_Sg4MI4odXLPgB2IVs8M1uswjuWjnsMcvehpWvf9tzQT8HTWiBigInJLB8BrMg5J3O02hlTvcF441XxXDXthyj993COJ2u5swOTKjC_dcijiN8amuzrj32rh9Fr3CNgCpoZ0WqXnBhoHUVMYSOBV-owA5rI4-OfysXC71Zbtv1hb8igk"  

当该访问令牌到期时，请按照请求LWA访问令牌中的上述过程获取新访问令牌，并开始在您的请求中使用新访问令牌。如果您自上次请求访问令牌以来已超过一个小时，并且您开始收到403 Forbidden HTTP错误以及消息“Request is not authorized”（请求未获得授权），则可以确定访问令牌已到期。

报告API URL

使用以下内容作为发送报告API请求的基本URL：

developer.amazon.com

请求报表文件URL

您可以使用报告API下载以下文件：

• 单一销售或订阅报表文件
• 收入和付款报表文件
• 订阅概览报表文件

API请求将返回一个URL，您可以使用该URL从安全的S3存储位置下载文件。

语法

/api/appstore/download/report/sales/<year>/<month>

/api/appstore/download/report/earnings/<year>

/api/appstore/download/report/earnings/<year>/<month>

/api/appstore/download/report/subscription/<year>/<month>

/api/appstore/download/report/subscriptions_overview/<year>/<month>

参数

示例

以下示例显示了如何请求2024年4月的销售报表。

请求：

curl -v -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2024/04" -H "Authorization: Bearer Atc|MQEBIDdrcC586BxhFBdS7FQVS454oUO-fo90H5gUYVMZB1UVsPFoOPLj_zrpkf9BuMrx-PksU_qDJHL-PJ5suEQTigL1tv7A6AKlyoJJaoyzyzKhd0dwWw3LWUGrlxXxW459nJJH66F89GSBolrmlfuNONly8Cbts2Fy_KHI9YwvzwSVcgf_nvefss_H1O8tsvoYpORVuL8IXBrzT7bHxU0Xj5VjiaxDtU6N4oOQafefT8AcdN0IOYnh3Us8uEeeur3_OH473JwO3SjA4NRaS61Aq37UyhvM9pK3ccGOO5JoMkw1V9kDQQVhKiGWfCoTUBlaVkU"

响应：

https://appstore-adx-sales-reports-prod.s3.amazonaws.com/monthly/85923/40-4202/sales-2024-04.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180405T060912Z&X-Amz-SignedHeaders=host&X-Amz-Expires=299&X-Amz-Credential=AKIAJMFYXPVLQKTRRB7Q%2F20180405%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=adab43be54631565d330727383341d56989d129e4dea151411cf7a802b9e5e12

错误

如果令牌请求导致了错误，则响应消息正文包含以下错误消息之一：

使用S3 URL下载报表

报告API将返回一个S3 URL，您可以用来下载报表。

错误消息

您可能会从API收到以下错误消息之一：

Report Not Available（报表不可用）： 您尝试复制一个文件，但具有指定名称的文件在S3文件夹中不存在：致命错误： 调用HeadObject操作时出错 (403)： 禁止访问

User not authorized（用户未授权）： 如果您尝试在没有有效访问令牌的情况下使用报告API。

Server Unavailable（服务器不可用）： 如果您发送请求时API服务器不可用，或者您尝试下载报表时S3存储桶不可用，您将收到HTTP 404错误代码。

有关其他信息，请参阅S3错误响应。

报告API常见问题解答

问： 我可以使用API检索最早什么时候的报表？

可用的最早报表是2018年1月的。尚未提供2017年及更早年份的报表。

问： 如何删除安全配置文件？

只有管理员级别的用户才能删除安全配置文件。导航到应用和服务下的安全配置文件选项卡，选择并删除相应的安全配置文件。

问： 为什么cURL命令的范围被定义为营销员？

范围是API访问的必填字段。营销员被定义为销售报告API的默认范围。

问： 访问令牌和预签名S3 URL是否能永久使用？

不能，访问令牌的有效期只有1小时。预签名S3 URL的有效期只有5分钟。这些超时设定是出于安全考虑。

问： 安全配置文件客户端ID和客户端密钥是否能永久使用？

是。​在从开发者控制台中删除安全配置文件之前，它们始终可用。但是，为了确保安全，我们强烈建议您至少每6个月更新一次与API相关的安全配置文件。

问： 我的团队中有5个管理员。他们是否都能创建安全配置文件？ 如果是，那么是如何进行管理的？

是的，所有5个管理员都能创建安全配置文件。每个管理员都能查看所有安全配置文件（即使是其他管理员创建的配置文件）

销售报表字段

CSV文件是具有.csv文件扩展名的文本文件。CSV文件必须使用UTF-8编码，以支持本地化字符串。

CSV文件包含一个标题行，其中显示列标题。文件中的每个后续行包含一个报表项目的信息。“发票ID”字段为报表中的每个行项目定义了一个唯一标识符。

下表介绍了CSV文件中的每个条目（行）的字段：

注释

• 销售数据每24小时更新一次。如果要自动执行数据拉取，建议每24小时运行一次脚本以获取最新信息。请注意，报告的信息可能有最长48小时的延迟。
• API支持每秒最多3个请求。更频繁地进行API调用可能导致性能下降。
• 此文件中提供估计收入。它可能与您的月底收入报表不完全相符，该报表可能包含此处未列出的额外调整。
• 所有调整都显示在进行调整的月份，而不显示在原始交易发生的月份。
• 测试ASIN对“Title”（名称）和“Item Name”（项目名称）显示null值。这个已知问题将在未来的版本中得到修复。

收入和付款报表字段

CSV文件是具有.csv文件扩展名的文本文件。CSV文件必须使用UTF-8编码，以支持本地化字符串。

CSV文件包含一个标题行，其中显示列标题。文件中的每个后续行包含一个报告项目的信息。

下表介绍了CSV文件中的每个条目（行）的字段：

订阅报表字段

CSV文件是具有.csv文件扩展名的文本文件。CSV文件必须使用UTF-8编码，以支持本地化字符串。

CSV文件包含一个标题行，其中显示列标题。文件中的每个后续行包含一个报告项目的信息。

下表介绍了CSV文件中的每个条目（行）的字段：亚马逊市场、供应商SKU、订阅名称以及订阅持续时间是您在开发者控制台中配置该订阅时输入的值。

订阅概览可下载报表字段

CSV文件是具有.csv文件扩展名的文本文件。CSV文件必须使用UTF-8编码，以支持本地化字符串。

CSV文件包含一个标题行，其中显示列标题。文件中的每个后续行包含一个报告项目的信息。

下表介绍了CSV文件中的每个条目（行）的字段：

市场信息

下表显示了每个市场的国家/地区缩写和货币类型。

API数据安全

您可以通过报告API访问的所有数据均为亚马逊机密，且仅供开发者使用。

如果您向受信任的第三方授予API访问权限（以支持您的日常运营），则表示您同意在自己承担风险的条件下共享这些信息。亚马逊对共享此信息造成的任何损失或损害不承担任何责任。

如果您决定与第三方共享您的API访问权限，请遵循以下准则：

1. 为第三方创建一个专用安全配置文件。
2. 在安全配置文件名称中包含第三方企业名称（如ReportingAPI_<您的公司名称>_<第三方名称>）。
3. 在安全配置文件描述字段中，清楚地说明将使用安全配置文件的人员。

为了增强保护，我们强烈建议您每六个月更新一次安全配置文件（与销售报告API关联的所有安全配置文件）。

Last updated: 2025年8月22日