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

Инструкции

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

Любой инструмент, который меняет цены от вашего имени, — ваш собственный скрипт или RepriceCat — аутентифицируется с помощью ключа API App Store Connect. Вот как создать ключ, который справится с задачей и не получит больше прав, чем нужно.

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

Коротко

В App Store Connect откройте «Пользователи и доступ» (Users and Access) → «Интеграции» (Integrations) → App Store Connect API → «Ключи команды» (Team Keys) и создайте ключ с ролью App Manager (или Admin, если нужны ещё и отчёты о продажах). Скачайте файл .p8 — такая возможность только одна — и скопируйте Key ID и Issuer ID. Эти три значения и есть учётные данные.

Создание ключа шаг за шагом

Для шагов Apple (Apple: создание ключей API) нужна учётная запись Admin; если API в вашей команде ещё ни разу не использовался, сначала владелец аккаунта (Account Holder) должен запросить к нему доступ.

  1. Войдите в App Store Connect, откройте «Пользователи и доступ» и выберите вкладку «Интеграции».
  2. Выберите App Store Connect API в левой колонке и убедитесь, что открыта вкладка «Ключи команды».
  3. Нажмите «Создать ключ API» (Generate API Key) или кнопку добавления (+).
  4. Введите имя, которое вы потом узнаете, например «Pricing — RepriceCat». Имя нужно только вам.
  5. В разделе «Доступ» выберите роль (см. таблицу ниже) и нажмите «Создать».
  6. Нажмите «Скачать ключ API» (Download API Key) рядом с новым ключом. Закрытый ключ скачивается один раз в виде файла .p8, обычно с именем вроде AuthKey_2X9R4HXF34.p8; Apple копию не хранит, а ссылка исчезает после скачивания.
  7. Скопируйте Key ID из списка активных ключей и Issuer ID, который показан в верхней части страницы.
ЗначениеКак выглядитГде найти
Issuer IDUUID, например 57246542-96fe-1a63-e053-0824d011072aВверху страницы App Store Connect API; одинаков для всех ключей команды
Key ID10 символов, например 2X9R4HXF34Рядом с ключом в списке активных
Закрытый ключТекстовый файл .p8, начинающийся с -----BEGIN PRIVATE KEY-----Ваша загрузка; скачать повторно нельзя

В примерах использованы тестовые значения самой Apple из её документации по токенам.

Какую роль дать ключу?

Роль командного ключа определяет, что он может делать, а командные ключи имеют доступ ко всем приложениям независимо от роли. В справке Apple о ценах для смены цен приложений, встроенных покупок и подписок в качестве необходимой роли указаны Account Holder, Admin или App Manager (Apple: установка цены, Apple: права ролей).

РольМожет менять ценыОтчёты «Продажи и тренды»Подходит для цен?
App ManagerДаДля этой роли Apple не описываетДа — наименьшая роль, управляющая ценами
AdminДаДаДа, если тот же ключ должен ещё и читать отчёты о продажах
FinanceНетДаНет — только отчёты
SalesНетДаНет — только отчёты
Developer, Marketing, Customer SupportНетApple не описываетНет

Ключи Admin очень мощные — Apple отмечает, что они могут создавать и удалять пользователей, — поэтому берите App Manager, если вам не нужны данные о продажах с того же ключа. О чтении продаж по странам рассказано в руководстве по vendor number и отчётам о продажах.

Командные и индивидуальные ключи

App Store Connect предлагает оба варианта. Для цен используйте командный ключ:

  • У командных ключей есть явная роль, и они остаются, даже если создавший их человек покинул команду.
  • Индивидуальные ключи несут доступ и роли одного пользователя и создаются из его профиля — только если Admin выдал право Generate Individual API Keys.
  • Индивидуальные ключи не могут использовать конечные точки Sales и Finance, provisioning и notarytool, поэтому для отчётов о продажах они не годятся.

Проверьте ключ, прежде чем на него полагаться

  1. Подпишите JWT: в заголовке alg ES256 и kid = Key ID; в полезной нагрузке iss = Issuer ID, iat = сейчас, exp = не позже чем через 20 минут, aud = appstoreconnect-v1.
  2. Вызовите GET https://api.appstoreconnect.apple.com/v1/apps, передав токен в заголовке bearer. Список ваших приложений означает, что ключ работает.
  3. 401 обычно значит неверный Issuer ID или Key ID, токен, подписанный другим ключом, либо токен со слишком долгим сроком жизни или уже просроченный (проверьте часы).
  4. 403 при вызове, связанном с ценами, обычно значит, что роль ключа не позволяет управлять ценами, — используйте ключ с ролью App Manager или Admin.

Когда ключ заработает, в руководстве по API цен разобраны конечные точки ценовых точек и графиков.

