跳到内容

App Store Connect API

App Store Connect 供应商编号与 salesReports API

向 App Store Connect API 请求任何销售报告,都需要一个大多数开发者从未留意过的编号:供应商编号。下面介绍它在哪里、哪种密钥可以使用它,以及如何把 `GET /v1/salesReports` 变成真正可用的分国家或地区销售数据。

更新于 阅读约需 9 分钟

在哪里找到 App Store Connect 供应商编号

供应商编号位于“付款和财务报告”中。登录 App Store Connect,打开“付款和财务报告”,选择页面顶部的“报告”,编号就显示在左上角的“法定实体名称”下方。API 要求以 filter[vendorNumber] 的形式传入(Apple 帮助)。

  1. 使用账户持有人、管理员或财务角色登录 App Store Connect——这些是 Apple 为“付款和财务报告”列出的角色。
  2. 打开“付款和财务报告”。
  3. 选择页面顶部的“报告”。
  4. 在左上角的“法定实体名称”下方读取供应商编号并复制。

还有两个捷径。如果你曾在“趋势 → 销售与趋势报告”中下载过销售报告,供应商编号就在文件名里:每日摘要文件的命名为 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 的端点参考:

reportTypereportSubTypefrequencyversion
SALESSUMMARYDAILY, WEEKLY, MONTHLY, YEARLY1_0
PRE_ORDERSUMMARYDAILY, WEEKLY, MONTHLY, YEARLY1_0
SUBSCRIPTIONSUMMARYDAILY1_3
SUBSCRIPTION_EVENTSUMMARYDAILY1_3
SUBSCRIBERDETAILEDDAILY1_3
SUBSCRIPTION_OFFER_CODE_REDEMPTIONSUMMARYDAILY1_0
WIN_BACK_ELIGIBILITYSUMMARYDAILY1_0
NEWSSTANDDETAILEDDAILY, WEEKLY1_0
FIRST_ANNUALDETAILED / SUMMARYDAILY / YEARLY1_0

要按国家或地区查看销售,你需要的是 SALES / SUMMARY:汇总了 App 和 App 内购买项目的单位数、价格和收益,每个产品、国家或地区、价格和交易类型一行。每日频率最有用,因为任何时间段都可以由天数据重建,而要观察价格变动的效果,需要的正是按天的数据。

用 GET /v1/salesReports 下载销售报告

参数是否必填每日销售报告的取值说明
filter[vendorNumber]是85012345(你自己的)来自“付款和财务报告”。
filter[reportType]是SALES其他类型见上表。
filter[reportSubType]是SUMMARY必须与报告类型匹配。
filter[frequency]是DAILYDAILY、WEEKLY、MONTHLY 或 YEARLY。
filter[reportDate]否2026-11-09Apple 的文档写明格式为 YYYY-MM-DD,并说明 DAILY 不要求日期。仍建议传入日期,这样你知道拿到的是哪一天。
filter[version]否1_0Apple 为该报告类型列出的版本。
  1. 创建一个具有管理员、财务或销售角色的团队 API 密钥,并保存好它的 Issuer ID、Key ID 和 .p8 文件。
  2. 用该密钥签发 JWT(生成令牌)。对于大多数请求,Apple 会拒绝有效期超过 20 分钟的令牌,所以每批请求都要生成一个新的。
  3. 请求当天的报告: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 编码。
  4. 200 响应的正文是 gzip(application/a-gzip)。需要解压——使用 curl 时,先保存为文件,再对其运行 gunzip。
  5. 现在你得到的是以制表符分隔的文本:一行表头,之后每个产品、国家或地区、价格和交易类型各占一行。请按表头名称而不是位置来解析列。
  6. 保存当天的数据。Apple 的每日报告只保留一年,所以任何想做同比的数据都需要你自己保存。
  7. 对需要的每一天重复上述步骤,并控制节奏:每个响应都带有 X-Rate-Limit 头,显示你每小时剩余的请求数(速率限制)。

每周、每月和每年的报告工作方式相同,只是频率不同。Apple 文件名示例中,每周报告以星期日标注日期,而每月和每年的文件只带月份或年份,这可以帮你核对收到的是哪个周期。请记住,把 30 个每日文件相加,得到的是一个可以任意切分的月度数据;而月度文件则无法还原出每一天。

文件格式与关键列

销售摘要报告字段参考记录了每一列(它描述的是版本 1_3 的布局;Apple 会随时间增加列,这是按表头名称匹配的另一个原因)。按国家或地区统计销售所需的列如下:

列含义用途
Apple IdentifierApp 或 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 ProceedsDeveloper 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_ERRORApple 服务器出错。当我们发送的供应商编号不属于该密钥所在团队时,返回的就是它,而不是明确的提示信息重试一次;如果仍然出现,首先仔细核对供应商编号。

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 会在不同布局版本之间增加列。

试一试

从一个基准价格为每个国家/地区重新定价

价格档、自动对齐价格点、一张检查表、一次确认,全部通过 App Store Connect API 完成。首月免费,之后每个 App 每月 $1。