swagger: '2.0'
info:
  description: callmeback API  will be used to post a request in AYO, when initiated by  Users via different Applications like "portal", "IVR" etc.
  version: "v1.0"
  title: Callmeback V1
schemes:
  - https
host: "za.api.mtn.com"
consumes:
  - "application/json"
produces:
  - "application/json"
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: X-API-Key
    in: header
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
  - ApiKeyAuth: []
  - OAuth2: []
paths:
      "/ayo/v1/callmeback":
        post:
          tags:
          - Callmeback
          description: Accept a callmeback request and send to downstream system layer.
          operationId: callmebackUsingPOST
          consumes:
          - application/json
          produces:
          - application/json
          parameters:
          - in: body
            name: Callmeback Data
            description: Callmeback data 
            required: true
            schema:
              $ref: "#/definitions/CallMeBackRequest"
          - name: transactionId
            in: header
            description: transactionId is unique id sent by 3pp to track the request.
            type: string
          - name: x-origin-channelId 
            in: header
            type: string
            description: provides informtion source system(3PP) like 'MTNWeb', 'IVR','MoMoAPP', 'USSD'
            required: true
          - name: transactionDate
            type: string
            in: header
            description: '2020-08-12T12:05:36.484Z'
            required: true
          - name: targetSystem
            type: string
            in: header
            description: AYO-MTN-ZAF
            required: true
          responses:
            '200':
              description: OK
              schema:
               $ref: "#/definitions/Success"
            '400':
              description: Business Error
              schema:
               $ref: "#/definitions/Error"
            '401':
              description: Unauthorized
              schema:
               $ref: "#/definitions/Error"
            '403':
              description: Forbidden
              schema:
               $ref: "#/definitions/Error"              
            '404':
              description: Not Found
              schema:
               $ref: "#/definitions/Error"  
            '500':
              description: internal server error
              schema:
               $ref: "#/definitions/Error"
definitions:
      CallMeBackRequest:
        required:
        - id
        - idType
        - name                  
        - reason
        - information
        description: Callmeback
        properties:
          id:
            description: id is a string which countains a value, if  id is msisdn (MADAPI Encrypts msisdn as per AYO encryption Requirement), In the logs Msisdn can be shown as encrypted and nonencrypted format(DTqlExQCSuW7K+hoes45mg==)
            example: '2345676788'
            type: string
          idType:
            enum:
            - 'MSISDN'
            type: string
            description: type of id
            example: MSISDN
          information:
            type: string
            $ref: "#/definitions/information"
      information:
        type: object
        description: defines all the fields for callmeback request for AYO
        required:
        - name
        - reason
        properties:
          name:
            description: Name of the user sent by channel as a string.(Maxlength-30,Minlength-2)
            example: 'John Smith'
          reason:
            type: string
            enum:
             - 'Claim related'
             - 'Cover related'
             - 'Payment related'
             - 'Mobile number change'
             - 'Other'   
             - 'Lead'
             - 'Service Enqiry'
             - 'Complaint'
            description: Reasons for callmeback request, selected by user and sent to MADAPI by channels for IVR- 'Service Enquiry' and 'Complaint', for MTNWeb 'Claim related',  'Cover related','Payment related','Mobile Number Change','Other', for MoMoAPP and USSD 'Lead'
            example: 'claiam Query'
          preferredTimeSlotCode:
            type: string
            description: TimeSlots are selected by users and Sent MADAPI and below logic is applied to define Timeslot and is sent to southbound system Morning(8AM-12PM),Afternoon(12PM-6PM) and 'Unknown', if no value is sent MADAPI sends as 'Unknown'
            example: 'Afternoon'
          policyHolderMsisdn:
            type: string
            description: msisdn is  number sent by 3pp  (MADAPI Encrypts msisdn as per AYO encryption Requirement), In the logs Msisdn can be shown as encrypted and nonencrypted format(DTqlExQCSuW7K+hoes45mg==)
            example: '233456786'
          policyHolderIdNumber:
            type: string
            description: policyHolderIdNumber is a input value sent by channels to southbound system(AYO)(MADAPI Encrypts msisdn as per AYO encryption Requirement), In the logs Msisdn can be shown as encrypted and nonencrypted format(DTqlExQCSuW7K+hoes45mg==)
            example: 'SP19363JS'
          description:
            type: string
            description: Free Text field for further information into the  reason descriptions,User can provide additional information 
            example: 'Claims query '
          customerInfoShareConsent:
            type: boolean
            description: CustomerInfoShareConsent is a boolean value which will be sent by channels and  MADAPI Sends to backend
            example: 'true'
      Success:
        type: object
        required:
        - "statusCode"
        - "statusMessage"
        - "transactionId"
        - "supportMessage"
        properties:
          statusCode:
            type: string
            description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned.
            example: '0000'
          statusMessage:
            type: string
            description: More details and corrective actions related to the error which can be shown to a client
            example: 'success'
          transactionId:
            type: string
            description: This is the same transactionId that is sent in the request
            example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
          supportMessage:
            type: string
            example: success
            description: Message will hold success for 200 response
      Error:
        type: object
        required:
        - "statusCode"
        - "statusMessage"
        - "transactionId"
        - "supportMessage"
        properties:
          statusCode:
            type: string
            description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned.
            example: '1000'
          statusMessage:
            type: string
            description: More details and corrective actions related to the error which can be shown to a client mapped to message from AYO Response 
          supportMessage:
            type: string
            description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful), mapped to description from the response of AYO
          transactionId:
            type: string
            description: This is the same transactionId that is sent in the request
            example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
          path:
            type: string
            description: The path that caused the error
            example: '/test/27831234567'
          method:
            type: string
            description: The HTTP method type that was used
            example: 'POST'
          type:
             type: string
             example: 'business error'
             description: type of error is shown for non 200 response and mapped from AYO response