openapi: 3.0.3
info:
  title: Mobile Plan Type Lookup Service
  description: |
    This microservice provides the plan type (prepaid or postpaid) associated with
    a given mobile number (MSISDN).
    It allows external systems to query and identify the mobile subscription type 
    for business logic such as billing, KYC, service provisioning, etc..
    
    # Further info and support

    (FAQs will be added in a later version of the documentation)
  version: 1.0.0
  termsOfService: http://swagger.io/terms/
  contact:
    email: MiddlewareESB@omantel.om
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Product documentation at https://developer.omantel.om/
  url: https://developer.omantel.om/
servers:
  - url: https://apigwsb.omantel.om
    variables:
      apiRoot:
        default: https://apigwsb.omantel.om
        description: API root
      basePath:
        default: /mobile-plan-type-lookup-service/v1
        description: Base path for mobile plan type lookup Service
paths:
  /mobile-plan-type-lookup-service/v1/mobile-plan-type/{msisdn}:
    get:
      security:
        - oAuth2ClientCredentials: []
      summary: Get plan type for a mobile number
      operationId: getMobilePlanType
      description: |
        This operation returns whether a given mobile number is associated
        with a prepaid or postpaid plan. 
      parameters:
        - name: msisdn
          in: path
          description: Mobile number of the customer with or without country code. 
          required: true
          schema:
            type: string
            minLength: 8
            maxLength: 11 
            pattern: '^(\+?\d{8,15})$' 
            example: '9689xxxxxxx'
        - name: mock-key
          in: query
          description: The mock-key parameter is used to simulate different response scenarios. Choose one of the available keys. 
            **NOTE:- Mock keys are only applicable for sandbox environment and only give you mock responses.**
          required: true
          schema:
            type: string
            enum:
              - plan-type-lookup-get-200
              - plan-type-lookup-get-400
              - plan-type-lookup-get-401
              - plan-type-lookup-get-403
              - plan-type-lookup-get-404
              - plan-type-lookup-get-500
              - plan-type-lookup-get-503
              - plan-type-lookup-get-504
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MobilePlanTypeResponse"
              examples:
                PrepaidExample:
                  summary: Prepaid response example
                  value:
                    msisdn: "9689250xxxx"
                    planType: "PREPAID"
                PostpaidExample:
                  summary: Postpaid response example
                  value:
                    msisdn: "9689260xxxx"
                    planType: "POSTPAID"

        400:
          $ref: "#/components/responses/Generic400"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        404:
          $ref: "#/components/responses/Generic404"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
components:
  schemas:
    MobilePlanTypeResponse:
      type: object
      properties:
        msisdn:
          type: string
          description: Mobile number of the Omantel customer
          example: "+9689250xxxx"
        planType:
          type: string
          enum: [PREPAID, POSTPAID]
          description: Indicates if the number is prepaid or postpaid
          example: "PREPAID"
      required:
        - msisdn
        - planType
    ErrorInfo:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          description: Code given to this error
        status:
          type: string
          description: HTTP response status code
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INVALID_MSISDN
            status: 400
            message: "The mobile number format is invalid. Please use international format (e.g., +9689250000)."
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAUTHORIZED
            status: 401
            message: "Authorization failed: ..."
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: FORBIDDEN
            status: 403
            message: "Operation not allowed: ..."
    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "No subscription information found for the given mobile number."
    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 409
            code: ALREADY_EXISTS
            message: "A specified resource duplicate entry found"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVER_ERROR
            status: 500
            message: "An unexpected error occurred. Please try again later."
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVICE_UNAVAILABLE
            status: 503
            message: "Service unavailable"
    Generic504:
      description: Request timeout exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: REQUEST_TIMEOUT_EXCEEDED
            status: 504
            message: "Request timeout exceeded"
  parameters:
    msisdn:
      name: msisdn
      in: query
      description: Phone number of the customer. It must be a valid mobile number of the customer with or without country code
      example: "92xxxxxx"
      schema:
        type: string
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigwsb.omantel.om/oauth2/accesstoken
          scopes: {}