Перейти к содержимому

App Store Connect API

Vendor number в App Store Connect и API salesReports

Каждый запрос отчёта о продажах к API App Store Connect требует число, на которое большинство разработчиков ни разу не смотрели: vendor number. Здесь — где оно лежит, какой ключ может им пользоваться и как превратить `GET /v1/salesReports` в продажи по странам, с которыми действительно можно работать.

Обновлено 9 мин чтения

Где найти vendor number в App Store Connect

Ваш vendor number находится в разделе «Платежи и финансовые отчёты» (Payments and Financial Reports). Войдите в App Store Connect, откройте этот раздел, выберите «Отчёты» (Reports) в верхней части страницы — номер появится в левом верхнем углу под названием вашего юридического лица (Legal Entity Name). API ожидает его как filter[vendorNumber] (справка Apple).

  1. Войдите в App Store Connect с ролью Account Holder, Admin или Finance — это роли, которые Apple указывает для раздела «Платежи и финансовые отчёты».
  2. Откройте «Платежи и финансовые отчёты».
  3. Выберите «Отчёты» в верхней части страницы.
  4. Прочитайте 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 ManagerApple не указываетНетДа
Developer, Marketing, Customer SupportНетНетНет

Для ключа, который вы передаёте стороннему сервису, лишь анализирующему отчёты, Apple советует роль Sales (в документации API она называется Sales and Reports): такой ключ может вызывать GET /v1/salesReports, но не конечную точку финансовых отчётов (примечание Apple). Если один ключ должен и читать продажи, и менять цены, единственная роль ключа, которая умеет и то и другое, — Admin. Альтернатива — два ключа: App Manager для цен и Sales для отчётов; это аккуратнее, если ваш инструмент это поддерживает. Как создать любой из них, описано в руководстве создание ключа API.

GET /v1/salesReports отдаёт все скачиваемые отчёты Sales and Trends. Каждый тип принимает только определённые сочетания подтипа, частоты и версии; всё остальное — ошибка. Допустимые сочетания из справочника по конечной точке от 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: агрегированные единицы, цены и выручка по приложениям и встроенным покупкам, одна строка на продукт, страну, цену и тип транзакции. Самая полезная частота — ежедневная: из дней можно собрать любой период, а дни нужны, чтобы увидеть эффект изменения цены.

Скачивание отчёта о продажах через 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_0Версия, которую Apple указывает для этого типа отчёта.
  1. Создайте командный ключ API с ролью Admin, Finance или Sales и сохраните его 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. Закодируйте квадратные скобки в URL, если ваш HTTP-клиент этого не делает.
  4. Тело ответа 200 — gzip (application/a-gzip). Распакуйте его: с curl сохраните в файл и выполните над ним gunzip.
  5. Теперь у вас текст с разделителями-табуляциями: строка заголовка, затем по строке на продукт, страну, цену и тип транзакции. Разбирайте столбцы по названию в заголовке, а не по позиции.
  6. Сохраните день. Apple хранит ежедневные отчёты только год, так что всё, что вы хотите сравнивать год к году, нужно сохранять у себя.
  7. Повторите для каждого нужного дня, не частя: в каждом ответе есть заголовок X-Rate-Limit с оставшимся числом запросов в час (ограничения частоты запросов).

Еженедельные, ежемесячные и ежегодные отчёты работают так же, с другой частотой. В примерах имён файлов у Apple еженедельный отчёт датирован воскресеньем, а у ежемесячных и ежегодных файлов указан только месяц или год — это удобная проверка того, за какой период вы получили отчёт. Помните: сумма 30 ежедневных файлов даёт месяц, который можно разрезать как угодно; а месячный файл дней не даёт.

Формат файла и важные столбцы

В справочнике полей Summary Sales Report описан каждый столбец (описана версия макета 1_3; Apple со временем добавляет столбцы, и это ещё одна причина сопоставлять по названиям заголовков). Те, что нужны для продаж по странам:

СтолбецЧто содержитДля чего использовать
Apple IdentifierApple 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 за приложение в месяц.

Продажи и аналитика10 мин чтения

Продажи в App Store по странам: где приложение продаётся на деле

Где App Store Connect показывает продажи по странам, что означают юниты, загрузки и выручка, как честно сравнивать страны и что менять, когда цифры перед глазами.

Читать руководство
Инструкции7 мин чтения

Как создать ключ API App Store Connect для управления ценами

Создайте ключ API App Store Connect для смены цен: нужная роль, где взять Issuer ID и Key ID, безопасное хранение файла .p8, проверка ключа и его отзыв.

Читать руководство
App Store Connect API7 мин чтения

Смена цен через API App Store Connect: ресурсы и запросы

Меняйте цены App Store через API App Store Connect: ценовые точки, выравнивание, графики цен приложений, IAP и подписок, тела запросов, лимиты и подводные камни.

Читать руководство
Стратегия ценообразования10 мин чтения

A/B-тест цен в App Store: как тестировать цены по странам

В App Store нет встроенного A/B-теста цен. Как проверить цену разделением по странам: выбор стран, срок, что измерять и как читать результаты.

Читать руководство
Продажи и аналитика10 мин чтения

Много загрузок, мало покупок: конверсия App Store по странам

Почему в одних странах приложение скачивают, но почти не покупают, как посчитать покупки на загрузку по странам в Sales and Trends и когда помогает цена ниже.

Читать руководство