openapi: 3.1.0
info:
  title: MEGOGO Partner Billing API (інтернет-провайдери)
  version: 1.0.0
  summary: Підключення передплат MEGOGO вашим абонентам і видача їм акаунта MEGOGO.
  description: "Partner Billing API для інтернет-провайдерів та інших партнерів, які\nпродають передплати\
    \ MEGOGO своїм абонентам: запити `/partners/{partnerId}/`,\nщо визначають абонента за вашим ідентифікатором\
    \ (номер договору, особового\nрахунку або інший ID у вашому білінгу).\n\n## Доступ\n\n- Запити не\
    \ підписуються. MEGOGO розпізнає вас за ID партнера та за\n  IP-адресою (IPv4) вашого сервера.\n-\
    \ Надсилайте всі запити з IP-адрес вашого списку.\n  `subscription/{operation}`, `user/subscriptions`\
    \ і `user/changeCredentials`\n  з інших адрес отримують HTTP 401.\n- Кнопку «Try it out» вимкнено.\
    \ Надсилайте запити зі свого сервера.\n\n## Ідентифікатор абонента\n\n`userId`, `identifier` і `isdn`\
    \ — одне значення: від 1 до 254 символів.\nРегістр не має значення. Пробіл у кінці ігнорується, пробіл\
    \ на початку\nстворює іншого абонента. `user/create`, `user/innerId`, `user/changeCredentials`,\n\
    `subscribe` і `resume` створюють користувача MEGOGO для нового\nідентифікатора.\n\n## Обмеження\n\n\
    1000 запитів на хвилину для кожного ID партнера. Понад цю межу можна\nотримати HTTP 429 Too Many Requests.\n\
    \n## Тестове середовище\n\nОкремого тестового середовища немає. Менеджер MEGOGO видає вам тестовий\n\
    ID партнера і тестові ID послуг на робочих серверах (production).\n\n## Відповіді та помилки\n\nРезультат\
    \ запиту приходить з HTTP 200:\n\n```json\n{\"successful\": false, \"message\": \"Exception while\
    \ trying to buy object, code 2023\"}\n```\n\nЯкщо `message` закінчується словом `code` і числом, орієнтуйтеся\
    \ на\nчисло, а не на решту тексту. Відсутній параметр дає HTTP 400, неправильний\nHTTP-метод — HTTP\
    \ 406 з порожнім тілом, невідомий ID партнера або IP-адреса\nпоза вашим списком — HTTP 401 з текстовим\
    \ тілом.\n"
  contact:
    name: MEGOGO partner support
    email: supportpartners@megogo.net
servers:
- url: https://billing.megogo.net
  description: 'Робочий сервер (production)

    '
