Продажа подписки¶

Ниже описано, как открыть пользователю доступ к вашей подписке (видео SVOD, AdVOD и FVOD) через биллинг MEGOGO. Подписку вы продаете в своей системе, а MEGOGO регистрирует услугу пользователя.

Перед началом работы¶

Убедитесь, что:

у вас есть ID партнера и ID услуг ваших подписок (см. Учетные данные);
MEGOGO добавил IP-адреса ваших серверов в список IP-адресов вашего ID партнера (см. Учетные данные);
вы знаете режим продления каждой услуги. Уточните его у вашего менеджера MEGOGO (см. Продление).

ВНИМАНИЕ

Отправляйте запросы Billing API только со своего сервера. Эти запросы не подписываются: MEGOGO определяет вас по IP-адресу.

Схема взаимодействия¶

sequenceDiagram
    participant User as Пользователь
    participant Server as Сервер партнера
    participant Billing as MEGOGO Billing API
    participant API as MEGOGO Content API
    User->>Server: Оплачивает подписку
    Server->>Billing: subscription/subscribe (userId, serviceId)
    Billing-->>Server: "successful": true
    Server->>Server: Списывает оплату с пользователя
    Server->>API: auth/by_partners
    API-->>Server: access_token
    Server-->>User: Видео доступно для просмотра

Шаг 1. Подключите подписку¶

Отправьте со своего сервера запрос:

GET https://billing.megogo.net/partners/{partner_id}/subscription/subscribe?userId={user_id}&serviceId={service_id}

Параметр	Описание
`partner_id`	Ваш ID партнера
`userId`	Идентификатор пользователя в вашей системе. Во всех запросах для этого пользователя передавайте одно и то же значение
`serviceId`	ID услуги подписки, например `premiumsvod`

Ожидаемый ответ:

{"successful": true}

Если пользователя еще нет в MEGOGO, запрос его создаст.

Шаг 2. Спишите оплату с пользователя¶

Списывайте оплату только после ответа "successful": true. При успешном ответе MEGOGO регистрирует подписку, даже если пользователь ничего не смотрит.

При любом другом ответе оплату не списывайте (см. Ошибки).

Шаг 3. Проверьте подписку¶

GET https://billing.megogo.net/partners/{partner_id}/user/subscriptions?identifier={user_id}

Ожидаемый ответ:

{
  "identifier": "user-0001",
  "svod": [
    {
      "serviceId": "premiumsvod",
      "serviceName": "SVOD partners",
      "dateFinish": 1795945720,
      "dateFinishString": "2026-11-29 09:48:40"
    }
  ]
}

dateFinish — окончание оплаченного периода в Unix-времени (в секундах), dateFinishString — то же время в UTC.
Не вычисляйте дату окончания самостоятельно — берите ее из этого ответа.
С помощью этого запроса проверяйте, что услуги пользователя в вашей системе и в MEGOGO совпадают.

Шаг 4. Откройте пользователю просмотр¶

Получите токен доступа пользователя (см. Авторизация пользователя).
Запустите воспроизведение видео (см. Воспроизведение видео).

ВНИМАНИЕ

В вашу подписку входят видео AdVOD и FVOD, а их поток Content API отдает без привязки к пользователю. Поэтому, прежде чем запрашивать поток, убедитесь, что у пользователя есть ваша подписка.

Продление¶

Для каждой услуги MEGOGO задает один из двух режимов продления:

Режим	Как продлевается подписка	Повторный `subscribe` для активной подписки
Автоматическое продление	MEGOGO продлевает подписку на каждый следующий период, пока вы не отправите `unsubscribe`	Ошибка 2023: услуга уже активна. Ничего делать не нужно
Продление партнером	На каждый новый период вы снова отправляете `subscribe`	Добавляет к дате окончания один период

Длительность периода задана в услуге — обычно 30 дней. Для пробного доступа MEGOGO может выдать отдельные услуги, например на 7 или 14 дней.

ВНИМАНИЕ

В режиме «продление партнером» запрос subscribe не идемпотентен: каждый успешный запрос добавляет еще один период. Прежде чем отправить запрос повторно, выполните шаг 3.

ВНИМАНИЕ

Дата окончания не может отстоять от текущего момента больше чем на 5 лет. Если запрос subscribe выходит за этот предел, возвращается ошибка 2027.

Отключение, приостановка и возобновление¶

Используйте тот же URL, что и в шаге 1, заменив операцию:

GET https://billing.megogo.net/partners/{partner_id}/subscription/{operation}?userId={user_id}&serviceId={service_id}

`operation`	Результат
`unsubscribe`	Доступ прекращается сразу, и подписка пропадает из `user/subscriptions`. Когда отправлять запрос, решаете вы — например, в конце оплаченного пользователем периода
`suspend`	Доступ приостанавливается до `resume`. Оплаченное время пользователь не теряет
`resume`	Доступ возобновляется, а дата окончания сдвигается вперед на время приостановки. Для активной подписки возвращается ошибка 2023

Повторный unsubscribe или suspend возвращает "successful": true.

Чтобы сменить подписку пользователя, отправьте unsubscribe для старой услуги, а затем subscribe для новой.

Повторные запросы¶

Повторяйте запрос только после тайм-аута или ответа HTTP 5xx:

Выполните шаг 3 и убедитесь, что первый запрос не изменил услугу.
Выдерживайте между попытками 1 минуту.
Делайте не больше 6 попыток.

Рекомендуем записывать в журнал все запросы к Billing API и ответы на них. При обращении в поддержку MEGOGO сообщайте время запроса и код ошибки.

Ошибки¶

Ошибка приходит с HTTP 200 и таким телом:

{"successful": false, "message": "Exception while trying to buy object, code 2023"}

Код указан в конце message; на остальной текст не опирайтесь.

Ответ	Причина	Что делать
Код 2023	Услуга уже активна или отправлен `resume` для активной подписки	Ничего делать не нужно
Код 2027	Дата окончания отстояла бы от текущего момента больше чем на 5 лет	Не продлевайте подписку сейчас
Код 40416	ID услуги не найден для вашего ID партнера	Убедитесь, что используете ID услуги, полученный от MEGOGO
Код 2009, 2010	Подписка не продается или не найдена	Сообщите в поддержку MEGOGO
HTTP 401, простой текст `Partner … not found`	IP-адреса вашего сервера нет в списке или указан неверный ID партнера	Отправьте запрос с сервера из списка. См. Учетные данные
HTTP 429	Больше 1 000 запросов в минуту с вашим ID партнера	Сократите число запросов
Тайм-аут, HTTP 5xx	Временный сбой	См. Повторные запросы

Полный список кодов приведен в справочнике по Billing API.

Дальнейшие шаги¶

Версия руководства 1.4.1, 2026-10-31 · Сообщить о проблеме на этой странице