Продаж передплати¶

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

Перед початком роботи¶

Переконайтеся, що:

у вас є ID партнера та ID послуг ваших передплат (див. Облікові дані);
MEGOGO додав 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 · Повідомити про проблему на цій сторінці