报告API
开发者可以使用报告API下载销售报表和订阅报表。
- 创建安全配置文件
- 将安全配置文件映射到API
- 请求LWA访问令牌
- 如何使用访问令牌
- 报告API URL
- 请求销售/订阅报表URL
- 使用S3 URL下载报表
- 报告API常见问题解答
- 销售报表字段
- API数据安全
要使用开发者控制台API，您需要创建安全配置文件并将该安全配置文件映射到API。安全配置文件是用于为API访问生成访问令牌的机制。
创建安全配置文件
要创建安全配置文件，请执行以下步骤：
- 登录亚马逊开发者控制台账户。如果您还没有账户，系统将提示您创建账户。
- 在主导航中，单击应用与服务。
- 单击子菜单中的API访问。
-
单击API的名称。
- 单击创建新的安全配置文件按钮。
- 针对新配置文件输入“安全配置文件名称”和“安全配置文件描述”，然后单击保存。
- 保存您的客户端ID和客户端密钥（在Web设置选项卡中），因为您需要此信息才能访问销售报告API。
将安全配置文件映射到API
要将安全配置文件映射到API，请执行以下步骤：
- 返回到API访问页面。
- 单击API名称以选择API。
- 从下拉列表中选择新的安全配置文件。
- 选择附加以将安全配置文件与此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=<客户端密钥>=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.处理任何错误响应
如果令牌请求导致了错误，则响应消息正文包含以下错误消息之一：
| 错误消息正文 | 详情 |
|---|---|
| {"error_description":"Client authentication failed", "error":"invalid_client"} | 密钥无效 |
| {"error_description":"The request has an invalid parameter : scope", "error":"invalid_scope"} | 范围值无效 |
| {"error_description":"The authorization grant type is not supported by the authorization server", "error":"unsupported_grant_type"} | 授权类型不正确 |
| {"error_description":"The Content-Type is not supported by the authorization server", "error":"invalid_request"} | content-type不受支持 |
如何使用访问令牌
获得有效的访问令牌后，请向具有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/subscription/<year>/<month>
参数
| <year> | 要下载的报表文件的四位数年份 |
| <month> | 报表文件的两位数月份值 |
示例
以下示例显示了如何请求2018年1月的销售报表。
请求：
curl -v -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2018/04" -H "Authorization: Bearer Atc|MQEBIDdrcC586BxhFBdS7FQVS454oUO-fo90H5gUYVMZB1UVsPFoOPLj_zrpkf9BuMrx-PksU_qDJHL-PJ5suEQTigL1tv7A6AKlyoJJaoyzyzKhd0dwWw3LWUGrlxXxW459nJJH66F89GSBolrmlfuNONly8Cbts2Fy_KHI9YwvzwSVcgf_nvefss_H1O8tsvoYpORVuL8IXBrzT7bHxU0Xj5VjiaxDtU6N4oOQafefT8AcdN0IOYnh3Us8uEeeur3_OH473JwO3SjA4NRaS61Aq37UyhvM9pK3ccGOO5JoMkw1V9kDQQVhKiGWfCoTUBlaVkU"
响应：
https://appstore-adx-reporting.s3.amazonaws.com/85923/sales/sales_2018_01.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
错误
如果令牌请求导致了错误，则响应消息正文包含以下错误消息之一：
| 错误 | 详情 |
|---|---|
| {"Message":"Request is not authorized."} | 访问密钥不正确，或请求的报表超出范围（例如，如果营销员请求付款/代理报表）。 |
| {"Message":"Unable to fetch the request scope for uri = (URL Entered) and verb = GET"} | URL或方法无效。 |
使用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文件包含一个标题行（其中显示列标题）。文件中的每个后续行包含一个报表项目的信息。“Invoice ID”（发票ID）字段为报表中的每个行项目定义了一个唯一标识符。
下表介绍了CSV文件中的每个条目（行）的字段：
| 字段 | 类型 | 描述 | 示例 |
|---|---|---|---|
| Marketplace | 字符串 | 亚马逊市场 | Amazon.com |
| Country/Region Code | 字符串 | 交易来源地的标准两位ISO国家/地区代码。请参阅此列表 | US |
| Invoice Id | 字符串 | 发票的唯一编号。对于2017年及更早的汇总数据，此字段设置为NA | 8dd921637-b092f385a7ee4- 62c6494b3ed702 |
| Transaction Id | 整数 | 与此交易关联的唯一ID。对于2017年及更早的汇总数据，此字段设置为NA，因为销售信息包括给定日内的所有交易 | 21854260140446 |
| Transaction Time | 字符串 | 交易的日期和时间。格式为MM/DD/YY HH:MM:SS XST，其中小时范围为00-23。XST是与交易的市场对应的时区。对于2017年及更早的数据，此字段表示销售日期。 | 05/21/18 14:39 PST |
| Transaction Type | 字符串 | 交易类型为Charge（收费）、Refund（退款）、（退单）Chargeback或（退单撤销）Chargeback reversal | Charge |
| Adjustment | 是或否 | 如果交易是一个调整，此字段将设置为Yes（是）。对于2017年及更早的数据，如果交易类型为Refund（退款），此字段将显示null值。 | 是 |
| ASIN | 字母数字字符串 | 应用/应用内项目/订阅的亚马逊标准识别码(ASIN)。 | C00006M4PF |
| Vendor SKU | 字符串 | 由最多150个字符组成的字符串，其中可包含字符a-z、A-Z、0-9、下划线、句点和短划线。该SKU区分大小写。 | com.gamevendor.fungame |
| Title | 字符串 | 应用或游戏的名称。 | Smashemup Truck Game |
| Item Name | 字符串 | 应用、游戏、订阅、应用内项目或游戏内项目的名称。 | Smashemup Truck Game |
| Item Type | 字符串 | 商品的类型。值包括Subscription（订阅）、In-App（应用程序内商品）、Game（游戏）、In-Game（游戏内商品）或Application（应用）。Application是指应用购买项目，它是亚马逊账户独有的新应用安装。Application商品不包括应用更新。 | 应用 |
| In-App Subscription Term | 字符串 | 订阅期限。该期限可以是Weekly（每周）、BiWeekly（每两周）、Monthly（每月）、BiMonthly（每两个月）、Quarterly（每季度）、SemiAnnually（每半年）或Annually（每年）。仅当商品类型为“订阅”时，此字段才适用。 此字段不适用于Twitch。 |
Weekly |
| In-App Subscription Status | 字符串 | 状态可以是TRIAL（试用）、PAID（付费）、Introductory Price - All Customers（试销价 - 所有客户）或Promotional Price - Lapsed Customers（促销价格 - 到期客户）。仅当商品类型为“订阅”时，此字段才适用。有关详细信息，请参阅应用内订阅状态。 此字段不适用于Twitch。 |
TRIAL |
| Units | 整数 | 此交易中包含的单位数。 | 1 |
| Usage Time | 字符串 | Underground应用的使用时间（以秒为单位）。此字段仅适用于亚马逊应用商店Underground产品。要计算单位数，请将使用时间除以60。例如，1200的使用时间是20个单位。 此字段不适用于Twitch。 |
1200 |
| Marketplace Currency | 字符串 | 市场决定了交易的货币。请参阅销售市场时区表。 | USD |
| Sales Price | 市场货币 | 客户看到的折后销售价格（不包括销售税）。对于Underground应用，销售价格表示基于应用使用分钟数的收入。Underground应用的销售额和收入相同。将显示原始商品的销售价格以进行调整。实际调整金额或绝对退款金额可能与销售价格不同（如部分退款）。对于退款和退单（交易类型 - 退款、退单），对应的销售价格将为负值。 | 4.99 |
| Estimated Earnings | 市场货币 | 从此交易中扣除亚马逊版税后的估算收入。对于调整和退款，收入将基于调整金额或退款金额来显示。在涉及2019年11月之后收入的报表中，从供应商账户中扣除的退款将显示为负值。 | 3.49 |
| App User ID | 字符串 | 交易的唯一客户标识。App User ID不适用于以下情景：
|
hQygC+MjonyR2Z0TMY03nyxeVxqIHq3+rK39TGzhkk0= |
| Receipt ID | 字符串 | 交易的唯一收据标识。Receipt ID不适用于以下情景：
|
EgL-HstEAXhMfTuQ5_NkhQicjp_sRpJ5Lic78cF-3HY=:1:13 |
| Digital Order ID | 字符串 | 交易的唯一订单标识。 | d01-6680198-0475238 |
| 设备类型 | 字符串 | 客户购买时使用的设备类型。类型类别“Others”（其他）包括在未分类的设备类型上进行的应用购买（例如，通过网络进行的应用购买）。 | Fire TV |
说明
- 销售数据每24小时更新一次。如果要自动执行数据拉取，建议每24小时运行一次脚本以获取最新信息。请注意，报告的信息可能有最长48小时的延迟。
- API支持每秒最多3个请求。更频繁地进行API调用可能导致性能下降。
- 此文件中提供估计收入。它可能与您的月底收入报表不完全相符，该报表可能包含此处未列出的额外调整。
- 所有调整都显示在进行调整的月份，而不显示在原始交易发生的月份。
- 测试ASIN对“Title”（名称）和“Item Name”（项目名称）显示null值。这个已知问题将在未来的版本中得到修复。
订阅报表字段
CSV文件是具有.csv文件扩展名的文本文件。CSV文件必须使用UTF-8编码，以支持本地化字符串。
CSV文件包含一个标题行（其中显示列标题）。文件中的每个后续行包含一个报表项目的信息。
下表介绍了文件中的每个条目（行）的字段。请注意，亚马逊市场、供应商SKU、订阅名称和订阅持续时间是您在开发者控制台中配置此订阅时输入的值：
| 字段 | 描述 | 示例 |
|---|---|---|
| Date | 此记录的订阅数据是在此日期收集的。 | 12/29/18 |
| Marketplace | 与此记录中的数据关联的亚马逊市场。 | Amazon.com |
| App Title | 订阅针对具有此名称的应用。 | My Test App |
| ASIN | 订阅的亚马逊标准识别码（ASIN）。 | C00006M4PF |
| Vendor SKU | 订阅的SKU。 | com.test.monthly |
| Subscription Title | 订阅的名称。 | 测试月度订阅 |
| Subscription Duration | 订阅的持续时间。 | 每月 |
| Subscription Type | 订阅类型的值为trial或paid。 | 付费 |
| Active | 指定日结束时(11:59 PM UTC)的有效订阅总数。 | 7261 |
| Started | 在指定日发起的订阅数 | 163 |
| Ended | 在指定日取消或结束而未续订的订阅数。 | 163 |
| Refunded | 在指定日退款的订阅数。 | 163 |
市场信息
下表显示了每个市场的国家/地区缩写和货币类型。
| 国家/地区 缩写 |
币种 缩写 |
币种 | Marketplace |
|---|---|---|---|
| AU | AUD | 澳元 | Amazon.com.au |
| BR | BRL | 巴西雷亚尔 | Amazon.com.br |
| CA | CAN | 加拿大元 | Amazon.ca |
| DE | EUR | 欧元 | Amazon.de |
| ES | EUR | 欧元 | Amazon.es |
| FR | EUR | 欧元 | Amazon.fr |
| GB | GBP | 英镑 | Amazon.co.uk |
| IN | INR | 印度卢比 | Amazon.in |
| IT | EUR | 欧元 | Amazon.it |
| JP | JPY | 日元 | Amazon.co.jp |
| US | USD | 美元 | Amazon.com |
API数据安全
您可以通过报告API访问的所有数据均为亚马逊机密，且仅供开发者使用。
如果您向受信任的第三方授予API访问权限（以支持您的日常运营），则表示您同意在自己承担风险的条件下共享这些信息。亚马逊对共享此信息造成的任何损失或损害不承担任何责任。
如果您决定与第三方共享您的API访问权限，请遵循以下准则：
- 为第三方创建一个专用安全配置文件。
- 在安全配置文件名称中包含第三方企业名称（如
ReportingAPI_<您的公司名称>_<第三方名称>）。 - 在安全配置文件描述字段中，清楚地说明将使用安全配置文件的人员。
为了增强保护，我们强烈建议您每六个月更新一次安全配置文件（与销售报告API关联的所有安全配置文件）。
Last updated: 2023年12月13日