openapi: 3.0.3
info:
  description: |
    API to check the usage of data, voice and SMS services of the Mobile Number. 

    # Introduction

    This API lets API Consumers to check usage of data, voice and SMS services of the number.

    # API resources 
    
    # Further info and support

    (FAQs will be added in a later version of the documentation)
  version: 1.0.0
  title: Usage Inquiry Service
  termsOfService: https://api.omantel.om/docs/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://apigw.omantel.om
    variables:
      apiRoot:
        default: https://apigw.omantel.om
        description: API root
      basePath:
        default: /usage-inquiry-service/v1
        description: Base path for the Usage Inquiry Service
tags:
  - name: Usage Inquiry
    description: Operation to check usage of data, voice and SMS services
paths:
  /usage-inquiry-service/v1/usages/{mobileNumber}:
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Usage Inquiry
      summary: Check usage of the number 
      operationId: getUsages
      description: Returns usage of data, voice and SMS services for the specified number 
      parameters:
        - name: mobileNumber
          in: path
          description: Mobile number of Omantel customer with or without country code.
          example: 9250xxxx
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageDetails"

        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:
    Summary:
      type: object
      properties:
        used:
          type: number
          format: double
          example: 150.00
          description: Amount already utilized by the user
        quota:
          type: number
          format: double
          description: Maximum Limit of the plan. If it is unlimited, then its value will be -1
          example: 500.00
        balance:
          type: number
          format: double
          description: Remaining amount. If it is unlimited, then its value will be -1.
          example: 350.00
        unit:
          type: string
          description: Units of the package
          enum:
            - GB
            - MB
            - KB 
            - Minute
            - RO 
            - SMS
          example: MB  
        isUnlimited:
          type: boolean
          description: true if it is unlimited plan, false otherwise.
          example: false
    
    UsageDetails:
      type: object
      properties:
        usageSummary:
          $ref: "#/components/schemas/UsageSummary"
          description: Usage summary of data, voice and SMS services
        products:
          type: array
          items:
            $ref: "#/components/schemas/Product"
        subscriber:
          $ref: "#/components/schemas/Subscriber"
          description: Subscriber detail                    
    UsageSummary:
      type: object
      properties:
        data:
          type: object
          $ref: "#/components/schemas/Summary"
          description: Summary for Data plans
        voice:
          type: object
          $ref: "#/components/schemas/Summary"
          description: Summary for Voice (Minutes) plans 
        sms:
          type: object
          $ref: "#/components/schemas/Summary"
          description: Summary for SMS plans
    CharacteristicValue:
      type: object
      properties:
        Name:
          type: string
          example: "PREPAID_BALANCE"
        Value:
          type: string
          example: "2.147"  
    Product:
        type: object
        properties:
          productId:
            type: string
            description: Product ID of the product
            example: "1170842"
          productName:
            type: string
            description: Product name 
            example: "New Hayyak 18 - 600 Minutes National, India, Pakistan & Bangladesh"
          status:
            type: string
            description: Status of the product like Active or Inactive
            example: "Active"
          balanceAmount:
            type: number
            format: double
            description: Balance amount of the product
            example: 395.00
          validFrom:
            type: string
            format: date-time
            description: STart date of the product
            example: "2021-12-10T20:32:54.000"
          validTo:
            type: string
            format: date-time
            description: Expiry date of the product
            example: "2022-01-07T20:32:54.000"
          unit:
            type: string
            description: GB -> Gigabyte, MB -> Megabyte, KB -> Kilobytes, RO -> Oman Riyals
            enum:
              - GB
              - MB
              - KB 
              - Minute 
              - RO 
              - SMS
            example: GB
          isMultipleSubscriptionAllowed:
            type: boolean
            description: Whether multiple subscriptions are allowed or not
            example: true
          isRoaming:
            type: boolean
            description: Whether it is a roaming product or not
            example: false
          isUnlimited:
            type: boolean
            description: Whether it is a unlimited product or not
            example: yes
          upperCapBalance:
            type: number
            format: double
            description: Upper cap limit value
            example: 600
          characteristicValueList:
            type: array
            description: Other extra details of the product
            items:
              $ref: '#/components/schemas/CharacteristicValue'   
    Subscriber:
      type: object
      properties:
        subscriberNo:
          type: string
          example: "96891912254"
        communicationLanguage:
          type: string
          enum:
            - English
            - Arabic  
          example: English
        lineExpiryDate:
          type: string
          format: date-time
          description: Expiry date of this number
          example: "2022-07-09T10:59:45.000"
        status:
          type: string
          enum:
            - Active
            - Inactive
            - Suspended
            - Blocked
          example: "Active"
        characteristicValueList:
          type: array
          description: Other extra details of the subscriber
          items:
            $ref: '#/components/schemas/CharacteristicValue'                        
    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_ARGUMENT
            status: 400
            message: "Schema validation failed at  ..."
    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: Customer Not Found - check if specified mobile number is a valid Omantel customer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified mobile number is not found"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVER_ERROR
            status: 500
            message: "Server Error"
    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"
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigw.omantel.om/oauth2/accesstoken
          scopes: {}