Безопасное хранение

  • Относитесь к файлу .p8 как к паролю. Любой, у кого он есть вместе с двумя ID, может действовать с ролью ключа во всех приложениях команды.
  • Совет Apple: не передавайте ключи другим, не храните их в репозитории кода и не включайте в клиентский код.
  • Один ключ — одна задача. Ключу для цен не обязательно быть тем же, что использует ваш CI для загрузок, тогда каждый можно отозвать, не сломав другой.
  • Если вы вставляете ключ в инструмент, проверьте, что тот с ним делает. RepriceCat шифрует ключ алгоритмом AES-256-GCM перед сохранением, никогда не отправляет его обратно в браузер и использует только для подписи недолговечных токенов для вашего аккаунта.

Частые ошибки

  • Выбрать Developer или Marketing, потому что это «звучит безопаснее». Тогда ключ читает данные, но любое изменение цены завершается ошибкой.
  • Создать индивидуальный ключ из своего профиля, а потом гадать, почему отказывают в отчётах о продажах, — индивидуальные ключи не могут использовать конечные точки Sales и Finance.
  • Перепутать Key ID и Issuer ID. Key ID короткий и идёт в заголовок токена как kid; Issuer ID — длинный UUID и идёт в полезную нагрузку как iss.
  • Подписывать токены со сроком жизни дольше 20 минут. Apple отклоняет их для конечных точек цен; долгой задаче нужно периодически подписывать новый токен и использовать каждый, пока он не истечёт.
  • Закоммитить файл .p8 в репозиторий, даже приватный. Перенесите его в хранилище секретов и отзовите скомпрометированный ключ.
  • Использовать один ключ для загрузок из CI, скрипта цен и стороннего инструмента. Когда вы отзываете его по одной причине, ломается и всё остальное.

Решаете, писать ли собственный скрипт для цен с этим ключом или взять инструмент? В материале RepriceCat против скриптов на API разобраны компромиссы.

Отзыв ключа

Отзывайте ключ, когда кто-то уходит, когда он мог утечь или когда вы перестаёте пользоваться инструментом. Admin может отозвать командные ключи из списка ключей API в «Пользователи и доступ» (Apple: отзыв ключей API). Отзыв необратим: отозванный ключ восстановить нельзя, все подписанные им токены перестают работать, а в списке «Отозванные» он остаётся 30 дней. Если вы потеряли .p8, отзовите ключ и создайте новый.

Использование ключа в RepriceCat

Для подключения RepriceCat нужны Issuer ID, Key ID и файл .p8 командного ключа с ролью App Manager или Admin. После этого:

  • Ключ хранится в зашифрованном виде, и вы можете отозвать его в любой момент в App Store Connect.
  • В Apple ничего не отправляется, пока вы не подтвердите проверку каждого продукта и страны; пробный запуск ничего не отправляет.
  • Странице Sales дополнительно нужны ваш vendor number и ключ с ролью Admin, Finance или Sales — поэтому ключ Admin покрывает и цены, и продажи сразу.

Готовы? Подключите ключ и измените цены первого приложения — первый месяц бесплатно, затем $1 за приложение в месяц.

Частые вопросы

Где найти Issuer ID?

В App Store Connect: «Пользователи и доступ», «Интеграции», App Store Connect API. Он находится в верхней части страницы, рядом с кнопкой «Копировать», и одинаков для всех командных ключей аккаунта.

Я потерял файл .p8. Можно скачать его снова?

Нет. Apple позволяет скачать закрытый ключ один раз и копию не хранит. Отзовите ключ и создайте новый.

Какая роль в App Store Connect может менять цены?

Admin и App Manager, а также владелец аккаунта (Account Holder). App Manager — наименьшая роль, управляющая ценами; Developer, Marketing, Finance и Sales не могут.

Кто может создать ключ API App Store Connect?

Командные ключи создаёт тот, у кого учётная запись Admin, после того как владелец аккаунта запросил доступ к API для команды. Индивидуальные ключи создаются из собственного профиля пользователя, если Admin выдал такое право.

Можно ли использовать индивидуальный ключ API для цен?

Для цен он работает, если собственная роль пользователя позволяет управлять ценами, но лучше командный ключ: у него явная роль, и он остаётся, если пользователь уходит. Кроме того, индивидуальные ключи не получают доступа к отчётам Sales и Finance.

Безопасно ли давать инструменту для цен мой ключ API?

Только если вы доверяете тому, как он хранит ключ, потому что ключ может всё, что позволяет его роль. Используйте отдельный командный ключ с наименьшей подходящей ролью и отзовите его, когда перестанете пользоваться инструментом.

Попробуйте

Новые цены во всех странах от одной базовой цены

Уровни, привязка к ценовым точкам, одна таблица проверки, одно подтверждение — через App Store Connect API. Первый месяц бесплатно, затем $1 за приложение в месяц.