openapi: 3.1.0
info:
  title: MEGOGO Partner Billing API (internet providers)
  version: 1.0.0
  summary: Activate MEGOGO subscriptions of your subscribers and give them a MEGOGO account.
  description: "The Partner Billing API for internet providers and other partners that\nsell MEGOGO subscriptions\
    \ to their subscribers: requests under\n`/partners/{partnerId}/` that identify the subscriber by your\
    \ identifier\n(contract number, account number or another ID in your billing).\n\n## Access\n\n- The\
    \ requests have no signature. MEGOGO identifies you by the partner\n  ID and by the IP address (IPv4)\
    \ of your server.\n- Send all requests from the IP addresses of your list.\n  `subscription/{operation}`,\
    \ `user/subscriptions` and\n  `user/changeCredentials` from other addresses get HTTP 401.\n- The \"\
    Try it out\" button is off. Send the requests from your server.\n\n## Identifier of the subscriber\n\
    \n`userId`, `identifier` and `isdn` are the same value: 1 to 254\ncharacters. Upper and lower case\
    \ are the same subscriber. A space at the\nend is ignored, a space at the start makes a different\
    \ subscriber.\n`user/create`, `user/innerId`, `user/changeCredentials`, `subscribe` and\n`resume`\
    \ make a MEGOGO user for a new identifier.\n\n## Limits\n\n1000 requests per minute for each partner\
    \ ID. Above this limit, you can\nget HTTP 429 Too Many Requests.\n\n## Test environment\n\nThere is\
    \ no separate test environment. Your MEGOGO manager gives you a\ntest partner ID and test service\
    \ IDs on production.\n\n## Responses and errors\n\nThe result of a request comes with HTTP 200:\n\n\
    ```json\n{\"successful\": false, \"message\": \"Exception while trying to buy object, code 2023\"\
    }\n```\n\nIf `message` ends with `code` and a number, use the number. Do not use\nthe rest of the\
    \ text. A missing parameter gives HTTP 400, a wrong HTTP\nmethod gives HTTP 406 with an empty body,\
    \ an unknown partner ID or an IP\naddress outside your list gives HTTP 401 with a plain text body.\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: Subscribe, unsubscribe, suspend or resume
      description: "Changes the subscription of a subscriber. If MEGOGO has no\nsubscriber with this identifier,\
        \ `subscribe` and `resume` make the\nsubscriber; `unsubscribe` and `suspend` give `\"successful\"\
        : true`\nand change nothing.\n\n- `subscribe` — start the subscription: one period from now. For\
        \ an\n  active subscription, the result depends on a MEGOGO setting of the\n  service: renewal\
        \ of an active subscription permitted → one\n  more period after the current end date; not permitted\
        \ (usually with\n  automatic renewal) → code 2023, no change.\n- `unsubscribe` — stop the subscription\
        \ immediately. Also stops a\n  suspended subscription: the suspended time is lost.\n- `suspend`\
        \ — stop the access until `resume`. The subscription is\n  not in `user/subscriptions` until `resume`.\n\
        - `resume` — start a suspended subscription again. The end date\n  moves forward by the time of\
        \ the suspension.\n\nWARNING: Send `resume` only after your own `suspend`. Without a\nsuspended\
        \ subscription, `resume` works as `subscribe`. Do not send\n`subscribe` while the subscription\
        \ is suspended.\n\n`unsubscribe` and `suspend` give `\"successful\": true` also when the\nsubscription\
        \ is not active.\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: 'Your identifier of the subscriber.

          '
        schema:
          $ref: '#/components/schemas/Identifier'
      - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: 'The result.

            '
          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: Get the active subscriptions of a subscriber
      description: 'The active subscriptions of the subscriber that you sell. A

        suspended subscription is not in the list. Two service IDs of one

        MEGOGO subscription make one item with the service ID of the last

        `subscribe`: use this service ID in `unsubscribe`.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - $ref: '#/components/parameters/identifier'
      responses:
        '200':
          description: 'The subscriptions, or `"successful": false` for an unknown subscriber.

            '
          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: Set the login and the password of the MEGOGO account
      description: 'Sets the login (an e-mail address) and the password with which the

        subscriber signs in to MEGOGO. Send it again to change the password

        or the login: the old login becomes free. If MEGOGO has no

        subscriber with this identifier, the request makes the subscriber.


        Before you change the password, get the current login with

        `user/innerId`: the subscriber can change the login in the MEGOGO

        profile.


        MEGOGO does not check the format of the login. Check it before the

        request.

        '
      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: 'The login. Unique in MEGOGO; upper and lower case are the same.

                    '
                  examples:
                  - 100245@your-isp.example
                password:
                  type: string
                  minLength: 6
                  description: 'The password. 6 or more characters.

                    '
            example:
              isdn: '100245'
              email: 100245@your-isp.example
              password: '{password}'
      responses:
        '200':
          description: 'The result.

            '
          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: Get the MEGOGO user ID and the current login
      description: 'Gives the MEGOGO user ID (`uid`) and, if the subscriber has a

        login, the current login (`email`). If MEGOGO has no subscriber with

        this identifier, the request makes the subscriber.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - $ref: '#/components/parameters/identifier'
      responses:
        '200':
          description: 'The MEGOGO user.

            '
          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: Make a MEGOGO user for a subscriber
      description: 'Makes a MEGOGO user for the identifier and gives the MEGOGO user ID.

        For an existing subscriber, gives the same `uid`. You do not have to

        send this request before the other requests.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - $ref: '#/components/parameters/identifier'
      responses:
        '200':
          description: 'The MEGOGO user ID, or an error.

            '
          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: Change the identifier of a subscriber
      description: 'Moves the subscriber to a new identifier. The MEGOGO user, the

        subscriptions and the login stay the same; the old identifier

        becomes free.


        WARNING: Do not send other requests with the new identifier before

        this request: they make a new MEGOGO user, and then this request

        gives an error.

        '
      parameters:
      - $ref: '#/components/parameters/partnerId'
      - name: identifier
        in: query
        required: true
        description: 'The old identifier of the subscriber.

          '
        schema:
          $ref: '#/components/schemas/Identifier'
      - name: newIdentifier
        in: query
        required: true
        description: 'The new identifier of the subscriber.

          '
        schema:
          $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: 'The MEGOGO user ID, or an error.

            '
          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: 'Your partner ID.

        '
      schema:
        type: string
        examples:
        - example_isp
    identifier:
      name: identifier
      in: query
      required: true
      description: 'Your identifier of the subscriber.

        '
      schema:
        $ref: '#/components/schemas/Identifier'
    serviceId:
      name: serviceId
      in: query
      required: true
      description: 'The service ID of the subscription. Your MEGOGO manager gives it.

        '
      schema:
        type: string
        examples:
        - example_service
  schemas:
    Identifier:
      type: string
      minLength: 1
      maxLength: 254
      description: 'Your identifier of the subscriber, for example the contract number.

        Upper and lower case are the same subscriber.

        '
      examples:
      - '100245'
    Result:
      type: object
      required:
      - successful
      properties:
        successful:
          type: boolean
        message:
          type: string
          description: 'The error text. If it ends with `code` and a number, use the number.

            '
    User:
      type: object
      required:
      - uid
      properties:
        uid:
          type: integer
          description: 'The MEGOGO user ID.

            '
        email:
          type: string
          description: 'The current login. Not in the response if the subscriber has no login.

            '
    UserSubscriptions:
      type: object
      required:
      - identifier
      - svod
      properties:
        identifier:
          type: string
        svod:
          type: array
          items:
            type: object
            properties:
              serviceId:
                type: string
              serviceName:
                type: string
                description: 'The name of the MEGOGO subscription.

                  '
              dateFinish:
                type: integer
                description: 'The end date, Unix time in seconds.

                  '
              dateFinishString:
                type: string
                description: 'The end date in UTC, `YYYY-MM-DD HH:MM:SS`.

                  '
  responses:
    BadRequest:
      description: 'A required parameter is not in the request.

        '
      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: 'The partner ID is not known, or the IP address is not in the list of your partner
        ID.

        '
      content:
        text/plain:
          schema:
            type: string
          example: Partner example_isp not found (ip /203.0.113.10)
    NotAcceptable:
      description: 'The HTTP method is not correct. The body is empty.

        '
    TooManyRequests:
      description: 'More than 1000 requests per minute for your partner ID.

        '
    ServerError:
      description: 'Temporary problem. See the retry rules.

        '