openapi: 3.0.3
info:
  title: MPL VAS subscription management API
  description: |
    This API specification is describing interface provided by MPL to trusted 3rd party
    systems to access and manipulate information about value added service subscripions.
    
    Change log:
    
    * 1.1.0
        *
  contact:
    email: apiteam@mygp.global
  version: "1.1.0-DRAFT"
servers:
- url: /v1
tags:
- name: VAS service catalog
  description: |
    Operations focused on providing general information about VAS offering.
- name: VAS subscription management
  description: |
    Operations focused on management of VAS subscriptions
security:
  - oidc_bearer_token: [ ]
paths:
  /vas/catalog:
    parameters:
      - $ref: '#/components/parameters/ClientSessionIdHeader'
      - $ref: '#/components/parameters/ClientRequestIdHeader'
    get:
      tags:
      - VAS service catalog
      summary: Get VAS catalog information
      description: |
        MPL server is asked to provide general information about available VAS offering.
      operationId: getVASCatalog
      responses:
        200:
          description: |
            Request was accepted and processed by the MPL server. 
            Requested information is provided as JSON object in the respose body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVASCatalogResponse'
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
  /vas/subscriptions/{bizid}/{slug}:
    parameters:
      - $ref: '#/components/parameters/ClientSessionIdHeader'
      - $ref: '#/components/parameters/ClientRequestIdHeader'
      - $ref: "#/components/parameters/BusinessIdPathParam"
      - $ref: "#/components/parameters/SlugPathParam"
    get:
      tags:
      - VAS subscription management
      summary: Get VAS subscription configuration
      description: |
        MPL server is asked to provide information about configuration of specific VAS subscription(s).
      operationId: getVASSubscriptionConfiguration
      responses:
        200:
          description: |
            Request was accepted and processed by the MPL server. 
            Requested information is provided as JSON object in the respose body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVASSubscriptionConfigurationResponse'
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
    put:
      tags:
      - VAS subscription management
      summary: Modify VAS subscription configuration
      description: |
        MPL server is asked to modify configuration of specific VAS suscription(s).
      operationId: modifyVASSubscriptionConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyVASSubscriptionConfigurationRequest'
      responses:
        204:
          $ref: "#/components/responses/204"
        206:
          description: |
            Request was accepted and partially processed by the MPL server -
            some resources were updated and some were not. Details about unapplied
            changes are provided in the `errors` collection inside the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyVASSubscriptionConfigurationResponse'
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
  /vas/subscriptions/{bizid}/{slug}/orders:
    parameters:
      - $ref: '#/components/parameters/ClientSessionIdHeader'
      - $ref: '#/components/parameters/ClientRequestIdHeader'
      - $ref: "#/components/parameters/BusinessIdPathParam"
      - $ref: "#/components/parameters/SlugPathParam"
    get:
      tags:
      - VAS subscription management
      summary: Get information about pending or in-progress VAS subscription orders
      description: |
        MPL server is asked to provide information about pending or in-progress orders for specific VAS subscription(s).
      operationId: getVASSubscriptionOrders
      responses:
        200:
          description: |
            Request was accepted and processed by the MPL server. 
            Requested information is provided as JSON object in the respose body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVASSubscriptionOrdersResponse'
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
    post:
      tags:
      - VAS subscription management
      summary: Place subscription activation order(s)
      description: |
        MPL server is asked to initiate activation for one or more VAS subscription(s).
      operationId: activateVASSubscription
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateVASSubscriptionRequest'
      responses:
        201:
          description: |
            Request was accepted and resources were created by the MPL server. 
            Resource information is provided as JSON object in the respose body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateVASSubscriptionResponse'
        206:
          description: |
            Request was accepted and partially processed by the MPL server -
            some resources were created and some were not. Resource information is 
            provided as JSON object in the respose body. Details about orders
            that were not create are provided in the `errors` collection inside
            the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateVASSubscriptionResponse'
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
  /vas/subscriptions/{bizid}/{slug}/orders/{orderid}:
    parameters:
      - $ref: '#/components/parameters/ClientSessionIdHeader'
      - $ref: '#/components/parameters/ClientRequestIdHeader'
      - $ref: "#/components/parameters/BusinessIdPathParam"
      - $ref: "#/components/parameters/SlugPathParam"
      - $ref: "#/components/parameters/OrderIdPathParam"
    get:
      tags:
      - VAS subscription management
      summary: Get information about specific VAS subscription order
      description: |
        MPL server is asked to provide information about specific VAS subscription order.
      operationId: getVASSubscriptionOrderInfo
      responses:
        200:
          description: |
            Request was accepted and processed by the MPL server. 
            Requested information is provided as JSON object in the respose body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVASSubscriptionOrderInfoResponse'
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
components:
  parameters:
    ClientSessionIdHeader:
      name: X-Correlation-ID
      in: header
      description: |
        If header is supplied the value is written out into logs to simplify grouping of client requests during 
        troubleshooting. No validation is performed on the value. When request is submitted by MPL, GUID/UUID values 
        are used for this purpose. Requests that are submitted as part of the same task/job/session will use the same 
        value for this header. If request header is present, then a response header named X-Correlation-ID should be 
        replied back in the response from the server.
      required: false
      schema:
        type: string
    ClientRequestIdHeader:
      name: X-Request-ID
      in: header
      description: |
        If header is supplied the value is written out into logs to simplify correlation of requests during 
        troubleshooting. No validation is performed on the value. When request is submitted by MPL, GUID/UUID 
        values are used for this purpose. If request header is present, then a response header named X-Request-ID 
        should be replied back in the response from the server.
      required: false
      schema:
        type: string
    BusinessIdPathParam:
      name: bizid
      in: path
      description: |
        Unique identifier of the merchant. IČO.
      required: true
      schema:
        type: string
    SlugPathParam:
      name: slug
      in: path
      description: |
        Human readable key that uniquely identifies resource.
      required: true
      schema:
        type: string
    OrderIdPathParam:
      name: orderid
      in: path
      description: |
        Unique ID of the subscription order.
      required: true
      schema:
        type: string
        format: uri
  schemas:
    ApiResponse:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 200
        message:
          type: string
          example: SUCCESS
        description:
          type: string
          example: Request was completed successfully.
    PricingInfo:
      type: object
      required:
        - not_before
        - not_before
        - amount
      properties:
        not_before:
          type: string
          format: date
          example: "2023-08-01"
        not_after:
          type: string
          format: date
          example: "2023-09-01"
        amount:
          type: string
          example: "8.99"
          description: |
            String formatted as decimal number with up to 2 decimal places.
            Dot character is used as decimal separator.
    VASServiceInfo:
      type: object
      required:
        - slug
        - title
        - logo
        - status
        - activation_level
      properties:
        slug:
          type: string
          example: "vas-service-1"
        title:
          type: string
          example: "VAS Service 1"
        logo:
          type: string
          example: "https://static.mygp.global/vas/vas-service-1/logo.png"
        status:
          type: string
          enum:
            - PREVIEW
            - GENERALLY_AVAILABLE
            - DEPRECATED
            - RETIRED
          example: "GENERALLY_AVAILABLE"
          description: |
            The status indicates the readiness and level of availability for the VAS offer.
            **PREVIEW** offers are reserved for selected (test) customers only. **GENERALLY_AVAILABLE**
            offers are available to all customers. **DEPRECATED** offers can no longer be activated,
            but existing subscriptions can be managed. **RETIRED** offers must no longer be available
            for management and/or activation.
            Primary use case for informatio provided in the status field is to allow UI applications
            to dynamicaly reveal or hide specific VAS offering to/from presentation, without the need
            for re-deployment.
        activation_level:
          type: string
          enum:
            - COMPANY
            - MID
          example: "COMPANY"
    VASSubscriptionInfo:
      type: object
      required:
        - id
        - ref
        - is_free_trial
        - selected_for_renewal
        - locked_for_change
        - modification_in_progress
        - plan
        - pricing
      properties:
        id:
          type: string
          example: "a90333dd-9a11-4bac-a2d2-bbab83c13c3b"
        ref:
          type: string
          example: "business_id-or-mid"
        is_free_trial:
          type: boolean
        selected_for_renewal:
          type: boolean
        locked_for_change:
          type: boolean
        modification_in_progress:
          type: boolean
        plan:
          type: string
          example: "vas-service-1-standard-plan"
        pricing:
          type: object
          required:
            - currency
            - current_cyle
          properties:
            currency:
              type: string
              example: "EUR"
            current_cyle:
              $ref: "#/components/schemas/PricingInfo"
            next_cycle:
              $ref: "#/components/schemas/PricingInfo"
        redirect_url:
          type: string
          example: https://example.com/redirect-to
    VASSubscriptionModInfo:
      type: object
      required:
        - id
        - ref
        - selected_for_renewal
      properties:
        id:
          type: string
          example: "a90333dd-9a11-4bac-a2d2-bbab83c13c3b"
        ref:
          type: string
          example: "business_id-or-mid"
        selected_for_renewal:
          type: boolean
    VASSubscriptionModErrorInfo:
      type: object
      required:
        - ref
        - code
        - description
      properties:
        ref:
          type: string
          example: "business_id-or-mid"
        code:
          type: string
          example: "INVALID_REF"
        description:
          type: string
          example: "Reference cannot be resolved in the context of business ID."
    VASSubscriptionOrderInfo:
      type: object
      required:
        - ref
        - order_id
        - status
      properties:
        id:
          type: string
          example: "a90333dd-9a11-4bac-a2d2-bbab83c13c3b"
        ref:
          type: string
          example: "business_id-or-mid"
        status:
          type: string
          enum:
            - CREATED
            - PENDING
            - QUEUED
            - EXECUTING
            - COMPLETED
            - FAILED
    VASSubscriptionOrderErrorInfo:
      type: object
      required:
        - ref
        - code
        - description
      properties:
        ref:
          type: string
          example: "business_id-or-mid"
        code:
          type: string
          example: "INVALID_REF"
        description:
          type: string
          example: "Reference cannot be resolved in the context of business ID."
    ActivationInput:
      type: object
      required:
        - ref
      properties:
        ref:
          type: string
          example: "business_id-or-mid"
    GetVASCatalogResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VASServiceInfo"
    GetVASSubscriptionConfigurationResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VASSubscriptionInfo"
    ModifyVASSubscriptionConfigurationRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VASSubscriptionModInfo"
    ModifyVASSubscriptionConfigurationResponse:
      type: object
      required:
        - data
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/VASSubscriptionModErrorInfo"
    GetVASSubscriptionOrdersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VASSubscriptionOrderInfo"
    ActivateVASSubscriptionRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ActivationInput"
    ActivateVASSubscriptionResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VASSubscriptionOrderInfo"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/VASSubscriptionOrderErrorInfo"
    GetVASSubscriptionOrderInfoResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/VASSubscriptionOrderInfo"
  responses:
    204:
      description: |
        Request was accepted and processed by the MPL server without errors.
        No content is provided in the response.
    400:
      description: |
        Request did not pass validation on the MPL server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
          example:
            code: 400
            message: "BAD REQUEST"
            description: "Validation errors ..."
    401:
      description: |
        Authentication credentials (JWT token) were missing or could not be validated by the MPL server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
          example:
            code: 401
            message: "NOT AUTHENTICATED"
            detail: "Authentication credentials were not provided."
    403:
      description: |
        Authentication credentials do not carry authorisation required by the MPL server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
          example:
            code: 403
            message: "NOT AUTHORISED"
            detail: "Bearer is not authorised to make the request."
    404:
      description: |
        Subscription does not exist in the MPL inventory.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
          example:
            code: 404
            message: "NOT FOUND"
            description: "Referenced subscription record does not exist."
    409:
      description: |
        Request is structured correclty but cannot be accepted due to a conflict detected by the MPL server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
          example:
            code: 409
            message: "CONFLICT"
            detail: "Unexpected subscription update ..."
  securitySchemes:
    oidc_bearer_token:
      type: http
      scheme: bearer