Руководство по миграции на Server-Side API v2
Server-Side API v2 от Adapty предоставляет новые возможности и улучшения для более эффективного управления уровнями доступа, транзакциями и профилями пользователей.
Зачем переходить на v2?
Вторая версия Server-Side API даёт больше гибкости и функциональности при работе с Adapty:
- Раздельное управление уровнями доступа: назначайте уровни доступа пользователям без необходимости указывать детали транзакции — это упрощает обработку компенсаций, бонусов и других нетранзакционных сценариев.
- Запись разовых покупок: фиксируйте транзакции для расходуемых покупок, указывая поля, специфичные для таких продуктов.
- Расширенные сведения о транзакциях: добавляйте к транзакциям больше данных — возвраты, проблемы с оплатой, причины отмены, продления и т. д.
- Обновление профиля: теперь можно не просто добавлять атрибуты, но и обновлять профиль пользователя целиком — например, добавлять метаданные установки или отключать внешнюю аналитику.
Версия 1 по-прежнему поддерживается, однако мы рекомендуем перейти на v2 ради расширенного функционала и дальнейших обновлений.
Обзор изменений
| Изменение | Необходимые действия |
|---|---|
| Базовый URL и эндпоинт | Базовый URL и все эндпоинты изменились. Обновите конфигурацию согласно описанию эндпоинтов запросов. |
| Заголовки запросов |
|
| Структура запросов и ответов | Измените параметры в соответствии с описанием каждого запроса и обновите интеграцию для обработки новых форматов ответов. |
| Изменение управления уровнями доступа | Старый запрос Prolong/grant a subscription for a user теперь разделён на три:
|
Шаги миграции
Чтобы упростить работу с нашим server-side API, мы подготовили коллекцию Postman и файл окружения, которые можно скачать и импортировать в Postman.
Шаг 1. Настройте заголовки запросов
Добавьте новые заголовки запросов:
| Заголовок | Описание |
|---|---|
| adapty-profile-id | (Обязательно, выберите один) Adapty ID профиля пользователя. Отображается в поле Adapty ID на странице дашборд Adapty -> Profiles -> конкретного профиля. Взаимозаменяем с adapty-customer-user-id — используйте любой из них. |
| adapty-customer-user-id | (Обязательно, выберите один) ID пользователя в вашей системе. Отображается в поле Customer user ID на странице дашборд Adapty -> Profiles -> конкретного профиля. Взаимозаменяем с adapty-profile-id — используйте любой из них. ⚠️ Работает только если вы идентифицируете пользователей в коде приложения с помощью SDK Adapty. |
| adapty-platform | Укажите платформу приложения. Допустимые значения: iOS, macOS, iPadOS, visionOS, Android. |
Шаг 2. Измените запросы управления транзакциями и доступом
В версии 1 использовались:
- Запрос Prolong/Grant a Subscription for a User: для записи транзакции и предоставления или сокращения уровня доступа.
- Запрос Revoke access level: для немедленного отзыва доступа.
Теперь они заменены тремя отдельными запросами, разграничивающими добавление транзакций и управление уровнями доступа:
- Grant Access Level: используйте этот запрос для продления уровня доступа без привязки к транзакции.
- Revoke Access Level: для немедленного отзыва или сокращения доступа.
- Set Transaction: используйте этот запрос для добавления деталей транзакции в Adapty с предоставлением уровней доступа.
Шаг 2.1. Как предоставить уровень доступа
Подробное описание см. в запросе Grant access level.
В версии 1 для предоставления доступа использовался запрос Prolong/grant a subscription for a user. Теперь вы можете предоставить доступ с помощью запроса Grant access level без указания деталей транзакции.
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/grant/access-level/ - Параметры, которые остаются:
- access_level_id: ранее передавался в эндпоинте. Обязательный.
- starts_at: теперь допускает null.
- expires_at: необязательный для пожизненного доступа, допускает null.
Шаг 2.2. Как отозвать или сократить уровень доступа
Подробное описание см. в запросе Revoke access level.
В версии 1 для немедленного отзыва доступа использовался запрос Revoke access level, а для сокращения — запрос Prolong/Grant a Subscription for a User. Теперь для обоих действий можно использовать запрос Revoke access level.
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/purchase/profile/revoke/access-level/ - Параметры, которые остаются:
- access_level_id: обязательный.
- expires_at: допускает null, если доступ не отзывается немедленно.
Шаг 2.3. Как записать транзакцию подписки
Подробное описание см. в запросе Set transaction.
В версии 1 транзакции записывались с помощью запроса Prolong/Grant a Subscription for a User, который поддерживал только транзакции подписок.
В версии 2 эту функцию заменяет запрос Set Transaction, который умеет обрабатывать как транзакции подписок, так и разовые покупки.
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/purchase/set/transaction/ - Детали: набор обязательных параметров зависит от того, является ли транзакция подпиской или разовой покупкой. Ниже описаны правила записи транзакций подписок.
Новые поля
| Параметр | Изменение | Тип | Обязательный | Допускает null | Описание |
|---|---|---|---|---|---|
billing_issue_detected_at | Добавлен | Дата ISO 8601 | :heavy_plus_sign: | :heavy_plus_sign: | Дата и время обнаружения проблемы с оплатой (например, неудачное списание с карты). Подписка при этом может оставаться активной. Поле очищается при успешном платеже. |
cancellation_reason | Добавлен | String | :heavy_plus_sign: | :heavy_plus_sign: | Возможные причины отмены: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, upgraded или unknown. |
environment | Добавлен | String | :heavy_minus_sign: | :heavy_minus_sign: | Среда, в которой произошла транзакция. Возможные значения: Заменяет параметр |
grace_period_expires_at | Добавлен | Дата ISO 8601 | :heavy_minus_sign: | :heavy_minus_sign: | Дата и время окончания льготного периода, если подписка в данный момент находится в нём. |
is_family_shared | Добавлен | Boolean | :heavy_minus_sign: | :heavy_minus_sign: | Булево значение, указывающее, поддерживает ли продукт семейный доступ в App Store Connect. Только для iOS. Всегда false для iOS ниже 14.0 и macOS ниже 11.0. |
offer | Добавлен | Object | :heavy_plus_sign: | :heavy_minus_sign: | Представляет офер покупки в виде объекта. См. объект Offer. |
originally_purchased_at | Добавлен | Дата ISO 8601 | :heavy_plus_sign: | :heavy_minus_sign: | Для цепочек подписок — дата покупки оригинальной транзакции, связанной через store_original_transaction_id. |
purchase_type | Добавлен | String | :heavy_plus_sign: | :heavy_minus_sign: | Указывает тип продукта; здесь устанавливается в subscription. |
purchased_at | Добавлен | Дата ISO 8601 | :heavy_plus_sign: | :heavy_minus_sign: | Дата и время последней покупки. |
refunded_at | Добавлен | Дата ISO 8601 | :heavy_minus_sign: | :heavy_minus_sign: | Дата и время возврата средств по подписке, если применимо. |
renew_status | Добавлен | Boolean | :heavy_plus_sign: | :heavy_minus_sign: | Указывает, включено ли автопродление подписки. |
renew_status_changed_at | Добавлен | Дата ISO 8601 | :heavy_minus_sign: | :heavy_minus_sign: | Дата и время изменения статуса автопродления. |
variation_id | Добавлен | String | :heavy_minus_sign: | :heavy_minus_sign: | ID варианта для отслеживания покупок на конкретном пейволе. |
Удалённые поля
| Параметр | Изменение | Описание |
|---|---|---|
base_plan_id | Удалён | Удалён. Добавляйте ID базового плана в поле store_product_id в формате product_id:base_plan_id. |
duration_days | Удалён | Удалён как ненужный — длительность рассчитывается автоматически. |
introductory_offer_type | Удалён | Типы оферов теперь находятся в объекте offer. |
is_lifetime | Удалён | Удалён, заменён параметром purchase_type. |
is_sandbox | Удалён | Заменён параметром environment. |
price_locale | Удалён | Перенесён в объект price. |
proceeds | Удалён | |
starts_at | Удалён | Удалён — значение берётся автоматически из уровня доступа, связанного с выбранным продуктом. |
Изменённые поля
| Параметр | Изменение | Тип | Обязательный | Допускает null | Описание изменения |
|---|---|---|---|---|---|
price | Изменён | Float -> Object | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: | Теперь представлен как объект Price и включает поля price_locale, country и value. |
store | Изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
vendor_original_transaction_id -> store_original_transaction_id | Переименован, изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
vendor_product_id -> store_product_id | Переименован, изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
vendor_transaction_id -> store_transaction_id | Переименован, изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
Шаг 2.4. Как записать транзакцию разовой покупки
Подробное описание см. в запросе Set transaction.
В версии 1 транзакции записывались с помощью запроса Prolong/Grant a Subscription for a User, который поддерживал только транзакции подписок.
В версии 2 эту функцию заменяет запрос Set Transaction, который умеет обрабатывать как транзакции подписок, так и разовые покупки.
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/purchase/set/transaction/ - Детали: набор обязательных параметров зависит от того, является ли транзакция подпиской или разовой покупкой. Ниже описаны правила записи транзакций разовых покупок.
Новые поля
| Параметр | Изменение | Тип | Обязательный | Допускает null | Описание изменения |
|---|---|---|---|---|---|
cancellation_reason | Добавлен | String | :heavy_minus_sign: | :heavy_minus_sign: | Возможные причины отмены: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, cancelled_by_developer, new_subscription_replace, upgraded, unknown, adapty_revoked. |
environment | Добавлен | String | :heavy_minus_sign: | :heavy_minus_sign: | Среда, в которой произошла транзакция. Возможные значения: Заменяет параметр |
is_family_shared | Добавлен | Boolean | :heavy_minus_sign: | :heavy_minus_sign: | Указывает, поддерживает ли продукт семейный доступ в App Store Connect. Только для iOS. Всегда false для iOS ниже 14.0 и macOS ниже 11.0. |
offer | Добавлен | Object | :heavy_minus_sign: | :heavy_minus_sign: | Представляет офер покупки в виде объекта. См. объект Offer. |
purchase_type | Добавлен | String | :heavy_plus_sign: | :heavy_minus_sign: | Указывает тип приобретённого продукта. Здесь устанавливается в one_time_purchase. |
purchased_at | Добавлен | Дата ISO 8601 | :heavy_plus_sign: | :heavy_minus_sign: | Дата и время последней покупки уровня доступа. |
refunded_at | Добавлен | Дата ISO 8601 | :heavy_minus_sign: | :heavy_minus_sign: | При возврате средств — дата и время возврата. |
variation_id | Добавлен | String | :heavy_minus_sign: | :heavy_minus_sign: | ID варианта для отслеживания покупок на конкретном пейволе. |
Удалённые поля
| Параметр | Изменение | Описание изменения |
|---|---|---|
base_plan_id | Удалён | Удалён. Добавляйте ID базового плана в поле store_product_id в формате product_id:base_plan_id. |
duration_days | Удалён | Удалён как ненужный — длительность рассчитывается автоматически. |
expires_at | Удалён | Удалён как неприменимый к разовой покупке. |
introductory_offer_type | Удалён | Типы оферов теперь находятся в объекте offer. |
is_lifetime | Удалён | Удалён, заменён параметром purchase_type. |
is_sandbox | Удалён | Заменён параметром environment. |
price_locale | Удалён | Перенесён в объект price. |
proceeds | Удалён | |
starts_at | Удалён | Удалён как неприменимый к разовой покупке. |
Изменённые поля
| Параметр | Изменение | Тип | Обязательный | Допускает null | Описание изменения |
|---|---|---|---|---|---|
price | Изменён | Float -> Object | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: | Теперь представлен как объект Price и включает поля price_locale, country и value. |
store | Изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
vendor_original_transaction_id -> store_original_transaction_id | Переименован, изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
vendor_product_id -> store_product_id | Переименован, изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
vendor_transaction_id -> store_transaction_id | Переименован, изменён | String | :heavy_minus_sign: -> :heavy_plus_sign: | :heavy_minus_sign: |
|
Шаг 3. Измените запрос Get info about a user
Подробное описание см. в запросе Get profile.
Измените запрос следующим образом:
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/profile/ - Изменение: ID профиля пользователя или Customer User ID теперь передаётся через заголовки, дополнительные параметры не нужны. Параметр extended больше не нужен, так как полные данные профиля возвращаются всегда.
Шаг 4. Измените запрос Set the user's attribute
Подробное описание см. в запросе Update profile.
В версии 1 можно было только обновлять атрибуты пользователя. В версии 2 доступен более широкий набор полей профиля — например, метаданные установки или настройки аналитики.
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/profile/.
| Параметр | Изменение | Тип | Обязательный | Допускает null | Описание изменения |
|---|---|---|---|---|---|
analytics_disabled | Добавлен | Boolean | :heavy_minus_sign: | :heavy_minus_sign: | Опция отказа от внешней аналитики. При отключении события не отправляются в интеграции, а поля idfa, idfv и advertising_id становятся обнуляемыми. |
installation_meta | Добавлен | Dictionary | :heavy_minus_sign: | :heavy_minus_sign: | Содержит специфичные для устройства данные приложения в виде словаря объектов Installation Meta. |
store | Добавлен | String | :heavy_minus_sign: | :heavy_plus_sign: | Стор, в котором был куплен продукт. Варианты: app_store, play_store, stripe или название вашего кастомного стора. |
store_country | Добавлен | String | :heavy_minus_sign: | :heavy_plus_sign: | Страна стора конечного пользователя. |
birthday | Изменён | Date -> Дата ISO 8601 | :heavy_minus_sign: | :heavy_plus_sign: -> :heavy_minus_sign: | Дата рождения конечного пользователя. |
ip_country | Изменён | String | :heavy_minus_sign: | :heavy_plus_sign: -> :heavy_minus_sign: | Страна конечного пользователя в формате ISO 3166-2. Обязательно передавать, если запрос выполняется с сервера. В противном случае определяется по IP запроса. |
Шаг 5. Измените запрос Delete user's data
Подробное описание см. в запросе Delete profile.
- Эндпоинт:
https://api.adapty.io/api/v2/server-side-api/profile/ - Изменение:
adapty-profile-idилиadapty-customer-user-idтеперь передаётся через заголовки, дополнительные параметры не нужны.