swagger: "2.0"
info:
  version: "v1.0"
  title: MTN Agent Profile API
  description: |-
    An API to retrieve the profile of an MTN field agent. Please refer to the reference guides https://developers.mtn.com/getting-started and Response and Error Codes documents https://developers.mtn.com/getting-started/response-and-error-codes
schemes:
  - https
host: "api.mtn.com"
basePath: "/v1/agents"
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:
    /{agentId}:
      get:
        description: "Retrieves the profile of a MTN field agent."
        summary: "View agent profile"
        tags:
          - "agents"
        parameters:
        - in: "path"
          name: "agentId"
          description: "ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123"
          required: true
          type: "string"
        - name: fields
          in: query
          type: string
          description: Filter for parts of the agent profile to be returned. Use comma-separated values
          x-example: agentKyc,agentPlans,activityReport
        - name: X-Authorization
          in: header
          type: string
          description: >-
            SSO Bearer token received from OAuth2.0 authentication with the
            backend system
          x-example: eyJhbGciOiJ.IUzI1NiIsIn.R5cCI6IkpXVCJ9
        responses:
          200:
            description: "Agent Profile object. For a successful request, it will contain all the agent's details. If the agent does not have any requested data, then it will be null."
            schema:
              $ref: "#/definitions/Agent"

          207:
            description: "If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty"
            examples:
              Multi-Status Response, showing valid Locations data, but plan object is null: >
                  "location": {
                    "data": {
                      "country": "ZA",
                      "operator": "MTN"
                    },
                    "_links": {
                      "self": {
                        "href": "http://api.mtn.com/agents/27832000046/locations"
                      }
                    }
                  }
                  "plan": {
                    "data": null,
                     "_links": {
                      "self": {
                          "href": "http://api.mtn.com/agents/27832000046/plans"
                        }
                      }
                  }

          400:
            description: "Bad Request"
            schema:
              $ref: "#/definitions/ErrorDefault"
          401:
            description: "Unauthorized"
            schema:
              $ref: "#/definitions/ErrorDefault"
          403:
            description: "Forbidden"
            schema:
              $ref: "#/definitions/ErrorDefault"
          404:
            description: "Agent not found"
            examples:
              The data object/envelope will be null: >
                {
                  "data": null
                }
          405:
            description: "Method Not allowed"
            schema:
              $ref: "#/definitions/Error"
          500:
            description: "Internal Server Error"
            schema:
              $ref: "#/definitions/Error"
    /{customerId}/agentFlag:
      get:
        summary: "To know if any given customer Id (MSISDN) is registered as an MTN field Agent or not"
        description: "To know if any given customer Id (MSISDN) is registered as an MTN field Agent or not"
        tags:
          - "agents"
        parameters:
        - in: "path"
          name: "customerId"
          description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123"
          required: true
          type: "string"
        - name: X-Authorization
          in: header
          type: string
          description: >-
            SSO Bearer token received from OAuth2.0 authentication with the
            backend system
          x-example: eyJhbGciOiJ.IUzI1NiIsIn.R5cCI6IkpXVCJ9
        responses:
          200:
            description: OK
            schema:
              $ref: "#/definitions/agentFLAG"

          400:
            description: "Bad Request"
            schema:
              $ref: "#/definitions/Error"
          401:
            description: "Unauthorized"
            schema:
              $ref: "#/definitions/ErrorDefault"
          403:
            description: "Forbidden"
            schema:
              $ref: "#/definitions/ErrorDefault"
          404:
            description: "Agent not found"
            examples:
              The data object/envelope will be null: >
                {
                  "data": null
                }
          405:
            description: "Method Not allowed"
            schema:
              $ref: "#/definitions/Error"
          500:
            description: "Internal Server Error"
            schema:
              $ref: "#/definitions/Error"

    /{agentId}/devices:
      patch:
        summary: "Update device information of a registered MTN Agent"
        description: "Update device information of a registered MTN Agent. E.g. Updating the IMEI the Agent's assigned Point-of-Sale device"
        tags:
          - "agents"
        parameters:
        - in: "path"
          name: "agentId"
          description: "ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123"
          required: true
          type: "string"
        - name: transactionId
          in: header
          description: Client generated request Id.
          type: string
        - name: X-Authorization
          in: header
          type: string
          description: >-
            SSO Bearer token received from OAuth2.0 authentication with the
            backend system
          x-example: eyJhbGciOiJ.IUzI1NiIsIn.R5cCI6IkpXVCJ9
        - name: deviceInfo
          in: body
          description: Device Information
          schema:
            allOf:
              - $ref: '#/definitions/Devices'
              - type: object
                properties:
                  geoTag:
                    $ref: '#/definitions/geoTagging'

        responses:
          201:
            description: Created
            schema:
              allOf:
                - type: object
                  properties:
                    statusCode:
                      type: string
                      description: Response status code. 0000 for success
                    transactionId:
                      type: string
                      description: Response transaction Id from the backend
                - $ref: "#/definitions/Devices"
                - type: object
                  properties:
                    geoTag:
                      $ref: '#/definitions/geoTagging'
                - type: object
                  properties:
                    _links:
                      $ref: "#/definitions/AgentLinks"

          400:
            description: "Bad Request"
            schema:
              $ref: "#/definitions/Error"
          401:
            description: "Unauthorized"
            schema:
              $ref: "#/definitions/Error"
          403:
            description: "Forbidden"
            schema:
              $ref: "#/definitions/Error"
          404:
            description: "Agent not found"
            examples:
              The data object/envelope will be null: >
                {
                  "data": null
                }
          405:
            description: "Method Not allowed"
            schema:
              $ref: "#/definitions/Error"
          500:
            description: "Internal Server Error"
            schema:
              $ref: "#/definitions/Error"

    /{agentId}/tracking/:
      post:
        operationId: addAppInstallationConfirmationDetails
        summary: submit app installation confirmation details to the API.
        description: >-
          This endpoint is used to submit app installation confirmation details to the API.
        tags:
          - agents
        parameters:
          - in: "path"
            name: "agentId"
            description: "ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123"
            required: true
            type: "string"
          - name: "installationConfirmationDetails"
            in: body
            required: true
            description: "Client generated Id to include for tracing requests."
            schema:
              $ref: "#/definitions/installationConfirmationDetailsRequest"
        responses:
          "200":
            description: Success
            schema:
              $ref: "#/definitions/installationConfirmationDetailsResponse"
          "400":
            description: Bad Request
            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"
          "405":
            description: Method Not allowed
            schema:
              $ref: "#/definitions/Error"
          "409":
            description: Conflict
            schema:
              $ref: "#/definitions/Error"
          "500":
            description: Internal Server Error
            schema:
              $ref: "#/definitions/Error"
