App Store Connect API
App Store Connect 供应商编号与 salesReports API
向 App Store Connect API 请求任何销售报告,都需要一个大多数开发者从未留意过的编号:供应商编号。下面介绍它在哪里、哪种密钥可以使用它,以及如何把 `GET /v1/salesReports` 变成真正可用的分国家或地区销售数据。
在哪里找到 App Store Connect 供应商编号
供应商编号位于“付款和财务报告”中。登录 App Store Connect,打开“付款和财务报告”,选择页面顶部的“报告”,编号就显示在左上角的“法定实体名称”下方。API 要求以 filter[vendorNumber] 的形式传入(Apple 帮助)。
- 使用账户持有人、管理员或财务角色登录 App Store Connect——这些是 Apple 为“付款和财务报告”列出的角色。
- 打开“付款和财务报告”。
- 选择页面顶部的“报告”。
- 在左上角的“法定实体名称”下方读取供应商编号并复制。
还有两个捷径。如果你曾在“趋势 → 销售与趋势报告”中下载过销售报告,供应商编号就在文件名里:每日摘要文件的命名为 S_D_<vendor number>_<date>,例如 S_D_80012345_20130919(报告文件名)。如果你只有销售角色,请让拥有管理员或财务角色的人帮你查看,因为它显示在财务页面上。
不止一个供应商编号
供应商名称旁边的菜单可能会列出多个供应商编号。更改法定实体名称时,Apple 会分配一个新编号;Apple News+ 或 Apple Arcade 协议则有各自独立的编号。报告按供应商编号拆分,所以更改法定名称之后,新的销售需要用新编号,历史数据则需要用旧编号。
哪些角色可以读取销售报告
这里涉及两种不同的权限:查看供应商编号(付款和财务报告)和读取“销售与趋势”。下载报告的 API 密钥需要的是后者。以下内容来自 Apple 的角色权限和帮助页面:
| 角色 | 销售与趋势报告 | 付款和财务报告 | 修改价格 |
|---|---|---|---|
| 管理员 | 是 | 是 | 是 |
| 财务 | 是 | 是 | 否 |
| 销售 | 是 | 否 | 否 |
| App 管理 | Apple 未列出 | 否 | 是 |
| 开发者、市场营销、客户支持 | 否 | 否 | 否 |
对于交给第三方、只用于分析报告的密钥,Apple 建议使用销售角色(其 API 文档称之为“销售和报告”):它可以调用 GET /v1/salesReports,但不能调用财务报告端点(Apple 的说明)。如果一个密钥既要读取销售数据又要修改价格,唯一同时具备这两种能力的密钥角色是管理员。另一种做法是使用两个密钥——App 管理用于定价,销售用于报告——如果你的工具支持,这样更清晰。两者的创建方法见创建 API 密钥。
销售与趋势报告类型
GET /v1/salesReports 提供所有可下载的“销售与趋势”报告。每种类型只接受特定的子类型、频率和版本组合,其他组合都会报错。有效组合来自 Apple 的端点参考:
| reportType | reportSubType | frequency | version |
|---|---|---|---|
SALES | SUMMARY | DAILY, WEEKLY, MONTHLY, YEARLY | 1_0 |
PRE_ORDER | SUMMARY | DAILY, WEEKLY, MONTHLY, YEARLY | 1_0 |
SUBSCRIPTION | SUMMARY | DAILY | 1_3 |
SUBSCRIPTION_EVENT | SUMMARY | DAILY | 1_3 |
SUBSCRIBER | DETAILED | DAILY | 1_3 |
SUBSCRIPTION_OFFER_CODE_REDEMPTION | SUMMARY | DAILY | 1_0 |
WIN_BACK_ELIGIBILITY | SUMMARY | DAILY | 1_0 |
NEWSSTAND | DETAILED | DAILY, WEEKLY | 1_0 |
FIRST_ANNUAL | DETAILED / SUMMARY | DAILY / YEARLY | 1_0 |
要按国家或地区查看销售,你需要的是 SALES / SUMMARY:汇总了 App 和 App 内购买项目的单位数、价格和收益,每个产品、国家或地区、价格和交易类型一行。每日频率最有用,因为任何时间段都可以由天数据重建,而要观察价格变动的效果,需要的正是按天的数据。
用 GET /v1/salesReports 下载销售报告
| 参数 | 是否必填 | 每日销售报告的取值 | 说明 |
|---|---|---|---|
filter[vendorNumber] | 是 | 85012345(你自己的) | 来自“付款和财务报告”。 |
filter[reportType] | 是 | SALES | 其他类型见上表。 |
filter[reportSubType] | 是 | SUMMARY | 必须与报告类型匹配。 |
filter[frequency] | 是 | DAILY | DAILY、WEEKLY、MONTHLY 或 YEARLY。 |
filter[reportDate] | 否 | 2026-11-09 | Apple 的文档写明格式为 YYYY-MM-DD,并说明 DAILY 不要求日期。仍建议传入日期,这样你知道拿到的是哪一天。 |
filter[version] | 否 | 1_0 | Apple 为该报告类型列出的版本。 |
- 创建一个具有管理员、财务或销售角色的团队 API 密钥,并保存好它的 Issuer ID、Key ID 和
.p8文件。 - 用该密钥签发 JWT(生成令牌)。对于大多数请求,Apple 会拒绝有效期超过 20 分钟的令牌,所以每批请求都要生成一个新的。
- 请求当天的报告:
GET https://api.appstoreconnect.apple.com/v1/salesReports?filter[frequency]=DAILY&filter[reportType]=SALES&filter[reportSubType]=SUMMARY&filter[vendorNumber]=85012345&filter[reportDate]=2026-11-09&filter[version]=1_0,并带上Authorization: Bearer <token>和Accept: application/a-gzip。如果你的 HTTP 客户端不会自动处理,请对方括号进行 URL 编码。 - 200 响应的正文是 gzip(
application/a-gzip)。需要解压——使用 curl 时,先保存为文件,再对其运行gunzip。 - 现在你得到的是以制表符分隔的文本:一行表头,之后每个产品、国家或地区、价格和交易类型各占一行。请按表头名称而不是位置来解析列。
- 保存当天的数据。Apple 的每日报告只保留一年,所以任何想做同比的数据都需要你自己保存。
- 对需要的每一天重复上述步骤,并控制节奏:每个响应都带有
X-Rate-Limit头,显示你每小时剩余的请求数(速率限制)。
每周、每月和每年的报告工作方式相同,只是频率不同。Apple 文件名示例中,每周报告以星期日标注日期,而每月和每年的文件只带月份或年份,这可以帮你核对收到的是哪个周期。请记住,把 30 个每日文件相加,得到的是一个可以任意切分的月度数据;而月度文件则无法还原出每一天。
文件格式与关键列
销售摘要报告字段参考记录了每一列(它描述的是版本 1_3 的布局;Apple 会随时间增加列,这是按表头名称匹配的另一个原因)。按国家或地区统计销售所需的列如下:
| 列 | 含义 | 用途 |
|---|---|---|
| Apple Identifier | App 或 App 内购买项目的 Apple ID | 与 API 中的产品关联 |
| SKU / Parent Identifier | 你的 SKU;对于 App 内购买项目,Parent Identifier 是所属 App 的 SKU | 把 App 内购买项目归到其所属的 App 下 |
| Title | 下载行显示 App 名称,App 内购买项目行显示产品 ID | 标签 |
| Product Type Identifier | 交易类型,例如 1F 或 IAY | 区分下载、购买、更新和重新下载 |
| Units | 汇总的单位数;退款为负数 | 统计下载量和购买数 |
| Developer Proceeds | 扣除税费和 Apple 佣金后,你每个单位获得的金额 | 收益 = Units × Developer Proceeds |
| Customer Price / Customer Currency | 向客户收取的每单位价格及其货币 | 核对用户实际支付的价格 |
| Country Code | 购买所在 App Store 国家或地区的两位代码 | 按国家或地区拆分 |
| Currency of Proceeds | Developer Proceeds 数值所用的货币 | 比较各国家或地区之前先换算 |
| Subscription / Period | 新订阅或续订,以及订阅时长 | 区分新订阅者与续订 |
产品类型标识符用于对行分类(完整列表):1、1F、1T 和 F1 是 App 下载,无论免费还是付费;3 和 3F 是重新下载;7、7F、7T 和 F7 是更新;IA1、IA9、IAY、FI1 及其 -M 变体是 App 内购买项目和订阅;IA3 是恢复的非消耗型项目。
- Developer Proceeds 是每个单位的金额。把各行相加之前,先乘以 Units。
- 退款的 Units 为负数而 Developer Proceeds 为正数,所以 Units × Developer Proceeds 会正确地把它们减掉。
- 统计下载量之前,先去掉更新和重新下载——它们是免费的,数量通常远超真实下载。
- 同一产品和国家或地区可能出现在多行中(不同价格、设备、优惠码)。把它们加起来。
- 每一天按太平洋时间的午夜到午夜计算,而不是 UTC。
- 金额为本地货币。给国家或地区排名之前,请用同一套汇率换算;按国家或地区看销售介绍了如何进行公平的比较。
报告何时可用、保留多久
来自 Apple 的报告可用时间页面:每日报告在次日提供,每周报告在星期一提供,每月报告在月末五天后提供,每年报告在年末六天后提供,通常在太平洋时间上午 8 点之前。每日、每周和每月报告保留一年;每年报告保留十年。只有当某个时间段内至少售出一个 App 单位时,才会有销售摘要报告,所以冷清的一天就是没有文件。
salesReports 的常见错误
| 响应 | 通常的含义 | 处理方法 |
|---|---|---|
400 PARAMETER_ERROR.REQUIRED | 缺少必需的筛选条件,例如“The parameter 'filter[vendorNumber]' is required but was not provided” | 传入全部四个必填筛选条件。 |
| 400(其他) | Apple 不提供的组合——子类型、频率或版本与报告类型不匹配 | 对照上面的允许值表检查你的取值。 |
401 NOT_AUTHORIZED | 令牌格式错误、已过期,或使用了已撤销的密钥签名 | 生成新令牌;检查 Key ID、Issuer ID 和 .p8 是否匹配。 |
| 403 | 该密钥的角色无法读取销售报告 | 使用具有管理员、财务或销售角色的密钥。 |
| 404 | 该日期没有报告:尚未发布、当天没有销量,或已超出 Apple 的保留期限 | 视为“没有数据”,稍后重试近期的日期。 |
| 429 | 该密钥已达到每小时速率限制 | 退避后再继续;把历史数据的下载分散到不同时间。 |
500 UNEXPECTED_ERROR | Apple 服务器出错。当我们发送的供应商编号不属于该密钥所在团队时,返回的就是它,而不是明确的提示信息 | 重试一次;如果仍然出现,首先仔细核对供应商编号。 |
RepriceCat 如何使用你的供应商编号
RepriceCat 用你的 App Store Connect 密钥修改价格;有了你的供应商编号,它还能看到这些价格带来的效果。在“设置 → 销售报告”中添加即可。你的密钥需要具有管理员、财务或销售角色才能读取报告——如果同一个密钥还要修改价格,则需要管理员。此后 RepriceCat 会下载 Apple 的每日 SALES / SUMMARY 报告,每天只下载一次,并且只保留每个产品和国家或地区的每日汇总。更新和重新下载会被排除。
- 销售页面:按国家或地区显示单位数、下载量、购买数、收益(按当前汇率折算为 USD)、占比和趋势,附带世界地图、每日和按星期几的图表,并可按 App 和产品筛选。
- 定价提示,例如下载多但购买少的国家或地区,或购买频率远高于平均水平的国家或地区。
- 在“活动”中查看每次价格变动的影响:按产品和国家或地区显示变动前后的单位数和收益。
- 实验:在几个国家或地区修改价格,其余作为对照,然后保留或回滚结果(如何进行价格测试)。
如果你不想自己维护下载与解析的脚本,可以对比 RepriceCat 与 API 脚本,或免费体验一个月。
常见问题
在 App Store Connect 中哪里能找到供应商编号?
打开“付款和财务报告”,选择顶部的“报告”,在左上角的“法定实体名称”下方读取编号。它也出现在你下载过的任何销售报告的文件名中,例如 S_D_80012345_20130919。
供应商编号与我的 Team ID 或 App 的 Apple ID 是同一个吗?
不是。供应商编号与“付款和财务报告”中的法定实体相关联。Team ID 和 App 的 Apple ID 是不同的标识符,不能用作 filter[vendorNumber]。
API 密钥需要什么角色才能下载销售报告?
管理员、财务或销售。App 管理可以修改价格,但不在 Apple 为“销售与趋势”列出的角色之中,所以同时能做这两件事的单个密钥需要管理员角色。
为什么 GET /v1/salesReports 返回 404?
该日期没有报告:当天尚未发布、当天没有销量,或日期早于 Apple 保留每日报告的一年期限。视为没有数据,稍后重试近期的日期。
App Store 销售报告可以下载多久以前的?
每日、每周和每月报告在可用后保留一年,每年报告保留十年。如果需要更长的每日历史数据,请自行保存文件。
每日销售报告应该使用哪个版本?
Apple 的端点参考为 SALES 和 SUMMARY 列出的版本是 1_0。请按列名而不是位置来解析文件,因为 Apple 会在不同布局版本之间增加列。