swagger: '2.0'
info:
  title: Usage Consumption API
  description: 'API to fetch Airtime, Currency, Voice, Data and SMS  balance details for a subscriber.'
  version: '1.0'
host: api.mtn.com
basePath: /usageConsumption/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:
  - OAuth2: []
  - ApiKeyAuth: []
tags:
  - name: usageConsumptionReport

paths:
  /usageConsumptionSummary/{id}:
    get:
      operationId: retrieveUsageConsumptionSummary
      summary: Retrieves a usage consumption summary of a subscriber
      description: >-
        This operation is used to retrieve usage consumption summary/report of a subscriber.
      tags:
        - usageConsumptionReport
      parameters:
        - name: "transactionId"
          in: header
          required: true
          description: 'Client generated Id to include for tracing requests.'
          type: string
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: "countryCode"
          type: string
          in: header
          required: false
          description: Will be used internally by application
        - name: "id"
          required: true
          type: string
          in: path
          description: "Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456"
          x-example: '250788123456'
        - name: "usageType"
          required: false
          type: string
          in: query
          description: "Type of usage concerned by the bucket, such as voice, sms, data"
          enum:
            - All
            - mainBalance
            - currencyBalance
            - Voice
            - Data
            - SMS
        - name: "senderID"
          required: false
          type: string
          in: query
          description: "Identifies the source system which integrates with MAD API"

        - name: "queryMode"
          required: false
          type: string
          in: query
          description: "Query mode for which the request is to be returned, pass 0 or this will be assisgned a default value(0)"
        - name: "x-origin-channel-id"  
          required: false
          type: string
          in: header
          description: "The channel consuming the API e.g. chatbot"

      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ResponseUsageConsumptionSummary'
        '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'
  /usageConsumptionDetailedReport/{id}:
    get:
      operationId: retrieveUsageConsumptionDetailedReport
      summary: Retrieves a usage consumption Detailed Report of a subscriber
      description: >-
        This operation is used to retrieve usage consumption Detailed report of a subscriber.
      tags:
        - usageConsumptionReport
      parameters:
        - name: "transactionId"
          in: header
          required: true
          description: 'Client generated Id to include for tracing requests.'
          type: string
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: "countryCode"
          type: string
          in: header
          required: false
          description: Will be used internally by application
        - name: "id"
          required: true
          type: string
          in: path
          description: "Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456"
          x-example: '250788123456'
        - name: "usageType"
          required: true
          type: string
          in: query
          description: "Type of usage concerned by the bucket, such as voice, sms, data"
          enum:
            - All
            - mainBalance
            - currencyBalance
            - Voice
            - Data
            - SMS
        - name: "senderID"
          required: false
          type: string
          in: query
          description: "Identifies the source system which integrates with MAD API"

      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ResponseUsageConsumptionDetailedReport'
        '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:
  ResponseUsageConsumptionSummary:
    type: "object"
    required:
      - resultCode
      - resultDescription
      - transactionId
      - data
    properties:
      resultCode:
        example: "0000"
        type: string
        description: Result code. Example- '0000'
      resultDescription:
        example: "Success"
        type: string
        description: Result message. Example- 'Successfully processed'
      transactionId:
        example: "6f0bece6-7df3-4da4-af02-5e7f16e5e6fc"
        type: string
        description: Transaction id returned by the provider system.
      data:
        type: array
        items:
          $ref: '#/definitions/UsageConsumptionSummary'
  ResponseUsageConsumptionDetailedReport:
    type: "object"
    required:
      - resultCode
      - resultDescription
      - transactionId
      - data
    properties:
      resultCode:
        example: "0000"
        type: string
        description: Result code. Example- '0000'
      resultDescription:
        example: "Success"
        type: string
        description: Result message. Example- 'Successfully processed'
      transactionId:
        example: "6f0bece6-7df3-4da4-af02-5e7f16e5e6fc"
        type: string
        description: Transaction id returned by the provider system.
      data:
        type: array
        items:
          $ref: '#/definitions/UsageConsumptionDetailedReport'
  UsageConsumptionSummary:
    type: object
    description: >-
      An usage consumption report enables to know at a given point the balances
      and the consumption counters related to various buckets (SMS, Voice, Data
      for example).
    properties:
      id:
        type: string
        description: "Unique identifier"
      type:
        type: string
        description: "Type of unique identifier."
      description:
        type: string
        description: "Description of the entity"
      name:
        type: string
        description: "Name of the entity."
      subscriberType:
        type: string
        description: 'Type of subscriber such as Prepaid, Postpaid, Hybrid etc.'
        enum:
          - Prepaid
          - Postpaid
          - Hybrid
      usageType:
        type: string
        description: 'Type of usage concerned by the bucket, such as voice, sms, data'
      bucket:
        type: array
        items:
          $ref: '#/definitions/UsageVolumeProduct'
        description: Bucket(s) included in the offer or option subscribed.
  UsageConsumptionDetailedReport:
    type: object
    description: >-
      An usage consumption report enables to know at a given point the balances
      and the consumption counters related to various buckets (SMS, Voice, Data
      for example).
    properties:
      id:
        type: string
        description: "Unique identifier"
      type:
        type: string
        description: "Type of unique identifier."
      description:
        type: string
        description: "Description of the entity"
      name:
        type: string
        description: "Name of the entity."
      subscriberType:
        type: string
        description: 'Type of subscriber such as Prepaid, Postpaid, Hybrid etc.'
        enum:
          - Prepaid
          - Postpaid
          - Hybrid
      usageType:
        type: string
        description: 'Type of usage concerned by the bucket, such as voice, sms, data'
      bucket:
        type: array
        items:
          $ref: '#/definitions/Bucket'
        description: Bucket(s) included in the offer or option subscribed.
  Bucket:
    type: object
    description: >-
      An usage consumption report enables to know at a given point the balances
      and the consumption counters related to various buckets (SMS, Voice, Data
      for example).
    properties:
      id:
        type: string
        description: "Unique identifier"
      type:
        type: string
        description: "Type of unique identifier."
      description:
        type: string
        description: "Description of the entity"
      name:
        type: string
        description: "Name of the entity."
      remainingAmount:
        $ref: '#/definitions/Quantity'
        description: "Remaining balance of the entity"
      activationDate:
        type: string
        format: date
        description: "Activation date of the entity"
      expiryDate:
        type: string
        format: date
        description: "Expiry date of the entity"
      bundleDetails:
        type: array
        items:
          $ref: '#/definitions/EntityRef'
        description: Bundle(s) included in the bucket or option subscribed.
      offerDetails:
        type: array
        items:
          $ref: '#/definitions/EntityRef'
        description: Offer(s) included in the bundle or option subscribed.
  EntityRef:
    type: object
    description: >-
      An usage consumption report enables to know at a given point the balances
      and the consumption counters related to various buckets (SMS, Voice, Data
      for example).
    properties:
      id:
        type: string
        description: "Unique identifier"
      type:
        type: string
        description: "Type of unique identifier."
      description:
        type: string
        description: "Description of the entity"
      name:
        type: string
        description: "Name of the entity."
      remainingAmount:
        $ref: '#/definitions/Quantity'
        description: "Remaining balance of a bucket"
      activationDate:
        type: string
        format: date
        description: "Activation date of the bucket"
      expiryDate:
        type: string
        format: date
        description: "Expiry date of the bucket"
      validity:
        type: string
        description: "Validity of the entity"
      recurring:
        type: boolean
        default: false
        description: "Nature of entity, i.e., one-time or recurring."
      recurringDate:
        type: string
        format: date
        description: "Recuuring date of the entity."
  UsageVolumeProduct:
    type: object
    description: >-
      A bucket (called UsageVolumeProduct in the SID model) represents a
      quantity of usage, as 2 hours national calls or 50 sms for example. It
      could be either a quantity or an amount in a currency (i.e. It could
      represent a fixed number of SMS, MMS, minutes of calls, quantity of data,
      number of events as well as a specific amount in a given currency). It
      requires one or more network products from which usages will debit the
      bucket.
    properties:
      id:
        type: string
        description: Unique identifier of the bucket
      name:
        type: string
        description: Bucket name
      description:
        type: string
        description: "Description of the relative entity."
      type:
        type: string
        description: "This is the type of relative entity."
      bucketBalance:
        type: array
        items:
          $ref: '#/definitions/UsageVolumeBalance'
  UsageVolumeBalance:
    type: object
    description: >-
      The balance (called UsageVolumeBalance in the SID model) defines the
      remaining allowed product usage quantity in terms of volume, time,
      currency or events. It corresponds to the initial allowed usage quantity
      minus the usage consumed on the bucket.
    properties:
      initialValue:
        $ref: '#/definitions/Quantity'
        description: >-
          Numeric initial value for the bucket given in the unit (for example
          1.9). This numeric value could be used for calculation for example
      usedValue:
        $ref: '#/definitions/Quantity'
        description: >-
          Numeric used value for the bucket given in the unit (for example
          1.9). This numeric value could be used for calculation for example
      remainingValue:
        $ref: '#/definitions/Quantity'
        description: >-
          Numeric remaining value for the bucket given in the unit (for example
          1.9). This numeric value could be used for calculation for example
      validFor:
        $ref: '#/definitions/TimePeriod'
        description: >-
          Balance period between a start date time and an end date time. For
          prepaid bucket, the period of the balance is between the  effective
          date of the usage consumption report generation and the end date of
          the bucket. For postpaid bucket, the period of the balance is between
          the effective date of the usage consumption report generation and the
          next bill date.
      currencyId:
        type: string
        description:  Currency ID
        example: "1185"
      currencyName:
        type: string
        description: "Name of the currency"
        example: "SSD"
  Quantity:
    type: object
    description: An amount in a given unit
    properties:
      amount:
        default: 1
        type: number
        format: float
        description: Numeric value in a given unit
      units:
        type: string
        description: Unit
  TimePeriod:
    type: object
    description: >-
      A period of time, either as a deadline (endDateTime only) a startDateTime
      only, or both
    properties:
      endDateTime:
        type: string
        format: date-time
        description: 'End of the time period, using IETC-RFC-3339 format'
      startDateTime:
        type: string
        format: date-time
        description: >-
          Start of the time period, using IETC-RFC-3339 format. If you define a
          start, you must also define an end
  Error:
    type: "object"
    title: "Error"
    required:
      - "status"
      - "message"
    properties:
      timestamp:
        type: "string"
        format: "date-time"
        description: "Time stamp of the error"
      status:
        type: "string"
        description: "Status/Error code returned from the provider system"
      error:
        type: "string"
        description: "Status/Error description"
      message:
        type: "string"
        description: "More error details and corrective measures"
      path:
        type: "string"
        description: "the path that caused the error"