definitions:
  Agent:
    type: object
    properties:
      statusCode:
        type: string
        description: Canonical response code. '0000' for success response
        example: '0000'
      agentId:
        type: string
        example: '2568810000034'
      agentKyc:
        type: array
        items:
          $ref: "#/definitions/AGENTKYC"
      agentPlans:
        type: object
        $ref: "#/definitions/AGENTPLANS"
      activityReport:
        type: object
        $ref: "#/definitions/ACTIVITYREPORT"
      _link:
        type: "object"
        allOf:
          - description: "The link to retrieve the Agent KYC details."
          - $ref: "#/definitions/AgentLinks"

  AgentLinks:
    type: "object"
    required:
    - "self"
    properties:
      self:
        type: "object"
        required:
        - "href"
        description: ""
        properties:
          href:
            type: "string"
            description: ""
            example: 'https://api.mtn.com/v1/agents/256779999781'

  AGENTKYC:
    type: object
    properties:
      data:
        type: object
        properties:
          agentId:
            type: string
            description: Unique identifier for the Agent
            example: DEALER789
          role:
            type: string
            description: Role of the Agent in the agent's hierarchy
            enum:
              - Agent
              - MasterDealer
              - HandlerDealer
          type:
            type: string
            description: Type of the agent
            example: RICA
          status:
            type: string
            description: Current status of the agent
            enum:
             - Active
             - Suspended
             - Blocked
          imei:
            type: string
            description: IMEI of the handset that is assigned to the Agent
            example: 123456789876543
          registrationDate:
            type: string
            format: date-time
            description: Date and time when the Agent was created. Should be in ISO 8601
          firstName:
            type: string
          middleName:
            type: string
          lastName:
            type: string

  AGENTPLANS:
    type: object
    properties:
      data:
        type: object
        properties:
          balance:
            type: array
            description: The account balance details of an agent
            items:
              properties:
                balanceType:
                  type: string
                  description: 'Identifies the type of balance. An agent plan may have multiple types of balances for different usage, for example, AgentCommission, voice, SMS, and game services.'
                  example: 'AgentCommission'
                category:
                  type: string
                  description: Identifies the category of the balance type.
                  example: 'AgentCommission'
                balanceDetail:
                  $ref: '#/definitions/BalanceDetail'
                wallets:
                  type: array
                  description: The different wallets used to compute the active and unused values of this balance.
                  items:
                    $ref: '#/definitions/Wallet'
  BalanceDetail:
    type: object
    required:
      - type
      - activeValue
      - activeUnit
    description: The details for a balance type.
    properties:
      type:
        type: string
        description: This is the type of the value.
        enum:
          - CURRENCY
          - DATA
          - MINUTES
          - SMS
      activeValue:
        type: string
        description: This is the aggregated formatted active value of a balance type.
        example: '136271'
      activeUnit:
        type: string
        description: This is the unit of the aggregated active value.
        enum:
          - UGX
          - ZAR
          - NGN
          - GB
          - MB
          - MINUTES
          - SMS
  Wallet:
    type: object
    required:
      - name
      - amount
    description: Contributing wallets to the aggregated balance
    properties:
      name:
        type: string
        description: The name of a wallet account. E.g. registrationCommission, simswapCommission
        example: registrationCommission
      amount:
        $ref: '#/definitions/Amount'

  Amount:
    type: object
    required:
      - value
      - type
      - unit
    description: The amount details for a wallet.
    properties:
      type:
        type: string
        description: This is the type of the wallet value.
        enum:
          - CURRENCY
          - DATA
          - MINUTES
          - SMS
      value:
        type: string
        description: This is the value of a balance wallet.
        example: 76923
      unit:
        type: string
        description: This is the unit of the wallet value.
        enum:
          - UGX
          - ZAR
          - NGN
          - GB
          - MB
          - MINUTES
          - SMS
          - FCFA

  Devices:
    type: object
    properties:
      data:
        type: object
        properties:
          devices:
            type: array
            items:
              properties:
                IMEI:
                  type: string
                  description: "Last known IMEI. Unique identifier of Mobile Device used by the MSISDN"
                  example: "990000862471854"
                timePeriods:
                  type: object
                  properties:
                    startDateTime:
                      type: string
                      format: date-time
                    endDateTime:
                      type: string
                      format: date-time
                      
  ACTIVITYREPORT:
    type: object
    properties:
      firstCallActivationCount:
        type: integer
        description: 'Number of new customers registered by the agent that have done their first voice call'
        example: 110
      firstRechargeActivationCount:
        type: integer
        description: 'Number of new customers registered by the agent that have done their first airtime recharge'
        example: 90    
        
  agentFLAG:
    type: object
    properties:
      statusCode:
        type: string
        example: '0000'
      message:
        type: string
        description: 'Response description from the backend system'
        example: 'Yello, Requestor should be an agent.'
      transactionId:
        type: string
        description: 'Response Id from the backend'
      agentId:
        type: string
        description: 'ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123'
        example: '256789999781'
      data:
        type: object
        properties:
          isAgent:
            type: boolean
            example: false
      _links:
        allOf:
          - description: Links used to access the agent information
          - $ref: "#/definitions/AgentLinks"

  geoTagging:
    type: object
    properties:
      regLocationLat:
        type: number
        format: double
        description: >-
          Latitude value of the place where the agent KYC capture has taken
          place
        example: 3.225225225225225
      regLocationLong:
        type: number
        format: double
        description: >-
          Longitude value of the place where the agent KYC capture has
          taken place
        example: 30.913829549623536
      cellGlobalId:
        type: string
        pattern: '^\d{3}-\d{2}-\d-\w$'
        description: Full Cell Global Identity in the format MCC-MNC-LAC-CellId
        example: 641-10-2321-6b1c
      kycCaptureDateTime:
        type: string
        format: date-time
        description: datetime when the agent KYC capture/update happened, using IETC-RFC-3339 format
  Error:
    properties:
      timestamp:
        type: "string"
        format: "date-time"
        description: "Error response code"
      status:
        type: "string"
        description: "Text explaining the reason for the error"
      error:
        type: "string"
      message:
        type: "string"
        description: "More error details and corrective measures"
      path:
        type: "string"
        description: ""

  ErrorDefault:
    properties:
      error:
        type: "string"
      error_description:
        type: "string"

  installationConfirmationDetailsRequest:
    type: "object"
    required:
      - appCode
      - installerCode
      - msisdn
      - imei
    properties:
      appCode:
        type: string
      msisdn:
        type: string
      imei:
        type: string
      phoneOSVersion:
        type: string
      imsi:
        type: string
      sourceChannel:
        type: string
      deviceLocation:
        type: string

  installationConfirmationDetailsResponse:
    type: "object"
    properties:
      statusCode:
        type: string
      statusMessage:
        type: string
      timestamp:
        type: "string"
        format: "date-time"
        description: "Error response code"