MTN Retailer Productivity Tracking v1

swagger: "2.0"
info:
  version: "v1.0"
  title: MTN Retailer Productivity Tracking API
  description: An API to enable MTN retailers track their productivity KPI's over a period of time. Please refer to the reference guides https://developers.mtn.com/API-Reference-Guides and Response and Error Codes documents https://developers.mtn.com/ResponseCodes
schemes:
  - https
host: "api.mtn.com"
basePath: "/v1"
consumes:
  - "application/json"
produces:
  - "application/json"
securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    name: "X-API-Key"
    in: "header"
paths:
  /analytics/rpt/{id}/productivity:
    get:
      summary: "Retrieve details of retailer's productivity over a period of time"
      description: "Returns a list of productivity metrics. The report type query parameter must be provided when making a request"
      tags:
        - "Productivity Report"
      parameters:
        - name: "id"
          in: "path"
          description: "A unique identifier used to identify a customer it could be msisdn, userid or kitTag"
          required: true
          type: "string"
        - in: "query"
          name: "reportType"
          required: true
          description: "A required query parameter used to determine the The report Type to be returned e.g sim-swap"
          type: string
          enum:
            - "four-g-upgrade"
            - "sim-swap"
            - "d2r-transactions"
            - "data-vend"
            - "mfs-transactions"
            - "vtu-transactions"
            - "gross-connection"
            - "sim-registration"
            - "momo-registration"
        - name: "startDate"
          in: "query"
          description: "An optional parameter, together with endDate, allows developers to specify a time range by which to query customer data on.
          If you want to request data for 2 months, then start date will need to be set to 2 months prior to today, and endDate to todays date.
          If this is not set, the date range will be defaulted to 6 months date format is YYYY-MM-DD e.g 2019-06-24"
          type: string
          format: date
        - name: "endDate"
          in: query
          description: "An optional parameter, together with endDate, allows developers to specify a time range by which to query customer data on.
          If you want to request data for 2 months, then start date will need to be set to 2 months prior to today, and endDate to todays date.
          If this is not set, the date range will be defaulted to 6 months date format is YYYY-MM-DD e.g 2019-06-24"
          type: string
          format: date
      responses:
        200:
          description: "Success"
          schema:
            $ref: "#/definitions/reportWrapper"
        400:
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        401:
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        403:
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        405:
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

definitions:
  reportWrapper:
    type: "object"
    required:
      - "_link"
    properties:
      data:
        type: "object"
        required:
          - "report"
        properties:
          report:
            type: "array"
            items:
              $ref: "#/definitions/metric"
      _link:
        type: "object"
        $ref: "#/definitions/hateoasLinks"
  metric:
    type: "object"
    properties:
      metric:
        type: "string"
        description: "The name of the report metric"
        example: "total4GMigration"
      metricValue:
        type: "object"
        description: "Report metric values"
        example: 5
        $ref: "#/definitions/metricValue"
  metricValue:
    required:
      - "type"
    type: "object"
    description: "Values for any given metric"
    properties:
      type:
        type: "string"
        description: "The type of the metric value"
        example: "amount"
        enum:
          - "amount"
          - "count"
      value:
        type: "number"
        description: "The metric value could be double or integer"
        example: 4
  hateoasLinks:
    type: "object"
    required:
      - "self"
    properties:
      self:
        type: "object"
        required:
          - "href"
        description: ""
        properties:
          href:
            type: "string"
            description: "The HAETOS link referring to this object"
            example: "https://api.mtn.com/v1/analytics/sra_mohabd/productivity"
  Error:
    properties:
      timestamp:
        type: "string"
        format: "date-time"
        description: "Error response code"
        example: "2020-04-02T07:29:25.593+0000”"
      status:
        type: "string"
        description: "HTTP Status code"
        example: "404"
      error:
        type: "string"
        description: "HTTP Status description"
        example: "Not Found"
      message:
        type: "string"
        description: "More error details and corrective measures"
        example: "No message available"
      path:
        type: "string"
        description: ""