tags:
- name: Subscriptions
- name: Subscribers
paths:
  /partners/{partnerId}/subscription/{operation}:
    get:
      tags:
      - Subscriptions
      operationId: changeSubscription
      summary: Підключити, відключити, призупинити або відновити передплату
      description: "Змінює передплату абонента. Якщо в MEGOGO немає абонента з таким\nідентифікатором,\
        \ `subscribe` і `resume` його створюють; `unsubscribe` і\n`suspend` повертають `\"successful\"\
        : true` і нічого не змінюють.\n\n- `subscribe` — підключити передплату: один період від поточного\
        \ моменту.\n  Для активної передплати результат залежить від налаштування послуги на боці MEGOGO:\
        \ продовження активної передплати дозволене → ще один період після поточної дати закінчення; не\
        \ дозволене (зазвичай для послуг з автоматичним продовженням) → код 2023, без змін.\n- `unsubscribe`\
        \ — відключити передплату одразу. Відключає й призупинену\n  передплату: призупинений залишок\
        \ втрачається.\n- `suspend` — припинити доступ до `resume`. До `resume` передплати немає в\n \
        \ `user/subscriptions`.\n- `resume` — знову ввімкнути призупинену передплату. Дата закінчення\n\
        \  зсувається на час призупинення.\n\nУВАГА: надсилайте `resume` лише після власного `suspend`.\
        \ Без призупиненої\nпередплати `resume` працює як `subscribe`. Не надсилайте `subscribe`, поки\n\
        передплата призупинена.\n\n`unsubscribe` і `suspend` повертають `\"successful\": true`, навіть\
        \ якщо\nпередплата не активна.\n"
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - name: operation
        in: path
        required: true
        schema:
          type: string
          enum:
          - subscribe
          - unsubscribe
          - suspend
          - resume
      - name: userId
        in: query
        required: true
        description: 'Ваш ідентифікатор абонента.

          '
        schema:
          $ref: '#/components/schemas/Identifier'
      - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: 'Результат.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              examples:
                ok:
                  summary: Successful
                  value:
                    successful: true
                alreadyActive:
                  summary: 'Code 2023: the subscription is already active'
                  value:
                    successful: false
                    message: Exception while trying to buy object, code 2023
                unknownService:
                  summary: 'Code 40416: the service ID is not configured for your partner ID'
                  value:
                    successful: false
                    message: Service id example_service for partner example_isp not found, code 40416
                unknownOperation:
                  summary: 'Code 40000: the operation is not known'
                  value:
                    successful: false
                    message: 'requirement failed: Invalid operation passed, code 40000'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /partners/{partnerId}/user/subscriptions:
    get:
      tags:
      - Subscriptions
      operationId: listUserSubscriptions
      summary: Отримати активні передплати абонента
      description: 'Активні передплати абонента, які продаєте ви. Призупиненої передплати

        в списку немає. Два ID послуг однієї передплати MEGOGO дають один елемент з

        ID послуги останнього `subscribe`: використовуйте цей ID в `unsubscribe`.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - $ref: '#/components/parameters/identifier'
      responses:
        '200':
          description: 'Передплати або `"successful": false` для невідомого абонента.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/UserSubscriptions'
                - $ref: '#/components/schemas/Result'
              examples:
                active:
                  summary: One active subscription
                  value:
                    identifier: '100245'
                    svod:
                    - serviceId: example_service
                      serviceName: SVOD partners
                      dateFinish: 1796750920
                      dateFinishString: '2026-12-08 17:28:40'
                none:
                  summary: No active subscriptions
                  value:
                    identifier: '100245'
                    svod: []
                unknown:
                  summary: MEGOGO has no subscriber with this identifier
                  value:
                    successful: false
                    message: User not found
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
  /partners/{partnerId}/user/changeCredentials:
    post:
      tags:
      - Subscribers
      operationId: changeCredentials
      summary: Задати логін і пароль акаунта MEGOGO
      description: 'Задає логін (адресу e-mail) і пароль, з якими абонент входить у MEGOGO.

        Надішліть запит повторно, щоб змінити пароль або логін: старий логін

        звільняється. Якщо в MEGOGO немає абонента з таким ідентифікатором, запит

        його створює.


        Перед зміною пароля отримайте поточний логін запитом `user/innerId`:

        абонент може змінити логін у профілі MEGOGO.


        MEGOGO не перевіряє формат логіна. Перевіряйте його перед запитом.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - isdn
              - email
              - password
              properties:
                isdn:
                  $ref: '#/components/schemas/Identifier'
                email:
                  type: string
                  format: email
                  description: 'Логін. Унікальний у MEGOGO; регістр не має значення.

                    '
                  examples:
                  - 100245@your-isp.example
                password:
                  type: string
                  minLength: 6
                  description: 'Пароль. Щонайменше 6 символів.

                    '
            example:
              isdn: '100245'
              email: 100245@your-isp.example
              password: '{password}'
      responses:
        '200':
          description: 'Результат.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              examples:
                ok:
                  summary: Successful
                  value:
                    successful: true
                emailUsed:
                  summary: Another MEGOGO user has this login
                  value:
                    successful: false
                    message: Other users already have this email
                shortPassword:
                  summary: The password has fewer than 6 characters
                  value:
                    successful: false
                    message: Invalid password
                noPassword:
                  summary: No password in the request
                  value:
                    successful: false
                    message: Parameter password should not be empty or null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /partners/{partnerId}/user/innerId:
    get:
      tags:
      - Subscribers
      operationId: getInnerId
      summary: Отримати ID користувача MEGOGO і поточний логін
      description: 'Повертає ID користувача MEGOGO (`uid`) і, якщо в абонента є логін,

        поточний логін (`email`). Якщо в MEGOGO немає абонента з таким

        ідентифікатором, запит його створює.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - $ref: '#/components/parameters/identifier'
      responses:
        '200':
          description: 'Користувач MEGOGO.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                withLogin:
                  summary: The subscriber has a login
                  value:
                    uid: 1234567890
                    email: 100245@your-isp.example
                noLogin:
                  summary: The subscriber has no login
                  value:
                    uid: 1234567890
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /partners/{partnerId}/user/create:
    get:
      tags:
      - Subscribers
      operationId: createUser
      summary: Створити користувача MEGOGO для абонента
      description: 'Створює користувача MEGOGO для ідентифікатора й повертає ID користувача

        MEGOGO. Для наявного абонента повертає той самий `uid`. Надсилати цей запит

        перед іншими не обов''язково.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - $ref: '#/components/parameters/identifier'
      responses:
        '200':
          description: 'ID користувача MEGOGO або помилка.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/User'
                - $ref: '#/components/schemas/Result'
              examples:
                ok:
                  summary: Successful
                  value:
                    uid: 1234567890
                tooLong:
                  summary: 'Code 40000: the identifier has more than 254 characters'
                  value:
                    successful: false
                    message: 'requirement failed: ISDN must be less 255 symbols, code 40000'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /partners/{partnerId}/user/changeLogin:
    get:
      tags:
      - Subscribers
      operationId: changeIdentifier
      summary: Змінити ідентифікатор абонента
      description: 'Переносить абонента на новий ідентифікатор. Користувач MEGOGO,

        передплати й логін не змінюються; старий ідентифікатор звільняється.


        УВАГА: не надсилайте інших запитів з новим ідентифікатором до цього

        запиту: вони створюють нового користувача MEGOGO, і тоді цей запит

        поверне помилку.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - name: identifier
        in: query
        required: true
        description: 'Старий ідентифікатор абонента.

          '
        schema:
          $ref: '#/components/schemas/Identifier'
      - name: newIdentifier
        in: query
        required: true
        description: 'Новий ідентифікатор абонента.

          '
        schema:
          $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: 'ID користувача MEGOGO або помилка.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/User'
                - $ref: '#/components/schemas/Result'
              examples:
                ok:
                  summary: Successful
                  value:
                    uid: 1234567890
                notFound:
                  summary: MEGOGO has no subscriber with the old identifier
                  value:
                    successful: false
                    message: User 100245 not found for partner example_isp
                same:
                  summary: The two identifiers are the same
                  value:
                    successful: false
                    message: 'requirement failed: ISDNs must be different'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    partnerId:
      name: partnerId
      in: path
      required: true
      description: 'Ваш ID партнера.

        '
      schema:
        type: string
        examples:
        - example_isp
    identifier:
      name: identifier
      in: query
      required: true
      description: 'Ваш ідентифікатор абонента.

        '
      schema:
        $ref: '#/components/schemas/Identifier'
    serviceId:
      name: serviceId
      in: query
      required: true
      description: 'ID послуги передплати. Його видає менеджер MEGOGO.

        '
      schema:
        type: string
        examples:
        - example_service
  schemas:
    Identifier:
      type: string
      minLength: 1
      maxLength: 254
      description: 'Ваш ідентифікатор абонента, наприклад номер договору. Регістр не має

        значення.

        '
      examples:
      - '100245'
    Result:
      type: object
      required:
      - successful
      properties:
        successful:
          type: boolean
        message:
          type: string
          description: 'Текст помилки. Якщо він закінчується словом `code` і числом, орієнтуйтеся на число.

            '
    User:
      type: object
      required:
      - uid
      properties:
        uid:
          type: integer
          description: 'ID користувача MEGOGO.

            '
        email:
          type: string
          description: 'Поточний логін. Його немає у відповіді, якщо в абонента немає логіна.

            '
    UserSubscriptions:
      type: object
      required:
      - identifier
      - svod
      properties:
        identifier:
          type: string
        svod:
          type: array
          items:
            type: object
            properties:
              serviceId:
                type: string
              serviceName:
                type: string
                description: 'Назва передплати MEGOGO.

                  '
              dateFinish:
                type: integer
                description: 'Дата закінчення, час Unix у секундах.

                  '
              dateFinishString:
                type: string
                description: 'Дата закінчення в UTC, `YYYY-MM-DD HH:MM:SS`.

                  '
  responses:
    BadRequest:
      description: 'У запиті немає обов''язкового параметра.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: integer
              result:
                type: string
          example:
            message: Invalid request format
            code: 400
            result: error
    Unauthorized:
      description: 'Partner ID невідомий, або IP-адреси немає в списку вашого ID партнера.

        '
      content:
        text/plain:
          schema:
            type: string
          example: Partner example_isp not found (ip /203.0.113.10)
    NotAcceptable:
      description: 'Неправильний HTTP-метод. Тіло порожнє.

        '
    TooManyRequests:
      description: 'Понад 1000 запитів на хвилину для вашого ID партнера.

        '
    ServerError:
      description: 'Тимчасова проблема. Див. правила повторних запитів.

        '