App Store Connect API
Vendor number в App Store Connect и API salesReports
Каждый запрос отчёта о продажах к API App Store Connect требует число, на которое большинство разработчиков ни разу не смотрели: vendor number. Здесь — где оно лежит, какой ключ может им пользоваться и как превратить `GET /v1/salesReports` в продажи по странам, с которыми действительно можно работать.
Где найти vendor number в App Store Connect
Ваш vendor number находится в разделе «Платежи и финансовые отчёты» (Payments and Financial Reports). Войдите в App Store Connect, откройте этот раздел, выберите «Отчёты» (Reports) в верхней части страницы — номер появится в левом верхнем углу под названием вашего юридического лица (Legal Entity Name). API ожидает его как filter[vendorNumber] (справка Apple).
- Войдите в App Store Connect с ролью Account Holder, Admin или Finance — это роли, которые Apple указывает для раздела «Платежи и финансовые отчёты».
- Откройте «Платежи и финансовые отчёты».
- Выберите «Отчёты» в верхней части страницы.
- Прочитайте vendor number под названием юридического лица в левом верхнем углу и скопируйте его.
Два коротких пути. Если вы хоть раз скачивали отчёт о продажах из раздела «Тренды» → «Отчёты о продажах и трендах», vendor number есть в имени файла: ежедневные сводные файлы называются S_D_<vendor number>_<date>, например S_D_80012345_20130919 (имена файлов отчётов). А если у вас только роль Sales, попросите того, у кого роль Admin или Finance, прочитать номер за вас: он показан на финансовой странице.
Если vendor number не один
В меню рядом с названием вашего поставщика может быть несколько vendor number. Apple выдаёт новый при смене названия юридического лица, а также отдельные номера для соглашений Apple News+ или Apple Arcade. Отчёты разделены по vendor number, поэтому после смены юридического названия вам понадобится новый номер для новых продаж и старый — для истории.
Какие роли читают отчёты о продажах
Здесь задействованы два разных права: видеть vendor number («Платежи и финансовые отчёты») и читать «Продажи и тренды». Ключу API, который скачивает отчёты, нужно второе. Из прав ролей и справочных страниц Apple:
| Роль | Отчёты «Продажи и тренды» | Платежи и финансовые отчёты | Изменение цен |
|---|---|---|---|
| Admin | Да | Да | Да |
| Finance | Да | Да | Нет |
| Sales | Да | Нет | Нет |
| App Manager | Apple не указывает | Нет | Да |
| Developer, Marketing, Customer Support | Нет | Нет | Нет |
Для ключа, который вы передаёте стороннему сервису, лишь анализирующему отчёты, Apple советует роль Sales (в документации API она называется Sales and Reports): такой ключ может вызывать GET /v1/salesReports, но не конечную точку финансовых отчётов (примечание Apple). Если один ключ должен и читать продажи, и менять цены, единственная роль ключа, которая умеет и то и другое, — Admin. Альтернатива — два ключа: App Manager для цен и Sales для отчётов; это аккуратнее, если ваш инструмент это поддерживает. Как создать любой из них, описано в руководстве создание ключа API.
Типы отчётов Sales and Trends
GET /v1/salesReports отдаёт все скачиваемые отчёты Sales and Trends. Каждый тип принимает только определённые сочетания подтипа, частоты и версии; всё остальное — ошибка. Допустимые сочетания из справочника по конечной точке от 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: агрегированные единицы, цены и выручка по приложениям и встроенным покупкам, одна строка на продукт, страну, цену и тип транзакции. Самая полезная частота — ежедневная: из дней можно собрать любой период, а дни нужны, чтобы увидеть эффект изменения цены.
Скачивание отчёта о продажах через 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 с ролью Admin, Finance или Sales и сохраните его 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. Закодируйте квадратные скобки в URL, если ваш HTTP-клиент этого не делает. - Тело ответа 200 — gzip (
application/a-gzip). Распакуйте его: с curl сохраните в файл и выполните над нимgunzip. - Теперь у вас текст с разделителями-табуляциями: строка заголовка, затем по строке на продукт, страну, цену и тип транзакции. Разбирайте столбцы по названию в заголовке, а не по позиции.
- Сохраните день. Apple хранит ежедневные отчёты только год, так что всё, что вы хотите сравнивать год к году, нужно сохранять у себя.
- Повторите для каждого нужного дня, не частя: в каждом ответе есть заголовок
X-Rate-Limitс оставшимся числом запросов в час (ограничения частоты запросов).
Еженедельные, ежемесячные и ежегодные отчёты работают так же, с другой частотой. В примерах имён файлов у Apple еженедельный отчёт датирован воскресеньем, а у ежемесячных и ежегодных файлов указан только месяц или год — это удобная проверка того, за какой период вы получили отчёт. Помните: сумма 30 ежедневных файлов даёт месяц, который можно разрезать как угодно; а месячный файл дней не даёт.
Формат файла и важные столбцы
В справочнике полей Summary Sales Report описан каждый столбец (описана версия макета 1_3; Apple со временем добавляет столбцы, и это ещё одна причина сопоставлять по названиям заголовков). Те, что нужны для продаж по странам:
| Столбец | Что содержит | Для чего использовать |
|---|---|---|
| Apple Identifier | Apple ID приложения или встроенной покупки | Сопоставление с вашими продуктами в API |
| SKU / Parent Identifier | Ваш SKU; для встроенных покупок Parent Identifier — это SKU приложения | Группировка встроенных покупок по приложению |
| Title | Название приложения для загрузок, 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 — загрузки приложения, бесплатные или платные; 3 и 3F — повторные загрузки; 7, 7F, 7T и F7 — обновления; IA1, IA9, IAY, FI1 и их варианты с -M — встроенные покупки и подписки; IA3 — восстановленная неисчерпываемая покупка.
- Developer Proceeds указывается на единицу. Перед суммированием строк умножайте на Units.
- У возвратов Units отрицательные, а Developer Proceeds положительные, поэтому Units × Developer Proceeds корректно их вычитает.
- Перед подсчётом загрузок исключите обновления и повторные загрузки — они бесплатны и обычно намного превосходят по числу настоящие загрузки.
- Один и тот же продукт и страна могут встречаться в нескольких строках (разные цены, устройства, промокоды). Суммируйте их.
- Дни идут от полуночи до полуночи по тихоокеанскому времени, а не по UTC.
- Суммы указаны в местных валютах. Прежде чем ранжировать страны, конвертируйте их по одному набору курсов; в руководстве продажи по странам разобрано честное сравнение.
Когда отчёты готовы и сколько хранятся
Со страницы Apple о доступности: ежедневные отчёты доступны на следующий день, еженедельные — по понедельникам, ежемесячные — через пять дней после конца месяца, ежегодные — через шесть дней после конца года, как правило к 8 утра по тихоокеанскому времени. Ежедневные, еженедельные и ежемесячные отчёты хранятся год; ежегодные — десять лет. Summary Sales report существует только за период, в котором продана хотя бы одна единица приложения, поэтому в тихий день файла просто нет.
Частые ошибки 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 | Роль ключа не позволяет читать отчёты о продажах | Используйте ключ с ролью Admin, Finance или Sales. |
| 404 | Нет отчёта за эту дату: он ещё не опубликован, в этот день ничего не продано или отчёт старше срока хранения Apple | Считайте это «нет данных», недавние дни повторите позже. |
| 429 | Достигнут почасовой лимит запросов для этого ключа | Сделайте паузу и продолжите; растяните скачивание истории по времени. |
500 UNEXPECTED_ERROR | Сбой на сервере Apple. Когда мы отправили vendor number, не принадлежащий команде ключа, пришла именно эта ошибка, а не понятное сообщение | Повторите один раз; если ошибка остаётся, прежде всего перепроверьте vendor number. |
Как RepriceCat использует ваш vendor number
RepriceCat меняет цены с помощью вашего ключа App Store Connect; с vendor number он ещё и видит, к чему эти цены приводят. Добавьте его в Settings → Sales reports. Чтобы читать отчёты, ключу нужна роль Admin, Finance или Sales — то есть Admin, если тот же ключ ещё и меняет цены. После этого RepriceCat скачивает ежедневные отчёты Apple SALES / SUMMARY, каждый день один раз, и хранит только дневные итоги по продуктам и странам. Обновления и повторные загрузки не учитываются.
- Экран Sales: единицы, загрузки, покупки, выручка (в USD по сегодняшним курсам), доля и тренд по странам, с картой мира, графиками по дням и дням недели и фильтрами по приложению и продукту.
- Ценовые подсказки, например страны с большим числом загрузок, но малым числом покупок, или те, где покупают намного чаще среднего.
- Влияние каждого изменения цены в Activity: единицы и выручка до и после изменения, по продуктам и странам.
- Эксперименты: измените цену в нескольких странах, остальные оставьте для сравнения и сохраните результат или откатите его (как провести тест цены).
Если вы не хотите сами поддерживать скрипт скачивания и разбора, сравните RepriceCat со скриптами на API или начните с бесплатного месяца.
Частые вопросы
Где найти vendor number в App Store Connect?
Откройте «Платежи и финансовые отчёты», выберите «Отчёты» вверху и прочитайте номер в левом верхнем углу под названием юридического лица. Он также есть в имени файла любого скачанного отчёта о продажах, например S_D_80012345_20130919.
Vendor number — это то же самое, что Team ID или Apple ID приложения?
Нет. Vendor number привязан к вашему юридическому лицу в разделе «Платежи и финансовые отчёты». Team ID и Apple ID приложений — отдельные идентификаторы, и в качестве filter[vendorNumber] они не подойдут.
Какая роль нужна ключу API, чтобы скачивать отчёты о продажах?
Admin, Finance или Sales. App Manager может менять цены, но Apple не указывает эту роль среди ролей для Sales and Trends, поэтому одному ключу, который делает и то и другое, нужна роль Admin.
Почему GET /v1/salesReports возвращает 404?
Отчёта за эту дату нет: день ещё не опубликован, в этот день ничего не продано или дата старше одного года, в течение которого Apple хранит ежедневные отчёты. Считайте это «нет данных» и повторите недавние дни позже.
За какой период назад можно скачать отчёты о продажах App Store?
Ежедневные, еженедельные и ежемесячные отчёты хранятся год с момента появления, ежегодные — десять лет. Если нужна более длинная история по дням, сохраняйте файлы сами.
Какую версию использовать для ежедневного отчёта о продажах?
В справочнике по конечной точке у Apple для SALES и SUMMARY указана версия 1_0. Разбирайте файл по названиям столбцов, а не по позициям: Apple добавляет столбцы между версиями макета.
Попробуйте
Новые цены во всех странах от одной базовой цены
Уровни, привязка к ценовым точкам, одна таблица проверки, одно подтверждение — через App Store Connect API. Первый месяц бесплатно, затем $1 за приложение в месяц.