MTN Customer Promotion

swagger: '2.0'
info:
  title: Customer Promotion Placeholder
  description: API Documentation
  version: '0.1'
host: za.api.mtn.com
basePath: /customerPromotion/v1
schemes:
  - https
consumes:
  - application/json;charset=utf-8
produces:
  - application/json;charset=utf-8
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:
  /tbd/promo:
    get:
      summary: some function here
      description: promotion description
      tags:
        - Customer Promotion
      responses:
        '200':
          description: Success
  /eligibilityCheck/{msisdn}:
    get:
      tags:
        - Customer Promotion
      summary: ELigibility check of customer.
      description: ELigibility check for recharge and Win campaign. This API is used to retreive customer profile.
      operationId: getUserProfile
      parameters:
        - name: transactionId
          in: header
          description: Unique ID for the transaction.
          required: true
          type: string
        - name: sourceIdentifier
          in: query
          description: This field denotes the channel that is initiating request to SOA like USSD, MyMTNApp
          required: true
          type: string
        - name: msisdn
          in: path
          description: MSISDN of the customer whose eligibility check needs to be done
          required: true
          type: string
      responses:
        '200':
          description: Eligibility check success Response
          schema:
            $ref: '#/definitions/eligibilityCheckResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorised
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '415':
          description: Unsupported Media Type
          schema:
            $ref: '#/definitions/Error415'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error500'
  /optin:
    post:
      summary: This API is used to optin users on campaigns
      tags:
      - Customer Promotion  
      parameters:
        - name: transactionId
          in: header
          description: Unique ID for the transaction.
          required: true
          type: string
        - name: sourceIdentifier
          in: query
          description: This field denotes the channel that is initiating request to SOA like USSD, MyMTNApp
          required: false
          type: string
        - name: OptIn
          description: Request parameters for customer Opt-In
          required: true
          schema:
              $ref: '#/definitions/optinRequest'
          in: body
      responses:
        '200':         
          description: Success response for optin
          schema:
            $ref: '#/definitions/optinResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '404':
          description: Not Found
          schema:
                $ref: '#/definitions/Error404'
        '415':
          description: Unsupported Media Type
          schema:
                $ref: '#/definitions/Error415'
        '500':
          description: Internal Server Error
          schema:
                $ref: '#/definitions/Error500'
            
