openapi: 3.1.0
info:
  title: MEGOGO Partner Billing API (интернет-провайдеры)
  version: 1.0.0
  summary: Подключение подписок MEGOGO вашим абонентам и выдача им аккаунта MEGOGO.
  description: "Partner Billing API для интернет-провайдеров и других партнеров,\nкоторые продают подписки\
    \ MEGOGO своим абонентам: запросы\n`/partners/{partnerId}/`, которые определяют абонента по вашему\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\
    \n1000 запросов в минуту для каждого ID партнера. Сверх этого лимита можно\nполучить HTTP 429 Too\
    \ Many Requests.\n\n## Тестовая среда\n\nОтдельной тестовой среды нет. Менеджер MEGOGO выдает вам\
    \ тестовый\nID партнера и тестовые 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,\nнеправильный\
    \ HTTP-метод — HTTP 406 с пустым телом, неизвестный ID партнера\nили IP-адрес вне вашего списка —\
    \ 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`. Не\nотправляйте `subscribe`, пока подписка приостановлена.\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: 'Временная проблема. См. правила повторных запросов.

        '