swagger: "2.0"
info:
  title: Device Swap API
  version: '0.1'
  description: |-
    The Device Swap API is designed to detect changes in the International Mobile Equipment Identity (IMEI) associated with a mobile subscriber's number (MSISDN) within a specific period, typically the last 30 days.  
    ## Supported Operations 
    1.Checks if the IMEI linked to an MSISDN has changed.
    2.Returns the date of the latest IMEI change.
    3.Helps detect suspicious behavior, such as device swaps preceding transactions or access attempts.
    4.It helps know how many times a device swap activity has occurred.
    5.Enables clients to query changes over a defined date range.
    

host: api.mtn.com
basePath: "/v1/devices"
schemes:
  - https
securityDefinitions: 
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/oauth/client/accesstoken?grant_type=client_credentials'
security:
  - OAuth2: []

consumes:
  - application/json
produces:
  - application/json


paths:
  '/deviceSwap':
    post:
      tags:
        - Device Swap API
      summary: Retrieve device swap details.
      description: >-
        The Device Swap API uses MSISDN to track changes in the IMEI linked to a subscriber's device
      parameters:
        - name: body
          in: body
          description: Request body
          required: true
          schema:
            $ref: '#/definitions/deviceSwapRequest'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/deviceSwapResponse'
          headers:
            transactionId:
              type: string
              description: "Client generated Id to include for tracing requests"
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error400'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error401'
        '403':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error403'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error404'
        '405':
          description: Method No Allowed
          schema:
            $ref: "#/definitions/Error405"
        '408':
          description: Time out
          schema:
            $ref: "#/definitions/Error408"
        '415':
          description: Not acceptable
          schema:
            $ref: "#/definitions/Error415"
        '500':
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error500"
        '503':
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error500"
            
    
definitions:

  deviceSwapResponse:
    required:
      - customerId
      - data
      - statusCode
      - statusMessage
    type: object
    properties:
      statusCode:
        type: string
        enum: ["0000","1022"]
        description: >
            HTTP error code extension:
             * `0000` - Success Response
        example: '0000'
      statusMessage:
        type: string
        description: Message.
        example: Successful
      customerId:
        type: string
        description: MSISDN of the customer provided in the input as customerId
        example: '234789999781'
      transactionId:
        type: string
        description: transaction ID From the backend provider system for tracing.
        example: 232TXYZ-212
      data:
        $ref: '#/definitions/deviceSwapData'
  
  deviceSwapData:
    type: object
    properties:
      date_changed:
        type: string
        description: >-
          The date of the most recent IMEI change, if applicable.
        example: '2020-04-20 15:22:11'
      swap_status:
       type: boolean
       description: Indicates whether a device swap occurred (true or false).
      count: 
       type: string
       description: The total number of times a device swap event was registered.
  
  deviceSwapRequest:
    type: object
    required:
     - MSISDN
    properties:
      MSISDN:
        type: string
        description:  The mobile number of the subscriber
      start_date:
        type: string
        format: date
        description : (DD-MM-YYYY) Start of the date range
      end_date:
        type: string
        format: date
        description : (DD-MM-YYYY) End of the date range  

  Error400:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: "5000"
        statusMessage:
          type: string
          description: "Invalid Parameters"
          example: "The input parameters provided are invalid"
        SupportMessage:
          type: string
          description: "Detailed error Message"
          example: "Unsupported input, please enter a valid 'msisdn' value"
          enum:
            - "Unsupported input, please enter a valid 'msisdn' value."
            - "Invalid country code"
        transactionId:
          type: string
          description: "Id for tracing."
          example: "fg545f-cf4gg4fd55-fdg85hg6"
          
  Error401:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: "4000"
        statusMessage:
          type: string
          description: "Short description of the error"
          example: "Unauthorised"
        supportMessage:
          type: string
          description: "Longer description of the error"
          example: "Please verify token environment or access token or API key"
        transactionId:
          type: string
          description: "Id for tracing."
          example: "fg545f-cf4gg4fd55-fdg85hg6"
  Error403:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: "6000"
        statusMessage:
          type: string
          description: "Short description of the error"
          example: "Forbidden"
        supportMessage:
          type: string
          description: "Longer description of the error"
          example: "Please verify token environment or access token or API key"
        transactionId:
          type: string
          description: "Id for tracing."
          example: "fg545f-cf4gg4fd55-fdg85hg6"
  Error404:
    type: object
    description: "phoneNumber not found"
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: "1000"
      statusMessage:
        type: string
        example: "phoneNumber not found."
      supportMessage:
        type: string
        example: "Queried phoneNumber could not be found"
      transactionId:
        type: string
        description: "Id for tracing."
        example: "fg545f-cf4gg4fd55-fdg85hg6"
  Error405:
    type: object
    description: "Method not Allowed"
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: "4001"
      statusMessage:
        type: string
        example: "Not Allowed"
      supportMessage:
        type: string
        example: "Method Not Allowed"
      transactionId:
        type: string
        description: "Id for tracing."
        example: "fg545f-cf4gg4fd55-fdg85hg6"
  Error408:
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: "3003"
      statusMessage:
        type: string
        description:  "The request timed out."
        example: "Timeout"
      supportMessage:
        type: string
        description: "The server took too long to respond."
        example: "Request timed out"
      transactionId:
        type: string
        description: "Id for tracing."
        example: "fg545f-cf4gg4fd55-fdg85hg6"
  Error415:
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: "5000"
      statusMessage:
        type: string
        description: "Short description of the error"
        example: "Unsupported Media Type"
      supportMessage:
        type: string
        description: "Longer description of the error"
        example: "Unsupported Media Type. It should be application/json"
      transactionId:
        type: string
        description: "Id for tracing."
        example: "fg545f-cf4gg4fd55-fdg85hg6"
  Error500:
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: "3001"
      statusMessage:
        type: string
        description: "Internal Server Error"
        example: "Internal Server Error"
      supportMessage:
        type: string
        description: "Error"
        example: "Internal Server Error"
      transactionId:
        type: string
        description: "Id for tracing."
        example: "fg545f-cf4gg4fd55-fdg85hg6"