openapi: 3.0.0
info:
  description: |
    These APIs allow API consumers to create and enquire vouchers 
    for their customers. 

    # Introduction

    Omantel will give these APIs to their contractual clients so that those clients can create the voucher for their customers. These voucher creation will be based on the allocated limit to the client which means if client has already used his limit then he has to cooridinate with Omantel for the limit increase. Also, Client can create these vouchers for the available denominations.

    # API Functionality

    This API allows to clients to reward Omantel mobile customers.

    The API provides several endpoints/operations:
    - An endpoint to create the voucher.
    - An endpoint to enquire the about voucher of 
    - An endpoint to check denomination for voucher creation.
  version: 1.0.0
  title: Company Vouchers API
servers:
  - url: https://apigw.omantel.om
    variables:
      apiRoot:
        default: https://apigw.omantel.om
        description: API root
      basePath:
        default: /posapi
        description: Base path for the Makasib API
tags:
  - name: Voucher Denomination
    description: Operations to query about denominations
  - name: Voucher Enquiry
    description: Operations to query voucher
  - name: Voucher Creation
    description: Operations to create the voucher
    
paths:
  /posapi/pos/denomination:
    get:
      security:
        - oAuth2ClientCredentials: []
        
      tags:
        - Voucher Denomination
      summary: To view the denominations list
      operationId: getVoucherDenominations
      description: This is to view the denominations details.
      responses:
        200:
          description: OK
          headers:
            X-Client-ID:
              $ref: "#/components/headers/X-Client-ID"
          content:
            application/json:
                schema:
                  $ref: "#/components/schemas/PosVoucherDenominationResponse"
                examples:
                  0000:
                    summary: Success scenario
                    value:
                      denominations: ["5","10","20","40"]
        400:
          $ref: "#/components/responses/Generic400"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        409:
          $ref: "#/components/responses/Generic409"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
                      
  /posapi/pos/vouchers/{voucherSNo}:      
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Voucher Enquiry
      summary: Get the details of voucher posted to this service 
      operationId: getVoucherEnquiry
      description: Retrieve posted voucher's information based on some filtering criteria.
      parameters:
      - in: path
        name: voucherSNo
        description: This is voucher serial number to check the status
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          headers:
            X-Client-ID:
              $ref: "#/components/headers/X-Client-ID"
            X-App-ID:
              $ref: "#/components/headers/X-App-ID"
            X-Omantel-UUID:
              $ref: "#/components/headers/X-Omantel-UUID"
          content:
            application/json:
                schema:
                  $ref: "#/components/schemas/PosVoucherResponse"
                examples:
                  0000:
                    summary: Success scenario
                    value:
                      voucherSNo: "72509851831168"
                      amount: "40"
                      status: "Available"
                      startDate: "23-MAR-17"
                      endDate: "31-DEC-24"
                      voucherType: "BMCT"
                      creationDate: "23-MAR-17"
                      errorCode: "0000"
                      errorMessage: "SUCCESS"
        400:
          $ref: "#/components/responses/Generic400"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        409:
          $ref: "#/components/responses/Generic409"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"




  /posapi/pos/vouchers:
    post:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Voucher Creation
      summary: To create the voucher
      operationId: postVoucherCreation
      description: To create the voucher.
      requestBody:
        description: Perform redemption transaction
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateVouchers"
      responses:
        201:
          description: OK
          headers:
            X-Client-ID:
              $ref: "#/components/headers/X-Client-ID"
            X-App-ID:
              $ref: "#/components/headers/X-App-ID"
            X-Omantel-UUID:
              $ref: "#/components/headers/X-Omantel-UUID"
          content:
            application/json:
                schema:
                  $ref: "#/components/schemas/PosVoucherInfo"
                examples:
                  0000:
                    summary: Success scenario
                    value:
                      batchId: "12052024073302797"
                      posVouchers:
                        - voucherSNo: "BM1230761359"
                          amount: "10"
                          status: "Available"
                          startDate: "12-May-2024"
                          endDate: "11-Jun-2024"
                          voucherType: "BMCT"
                          creationDate: "12-05-2024 11:33:02 AM"
                        - voucherSNo: "BM8783367875"
                          amount: "10"
                          status: "Available"
                          startDate: "12-May-2024"
                          endDate: "11-Jun-2024"
                          voucherType: "BMCT"
                          creationDate: "12-05-2024 11:33:02 AM"
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                0001:
                  summary: Transaction code is missing which is internally managed
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Transaction code is missing"
                0002:
                  summary: Client Id is not passed
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Client Id is mandatory"
                0003:
                  summary: Client Id is invalid
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Client Id is invalid"
                0004:
                  summary: Valuation configuration is missing
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Valuation configuration is missing"
                0005:
                  summary: Available valuation limit has exhausted
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Available valuation limit has exhausted"
                0006:
                  summary: Remaining valuation is not sufficient for voucher gereneration
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Remaining valuation is not sufficient for voucher gereneration"

        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        409:
          $ref: "#/components/responses/Generic409"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"