definitions:
  eligibilityCheckResponse:
    type: object
    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. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes',
        example: '0000'
        maxLength: 30
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client. Success for 200.
      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)
      transactionId:
        type: string
        description: Unique reference number
        example: "100000172429605"
      balances:
        type: array
        items:
          $ref: "#/definitions/balanceType"
        description: >-
          'The amount of plays the user has available per game type. Balances expire daily at 12AM (midnight)
          The balance is redeemed by using the play endpoint to win a prize. Plays are not transferable between MSISDNs or game types'  
      wallet: 
        type: array
        items:
          $ref: "#/definitions/category1"
        description: |
          The user's rewards wallet that contains a collection of awarded prizes/gifts by category (redeemed and non-redeemed).
          These rewards may come from various sources, e.g. playing one of the games, gift campaigns or prizes won in the live draw 
          Rewards are not transferable between MSISDNs.
          Ordered by awardedAt in descending order.   
      draws:
        type: array
        items:
          $ref: "#/definitions/Draw"
        description: |
          A breakdown of draws, past and present that shows the number of entries a customer has aquired per draw.
          If the user has won a prize in one of the respective draws, the details pertaining to the prize awarded are included 
          A maximum of three draws will be shown, ordered by entriesOpenAt in descending order.
      history:
        $ref: "#/definitions/History"
      rechargeOptions: 
        $ref: "#/definitions/RechargeOptions"
      recharges:
        type: array
        items:
          $ref: "#/definitions/Recharges"
        description: |
          A breakdown of draws, past and present that shows the number of entries a customer has aquired per draw.
          If the user has won a prize in one of the respective draws, the details pertaining to the prize awarded are included
          A maximum of three draws will be shown, ordered by entriesOpenAt in descending order.
  optinRequest:
      allOf:
        - required:
          - msisdn
          properties:
            optin:
              type: boolean
              description: this is true or false for user optin. 
              example: true 
            campaign:
              type: string
              description: Identifies the campaign you would like to optin or optout to.
              example: 'RECHARGE_AND_WIN'
            msisdn:
              description: MSISDN of the customer who wants to redeem their reward. This will be cross-checked against the play id as pre provision safety measure
              type: string
              example: 27605220405
  optinResponse:
      allOf:
        - 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. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
              example: '0000'
              maxLength: 30
            statusMessage:
              type: string
              description: More details and corrective actions related to the error which can be shown to a client. Success for 200.
            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)
            transactionId:
              type: string
              description: Unique reference number
              example: "100000172429605"

  balanceType:
        required:
          - type
          - balance
        properties:
          type:
            type: string
            enum: ['DAILY', 'LOYALTY_SPEND_1', 'LOYALTY_SPEND_2', 'LOYALTY_SPEND_3', 'LIVE_DRAW']
            description: >-
              Type of the balance that the customer is having in their profile
          balance:
            type: integer
            description: >-
              The amount of plays available
        description: >
          status:
           * `DAILY` - Daily plays awarded
           * `LOYALTY_SPEND_1` - plays awarded for loyalty points redeptions of less than 50 points
           * `LOYALTY_SPEND_2` - plays awarded for loyalty points redeptions of less than 250 points
           * `LOYALTY_SPEND_3` - plays awarded for loyalty points redeptions of more than 250 points
           * `LIVE_DRAW` - Plays awarded for visiting the draw announcement page during the live announcement window
  category1:
      $ref: "#/definitions/reward1"
  Draw:
      required:
        - entries
        - drawStatus
        - entriesOpenAt
        - entriesCloseAt
        - announcementStartAt
        - announcementEndAt
      properties:
        entries:
          type: integer
          format: int32
          description : |
            The number of entries that have been awarded to the customer in question (Only applicalbe to draws shown in customer profile)
        winner:
          type: boolean
          description : |
            Whether the customer in question has won a pize in the draw (Only applicalbe to draws shown in customer profile)
        drawStatus:
          type: string
          enum: ['OPEN', 'CLOSED', 'LIVE']
        entriesOpenAt:
          type: string
          format: date-time
          description : This field defines the time when the draws open for entries
        entriesCloseAt:
          type: string
          format: date-time
          description : When the draw no longer accepts entries
        announcementStartAt:
          type: string
          format: date-time
          description : When the live draw starts
        announcementEndAt:
          type: string
          format: date-time
          description : When the live draw ends
        prizes:
          type: array
          description : |
            A list of prizes that pertain to the draw
            
            Draws shown in customer profile will only show prizes that pertain to the customer in question
          items:
            required:
            - msisdn
            - reward
            properties:
              msisdn:
                type: string
                description : The msisdn of the winner of the prize. The value will be in international format i.e., 27867583465 [MQ] - Is the msisdn of the customer querying the service or the prize winner? [SOA] This is the winner
              reward:
                $ref: "#/definitions/reward"
      description: >
        drawStatus:
         * `OPEN` - The draw is accepting entries
         * `CLOSED` - The draw is no longer accepting entries
         * `LIVE` - The draw winners are being announced     
  History:
      required:
        - anniversary
        - lastRecharges
        - firstRecharge
        - log
      properties:
        anniversary:
          type: string
          format: date-time
        lastRecharges:
          type: string
          format: date-time
        firstRecharge:
          type: string
          format: date-time
        log : 
          type: array
          items:
            $ref: "#/definitions/LogHistory" 
  Recharges:
      required:
        - SOID
        - price
        - location
        - date
      properties:
        SOID:
          type: string
          example: '1234'
        price:
          type: string
          example: '49'
        location:
          type: string
          example: "Randburg"
        date:
          type: string
          format: date-time  
  RechargeOptions:
      required:
        - optin
        - nextRechargeBefore
      properties:
        optin:
          type: boolean
          example: true 
        nextRechargeBefore:
          format: date-time
  reward1:

      properties:
        redeemId:
          type: string
          example: "922625"
          description: The redeem id of the reward
        pool:
          type: string
          example: "UNCONDITIONAL_GIFT"
          description: The pool of the reward
        category:
          type: string
          example: "Grocery"
          description: The category of the reward
        subCategory:
          type: string
          example: "Checkers"
          description: The subcategory of the reward
        shortDescription:
          type: string
          example: ""
          description: The short description of the reward
        description:
          type: string
          example: "R5000 CHECKERS VOUCHER"
          description: The description of the reward
        properties:
          type: object
          properties:
            type:
              type: string
              example: "VOUCHERCHECKERS"
              description: The type of the reward
            value:
              type: integer
              example: 5000
              description: The value of the reward
            valueUnit:
              type: string
              example: "R"
              description: The unit of the reward value
            validity:
              type: integer
              example: 60
              description: The validity of the reward
            validityUnit:
              type: string
              example: "Days"
              description: The unit of the reward validity
            valueCents:
              type: integer
              example: 0
              description: The cost of redeeming the reward in cents
            valueFormatted:
              type: string
              example: "R0"
              description: The formatted cost of redeeming the reward
            discount:
              type: string
              example: "100%"
              description: The discount applied to the reward
        awardedAt:
          type: string
          format: date-time
          example: "2023-11-07T07:00:23.559Z"
          description: The time when the reward was awarded
        redeemed:
          type: boolean
          example: false
          description: Whether the reward has been redeemed or not
        redeemedAt:
          type: string
          format: date-time
          example: ""
          description: The time when the reward was redeemed
        expired:
          type: boolean
          example: true
          description: Whether the reward has expired or not
        expiresAt:
          type: string
          format: date-time
          example: "2023-11-07T07:00:40.339Z"
          description: The time when the reward expires
        source:
          type: string
          example: "GIFT"
          description: The source of the reward
      description: >
        source:
         * `DAILY` - A prize won when playing the game using daily plays
         * `LOYALTY_SPEND_1` - A prize won when playing the game using low value loyalty spend plays
         * `LOYALTY_SPEND_2` - A prize won when playing the game using medium value loyalty spend plays
         * `LOYALTY_SPEND_3` - A prize won when playing the game using high value loyalty spend plays
         * `LIVE_DRAW` - A prize won when playing the game made available during the announcement window
         * `GIFT` - A reward gifted to the user via the gigting endpoint
         * `DRAW` - A prize in the weekly/monthly draw     
  reward:
      properties:
        redeemId:
          type: string
          example: "922625"
          description: The redeem id of the reward
        pool:
          type: string
          example: "UNCONDITIONAL_GIFT"
          description: The pool of the reward
        category:
          type: string
          example: "Grocery"
          description: The category of the reward
        subCategory:
          type: string
          example: "Checkers"
          description: The subcategory of the reward
        shortDescription:
          type: string
          example: ""
          description: The short description of the reward
        description:
          type: string
          example: "R5000 CHECKERS VOUCHER"
          description: The description of the reward
        properties:
          type: object
          properties:
            type:
              type: string
              example: "VOUCHERCHECKERS"
              description: The type of the reward
            value:
              type: integer
              example: 5000
              description: The value of the reward
            valueUnit:
              type: string
              example: "R"
              description: The unit of the reward value
            validity:
              type: integer
              example: 60
              description: The validity of the reward
            validityUnit:
              type: string
              example: "Days"
              description: The unit of the reward validity
            valueCents:
              type: integer
              example: 0
              description: The cost of redeeming the reward in cents
            valueFormatted:
              type: string
              example: "R0"
              description: The formatted cost of redeeming the reward
            discount:
              type: string
              example: "100%"
              description: The discount applied to the reward
        awardedAt:
          type: string
          format: date-time
          example: "2023-11-07T07:00:23.559Z"
          description: The time when the reward was awarded
        redeemed:
          type: boolean
          example: false
          description: Whether the reward has been redeemed or not
        redeemedAt:
          type: string
          format: date-time
          example: ""
          description: The time when the reward was redeemed
        expired:
          type: boolean
          example: true
          description: Whether the reward has expired or not
        expiresAt:
          type: string
          format: date-time
          example: "2023-11-07T07:00:40.339Z"
          description: The time when the reward expires
        source:
          type: string
          example: "GIFT"
          description: The source of the reward
      description: >
        source:
         * `DAILY` - A prize won when playing the game using daily plays
         * `LOYALTY_SPEND_1` - A prize won when playing the game using low value loyalty spend plays
         * `LOYALTY_SPEND_2` - A prize won when playing the game using medium value loyalty spend plays
         * `LOYALTY_SPEND_3` - A prize won when playing the game using high value loyalty spend plays
         * `LIVE_DRAW` - A prize won when playing the game made available during the announcement window
         * `GIFT` - A reward gifted to the user via the gigting endpoint
         * `DRAW` - A prize in the weekly/monthly draw
  LogHistory:
      properties:
        recharge:
          type: string
          description : The time of recharge transaction
          format: date-time
        bundle:
          type: string
          example: 'BUY-1-500MB-1D-R500'
        value:
          type: integer
          format: int32
          description : The value will be returned cents from Infinity and will be convered to Rand
          example: 500 
        valueUom:
          type: string
          format: Rand
          description : The unit of measure of the value
          example: Rand

  Error400:
    properties:
      statusCode:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 5000
      statusMessage:
          type: "string"
          description: Status message from target system to indicate transaction status.
      supportMessage:
          type: "string"
          description: detail message from target system to indicate transaction status.
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
        example: "0d1e1b18-1b6d-4792-8417-72d337f42a1c"
  Error401:
    properties:
      statusCode:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 4000
      statusMessage:
          type: "string"
          description: Status message from target system to indicate transaction status.
          example: Unauthorised
      supportMessage:
          type: "string"
          description: detail message from target system to indicate transaction status.
          example: Please verify token environment and key
      faultMessage1:
        type: "string"
        description: ""
      faultMessage2:
          type: "string"
          description: fault message
  Error404:
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      status:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 404
      error:
          type: "string"
          description: error message
          example: Not found
      message:
        type: string
        description: details
      path:
        type: string
        description: The path that caused the error
  Error405:
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      status:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 405
      error:
          type: "string"
          description: error message
          example: Method Not Allowed
      message:
        type: string
        description: details
      path:
        type: string
        description: The path that caused the error
  Error415:
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      status:
          type: "integer"
          description: Status code from target system to indicate transaction status
          example: 415
      error:
          type: "string"
          description: error message
          example: Unsupported Media Type
      message:
        type: string
        description: details
      path:
        type: string
        description: The path that caused the error
  Error500:
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      status:
        type: string
        description: status code from backend
        example: '500'
      error:
        type: string
        description: Type of error
        example: "Internal Server Error"
      message:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
        example: 'Internal Server Error'
      path:
        type: string
        description: The path that caused the error