components:
  schemas:
    ErrorInfo:
      type: object
      required:
        - code
        - status
        - message
      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
    PosVoucherResponse:
      type: object
      properties:
        voucherSNo:
          type: string
          description: voucher serial number
          example: "72509851831168"
        amount:
          type: string
          description: voucher amount
          example: "10"
        status:
          type: string
          description: voucher status
          example: "Available"
        startDate:
          type: string
          description: voucher validity start date
          example: "23-MAR-17"
        endDate:
          type: string
          description: voucher validity expiry date
          example: "31-DEC-17"
        voucherType:
          type: string
          description: voucher belongs to which client id
          example: "BMCT"
        creationDate:
          type: string
          description: voucher creation date and time
          example: "23-MAR-17"
        errorCode:
          type: string
          description: API's return code
          example: "0000"
        errorMessage:
          type: string
          description: API's return error message
          example: "SUCCESS"
          
    PosVoucherRequest:
      type: object
      properties:
        voucherSNo:
          type: string
          description: voucher serial number
        vendorId:
          type: string
          description: vendor's id
        userId:
          type: string
          description: logged in user id
        contactNo:
          type: string
          description: logged in user's contact number
        noofvouchers:
          type: string
          description: No of vouchers to be created
        denomination:
          type: string
          description: denomination for voucher creation
    
    PosVoucherInfo:
      type: object
      properties:
        batchId:
          type: string
          description: voucher batch id
          example: "23042024102730932"
        posVouchers:
            $ref: "#/components/schemas/PosVouchers"
    
    PosVouchers:    
      type: object
      properties:
        voucherSNo:
          type: string
          description: voucher serial number
          example: "BM2930715455"
        amount:
          type: string  
          description: voucher amount
          example: "10"
        status:
          type: string  
          description: voucher status
          example: "Available"
        startDate:
          type: string 
          description: voucher validity start date
          example: "23-Apr-2024"
        endDate:
          type: string 
          description: voucher validity end date
          example: "25-Apr-2024"
        voucherType:
          type: string 
          description: voucher amount
          example: "BMCT"
        creationDate:
          type: string 
          description: voucher amount
          example: "23-04-2024 10:27:28 AM"
    
    PosVoucherDenominationResponse:
      type: object
      properties:
        denominations:
          type: array
          items: 
             $ref: "#/components/schemas/denomination"
          description: String array
          example: ["5", "10", "20", "40", "50"]
    denomination:
      type: string
    CreateVouchers:
      type: object
      required:
      - contactNo
      - noofvouchers
      - denomination
      properties:
        contactNo:
          type: string
          description: Vendor contact number (Mobile Number or Fixed number ie 24244040).
        noofvouchers:
          type: string
          description: Number of vouchers which need to create.
        denomination:
          type: string
          description: Denomination number for the voucher creation.
  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: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified resource is not found"
    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: "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"

  headers:
    X-Client-ID:
      description: This is client's Id (Like BMCT for Bank Muscat)
      schema:
        type: string
    X-App-ID:
      description: application name or id
      schema:
        type: string
    X-Omantel-UUID:
      description: user id for tracking purpose
      schema:
        type: string
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigw.omantel.om/oauth2/accesstoken
          scopes: {}