---
openapi: 3.0.3
info:
  title: Business Analytics Report API
  version: 1.0.5
  description: |-
    #### Copyright
    © Aeris Communications, Inc. 2025. All rights reserved. No part of this document may be reproduced in any form without the written permission of the copyright owner.

    #### Disclaimer

    The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing.
    Aeris shall have no liability for any error or damage of any kind resulting from the use of this document.

    #### Trademark List

    All trademarks mentioned herein are the property of their respective owners.
    These are shown in the document Trademark Information.

    # Introduction

    This document describes the IoT Accelerator Business Analytics Report API that provides report and invoice resources
    to retrieve an organization's report and invoice information.
    The Business Analytics Report API is based on the Representational State Transfer (REST) interface.
    From this point on, the Business Analytics API is referred to as API in this document.

    ## Scope

    Business Analytics Report API provides operations to query the available reports, invoices and usage data. The API users can download desired report, invoice data files and usage data files according to the information in reports, invoices and usage data query response. This API also provides operation to delete invoice data files.

    <b>Currently supported operations:</b>

     * Query reports
     * Download report data file
     * Query invoices
     * Download invoice data file
     * Delete invoice data file
     * Query useage data
     * Download usage data file
     * Query the top subscriptions with most traffic usage

    ## Prerequisites
    In this document, it is assumed that the user is familiar with the following:

    — Java Script Object Notation (JSON)

    — Basic understanding of REST web services

    — The [OpenAPI Initiative](https://www.openapis.org/) for the standardized format used in this document.

    ## Related Information
    The definition and explanation of acronyms and terminology and typographic conventions can be found in the following documents:

    — IoTA Glossary of Terms and Acronyms

    — Typographic Conventions

    # General API Guidelines

    ## Compatibility

    API audience must be prepared for compatible API extensions:

    - Be tolerant with unknown fields in the payload (see also Fowler's "TolerantReader" post), i.e. ignore new fields but do not eliminate them from payload if needed for subsequent PUT requests.
    - Be prepared that "x-extensible-enum" return parameter may deliver new values. Either be agnostic or provide default behavior for unknown values.
    - Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions.
    - Follow the redirect when the server returns HTTP status 301 Moved Permanently.

    ## Security

    This section describes the security measures in the API. Security measures include authentication, authorization, and encryption.

    ### Authentication and Authorization

    The API uses OAuth2 and OpenID Connect (OIDC) for authentication and authorization.

    All API endpoints require authentication, which is performed by passing a token in the Authorization header in each request, preceded by the word Bearer and a space. See the following example:
    ```
    curl -i -X GET "https://<baseURL>/iot/api/business-analytics-service/v1/reports" -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN_GOES_HERE>"
    ```
    To fetch the token using e.g. curl, submit the following:
    ```
    curl -X POST "https://<baseURL>/iot/api/auth/token" -H "Accept: application/vnd.dcp-v1+json" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&client_id=<client_id>&username=<username>&password=<password>"
    ```
    ### Encryption

    All API requests are encrypted using the HTTPS protocol to grant secure data transfer.

    ### Permission
    API permissions are authorized by authorization server based on the account roles. Required permissions for this API are documented in 'securitySchemes' section.
    You can view available permissions for your account through permission library in Service Portal by navigating Administration > Users & roles > Permission library
    or Role administration > Actions > View permission library.

    Make sure permissions are available to your account before you start utilizing this API.

    Below shows the permissions related to the endpoints in this API:

     * Download monthly reports - for TCXN (old)
     * Download monthly reports - for TCXN
     * Download monthly reports - for operators (old)
     * Download monthly reports - for operators
     * Download monthly reports - for TCXN (old)
     * Download monthly reports - for enterprises
     * Download monthly reports (no billing-related reports) - for enterprises (old)
     * Download monthly reports (no billing-related reports) - for enterprises
     * Download invoices + invoice deletion - for supplier
     * Download invoices + invoice deletion - for operators (old)
     * Download invoices + invoice deletion
     * Download invoices - for enterprises (old)
     * Download invoices
     * Download usage data (old)
     * Download usage data
     * API: Subscriptions with most data traffic
     * API: Subscriptions with most SMS traffic

    
    ## Deprecation

    API deprecation will be reflected in the OpenAPI definition. If a method on a path, a whole path or even a whole API endpoint (multiple paths) should be deprecated, they will be marked as deprecated.
    During deprecation phase, a Deprecation header and a Sunset header fields will be added in the response.

    Example:
    ```
    Deprecation: Tue, 31 Dec 2024 23:59:59 GMT
    Sunset: Wed, 31 Dec 2025 23:59:59 GMT
    ```

    API audience should not start using a deprecated API.

    API audience is encouraged to monitor for Deprecation and Sunset header.

  x-audience: external-public
  x-api-id: b6389a2a-0d7f-4ba1-af93-27ad5e690095
servers:
  - url: https://iot-api.aeris.com/iot/api/business-analytics-service/v1
    description: API server

tags:
  - name: Reports
  - name: Invoices
  - name: Usages
  - name: Aggregated traffics

paths:
  '/reports':
    get:
      tags:
        - Reports
      summary: Query report data files
      description: >
        Returns a list of report data files that can be downloaded.
      operationId: QueryReports
      parameters:
        - name: fromDate
          in: query
          description: >
            Specifies the earliest date from which reports are requested. The input of fromData is set according to RFC 3339 standard in UTC time.
          required: false
          schema:
            type: string
            format: date-time
            example: '2022-04-20T01:01:01Z'
        - name: toDate
          in: query
          description: >
            Specifies the latest date from which reports are requested. The input of toData is set according to RFC 3339 standard in UTC time.
          required: false
          schema:
            type: string
            example: '2022-04-20T01:01:01Z'
        - name: limit
          in: query
          required: false
          description: >
            Specifies the maximum number of entries to return. If the value exceeds the maximum, then the errror will be returned.
            If this parameter is not specified, the default value will be used.
          schema:
            type: integer
            format: int32
            example: 10000
            default: 10000
            minimum: 1
            maximum: 10000
        - name: offset
          in: query
          required: false
          description: >
            Specifies the offset of the first item in the collection to return. If the value exceeds the total count of result, empty result will be returned.
          schema:
            type: integer
            format: int32
            example: 0
            default: 0
            minimum: 0
        - name: customerNo
          in: query
          required: false
          description: |
            Specifies the customer number of the related organization. If this parameter is not specified, default organizationId from token will be used as query and validated with organization id field in DB.
            If both organizationId and customerNo are provided when query, organizationId will be used as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, default organizationId from token will be used as query and validated with organization id field in DB.
          schema:
            type: string
            example: '99887766'
        - name: organizationId
          in: query
          required: false
          description: |
            Specifies the organization ID number of the related organization. If this parameter is not specified, customerNo field in DB will be used as query.
            If both organizationId and customerNo are provided when query, organizationId will be used as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, default organizationId from token will be used as query and validate with organization id field in DB.
            ID of the organization could be a fix number e.g. “1.2.3” or it can contain ‘*’ as a wildcard in the following way:
            - '1.2.*' will filter all organization whose id starts with 1.2 but not the parent 1.2 itself
            - '1.2*' will filter all organizations whose id starts with 1.2 and include the parent 1.2 itself
          schema:
            type: string
            example: '3.78.2'
        - name: reportType
          in: query
          required: false
          description: >
            Specifies the type of reports to retrieve. If this parameter is specified, only reports of that type are returned.
            If this parameter is not specified, then reports for all types are returned.
          schema:
            $ref: "#/components/schemas/ReportTypeEnum"
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryReportsResponse'
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_report_download_operator
            - cnx_report_download_operator_2
            - cnx_report_download_opco
            - cnx_report_download_opco_2
            - cnx_report_download
            - cnx_report_download_2
            - cnx_report_download_no_invoice
            - cnx_report_download_no_invoice_2
  '/reports/{id}':
    get:
      tags:
        - Reports
      summary: Download a report data file
      description: >
        Returns the report data file which is identified by id.
      operationId: DownloadReport
      parameters:
        - name: id
          in: path
          description: Id of report data file which will be downloaded
          required: true
          schema:
            type: string
            example: '1650426960:CBADETRPT:99887766'
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '404':
          $ref: '#/components/responses/404Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_report_download_operator
            - cnx_report_download_operator_2
            - cnx_report_download_opco
            - cnx_report_download_opco_2
            - cnx_report_download
            - cnx_report_download_2
            - cnx_report_download_no_invoice
            - cnx_report_download_no_invoice_2
  '/invoices':
    get:
      tags:
        - Invoices
      summary: Query invoice data files
      description: >
        Returns a list of invoice data files that can be downloaded.
      operationId: QueryInvoices
      parameters:
        - name: fromDate
          in: query
          description: >
            Specifies the earliest date from which reports are requested. The input of fromData is set according to RFC 3339 standard in UTC time.
          required: false
          schema:
            type: string
            format: date-time
            example: '2022-04-20T01:01:01Z'
        - name: toDate
          in: query
          description: >
            Specifies the latest date from which reports are requested. The input of toData is set according to RFC 3339 standard in UTC time.
          required: false
          schema:
            type: string
            example: '2022-04-20T01:01:01Z'
        - name: limit
          in: query
          required: false
          description: >
            Specifies the maximum number of entries to return. If the value exceeds the maximum, then the errror will be returned. If this parameter is not specified, the default value will be used.
          schema:
            type: integer
            format: int32
            example: 10000
            default: 10000
            minimum: 1
            maximum: 10000
        - name: offset
          in: query
          required: false
          description: >
            Specifies the offset of the first item in the collection to return. If the value exceeds the total count of result, empty result will be returned.
          schema:
            type: integer
            format: int32
            example: 0
            default: 0
            minimum: 0
        - name: customerNo
          in: query
          required: false
          description: |
            Specifies the customer number of the related organization. If this parameter is not specified, default organizationId from token will be used as query and validated with organization id field in DB.
            If both organizationId and customerNo are provided when query, organizationId will be used as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, default organizationId from token will be used as query and validated with organization id field in DB.
          schema:
            type: string
            example: '99887766'
        - name: organizationId
          in: query
          required: false
          description: |
            Specifies the organization ID number of the related organization. If this parameter is not specified, customerNo field in DB will be used as query.
            If both organizationId and customerNo are provided when query, use organizationId as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, it will query with default organizationId from token and validate with organization id field in DB.
            ID of the organization could be a fix number e.g. “1.2.3” or it can contain ‘*’ as a wildcard in the following way:
            - '1.2.*' will filter all organization whose id starts with 1.2 but not the parent 1.2 itself
            - '1.2*' will filter all organizations whose id starts with 1.2 and include the parent 1.2 itself
          schema:
            type: string
            example: '3.78.2'
        - name: invoiceType
          in: query
          required: false
          description: >
            Specifies the type of invoices to retrieve. If this parameter is specified, only invoices of that type are returned. If this parameter is not specified, then invoices for all types are returned.
          schema:
            $ref: "#/components/schemas/InvoiceTypeEnum"
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryInvoicesResponse'
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '404':
          $ref: '#/components/responses/404Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_invoice_download_supplier
            - cnx_invoice_download_operator
            - cnx_invoice_download_operator_2
            - cnx_invoice_download
            - cnx_invoice_download_2
    delete:
      tags:
        - Invoices
      summary: Delete an invoice data file
      description: >
        Delete an invoice data file which is identified by invoice name.
      operationId: DeleteInvoice
      parameters:
        - name: invoiceName
          in: query
          description: >
            Specifies the name of invoice file which will be deleted
          required: true
          schema:
            type: string
            example: '2022-04-20-11-56-00C99887766TINVOICE.pdf'
        - name: customerNo
          in: query
          required: false
          description: |
            Specifies the customer number of the related organization. If this parameter is not specified, default organizationId from token will be used as query and validated with organization id field in DB.
            If both organizationId and customerNo are provided when query, organizationId will be used as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, default organizationId from token will be used as query and validated with organization id field in DB.
          schema:
            type: string
            example: '99887766'
        - name: organizationId
          in: query
          required: false
          description: |
            Specifies the organization ID number of the related organization. If this parameter is not specified,  customerNo field in DB will be used as query.
            If both organizationId and customerNo are provided when query, use organizationId as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, it will query with default organizationId from token and validate with organization id field in DB.
          schema:
            type: string
            example: '3.78.2'
      responses:
        '204':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: No Content
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '404':
          $ref: '#/components/responses/404Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_invoice_download_supplier
            - cnx_invoice_download_operator
            - cnx_invoice_download_operator_2
            - cnx_invoice_download
            - cnx_invoice_download_2
  '/invoices/{id}':
    get:
      tags:
        - Invoices
      summary: Download an invoice data file
      description: >
        Returns the invoice data file which is identified by id.
      operationId: DownloadInvoice
      parameters:
        - name: id
          in: path
          description: Id of invoice data file which will be downloaded, this value can be in customerNO or organizationId format, which will be validated against DB field for customerNo and organizationId respectively.
          required: true
          schema:
            type: string
            example: '1650426960:INVOICE:99887766'
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '404':
          $ref: '#/components/responses/404Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_invoice_download_supplier
            - cnx_invoice_download_operator
            - cnx_invoice_download_operator_2
            - cnx_invoice_download
            - cnx_invoice_download_2
  '/usages':
    get:
      tags:
        - Usages
      summary: Query usage data files
      description: >
        Returns a list of report data files that can be downloaded.
      operationId: QueryUsage
      parameters:
        - name: fromDate
          in: query
          description: >
            Specifies the earliest date from which usage data are requested. The input of fromData is set according to RFC 3339 standard in UTC time.
          required: false
          schema:
            type: string
            format: date-time
            example: '2022-04-20T01:01:01Z'
        - name: toDate
          in: query
          description: >
            Specifies the latest date from which usage data are requested. The input of tomData is set according to RFC 3339 standard in UTC time.
          required: false
          schema:
            type: string
            format: date-time
            example: '2022-04-20T01:01:01Z'
        - name: limit
          in: query
          required: false
          description: >
            Specifies the maximum number of entries to return. If the value exceeds the maximum, then the errror will be returned. If this parameter is not specified, the default value will be used.
          schema:
            type: integer
            format: int32
            example: 10000
            default: 10000
            minimum: 1
            maximum: 10000
        - name: offset
          in: query
          required: false
          description: >
            Specifies the offset of the first item in the collection to return. If the value exceeds the total count of result, empty result will be returned.
          schema:
            type: integer
            format: int32
            example: 0
            default: 0
            minimum: 0
        - name: customerNo
          in: query
          required: false
          description: |
            Specifies the customer number of the related organization. If this parameter is not specified, default organizationId from token will be used as query and validated with organization id field in DB.
            If both organizationId and customerNo are provided when query, organizationId will be used as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, default organizationId from token will be used as query and validated with organization id field in DB.
          schema:
            type: string
            example: '99887766'
        - name: organizationId
          in: query
          required: false
          description: |
            Specifies the organization ID number of the related organization. If this parameter is not specified,  customerNo field in DB will be used as query.
            If both organizationId and customerNo are provided when query, use organizationId as query criteria and validate with customerNo field in DB.
            If none of organizationId or customerNo is provided when query, it will query with default organizationId from token and validate with organization id field in DB.
            ID of the organization could be a fix number e.g. “1.2.3” or it can contain ‘*’ as a wildcard in the following way:
            - '1.2.*' will filter all organization whose id starts with 1.2 but not the parent 1.2 itself
            - '1.2*' will filter all organizations whose id starts with 1.2 and include the parent 1.2 itself
          schema:
            type: string
            example: '3.78.2'
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryUsagesResponse'
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_usage_data_download
            - cnx_usage_data_download_2
  '/usages/{id}':
    get:
      tags:
        - Usages
      summary: Download a usage data file
      operationId: DownloadUsage
      description: >
        Returns the usage data file which is identified by id.
      parameters:
        - name: id
          in: path
          description: Id of usage data file which will be downloaded, this value can be in customerNO or organizationId format, which will be validated against DB field for customerNo and organizationId respectively.
          required: true
          schema:
            type: string
            example: '1234567800000'
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '404':
          $ref: '#/components/responses/404Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_usage_data_download
            - cnx_usage_data_download_2
  '/aggregated-traffic-usages/top-usage-subscriptions':
    get:
      tags:
        - Aggregated traffics
      summary: Query the top subscriptions with most traffic usage.
      operationId: TopUsageSubscriptions
      description: >
        Returns the top subscriptions with most traffic usage in the specified time duration.
      parameters:
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/ResultLimit'
        - $ref: '#/components/parameters/TrafficType'
        - $ref: '#/components/parameters/OrganizationId'
        - $ref: '#/components/parameters/DateRange'
      responses:
        '200':
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficTopUsageSubscriptionsResponse'
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
        '403':
          $ref: '#/components/responses/403Response'
        '404':
          $ref: '#/components/responses/404Response'
        '429':
          $ref: '#/components/responses/429Response'
        '500':
          $ref: '#/components/responses/500Response'
        default:
          $ref: '#/components/responses/500Response'
      security:
        - Oauth2_auth:
            - cnx_top_traffic_subscr_gprs
            - cnx_top_traffic_subscr_sms
components:
  responses:
    RateLimitedResponse:
      headers:
        X-RateLimit-Limit-Second:
          $ref: '#/components/headers/X-RateLimit-Limit-Second'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/X-RateLimit-Limit-Minute'
        X-RateLimit-Remaining-Second:
          $ref: '#/components/headers/X-RateLimit-Remaining-Second'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    400Response:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Bad Request'
                status: 400
                detail: 'Invalid customerNo'
                instance: 'https://hostname/iot/api/some-path'
    401Response:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Unauthorized'
                status: 401
                detail: 'Token expired'
                instance: 'https://hostname/iot/api/some-path'
    403Response:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Forbidden'
                status: 403
                detail: 'You do not have access to the resource'
                instance: 'https://hostname/iot/api/some-path'
    404Response:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Not Found'
                status: 404
                detail: 'Not Found'
                instance: 'https://hostname/iot/api/some-path'
    '429Response':
      description: Too Many Requests
      headers:
        X-RateLimit-Limit-Second:
          $ref: '#/components/headers/X-RateLimit-Limit-Second'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/X-RateLimit-Limit-Minute'
        X-RateLimit-Remaining-Second:
          $ref: '#/components/headers/X-RateLimit-Remaining-Second'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    500Response:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            response:
              value:
                type: 'https://www.iana.org/assignments/http-status-codes/'
                title: 'Internal Server Error'
                status: 500
                detail: 'Internal Server Error'
                instance: 'https://hostname/iot/api/some-path'
  headers:
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    X-RateLimit-Limit-Second:
      description: The maximum number of requests allowed in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Minute:
      description: The maximum number of requests allowed in a minute.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Second:
      description: The number of requests remaining in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining in a minute.
      schema:
        type: integer
        format: int32
  schemas:
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type. When dereferenced,it SHOULD provide
            human-readable documentation for the problem type (e.g., using HTML).
          default: about:blank
          example: 'http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable for engineers (usually not suited
            for non technical stakeholders and not localized.
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
        detail:
          type: string
          description: A human readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          example: 'https://api.documentation.url/request-id'
    ReportTypeEnum:
      type: string
      description: The report types.
      example: CBADETRPT
      x-extensible-enum:
        - CBADETRPT
        - CBDETRPT
        - CBISRPT
        - CBPPCRPT
        - CBRECRPT
        - CCHARPT
        - CERRRPT
        - COPCRPT
        - CRECRPT
        - CTRATRPT
        - CTRFRPT
        - CUSTOM
        - IMSINM
        - MSISDNUSE
        - OI01
        - OI04
        - OI05
        - SIMORDER
        - SIMSTADET
        - SIMSTAGE
        - SIMSTAT
        - SIMTERM
        - TIMRECRPT
        - SIMACTDET
    QueryReportsResponse:
      type: object
      properties:
        limit:
          type: integer
          format: int32
          description: The limit used for this page of results. This will be the same as the limit query parameter unless it exceeded the maximum value if it is specified in query request. If the limit parameter not specified in query request, the default value is used.
          example: 10000
          default: 10000
          minimum: 1
          maximum: 10000
        offset:
          type: integer
          format: int32
          description: The offset used for this page of results. This will be the same as the offset query parameter if it is specified in query request. If the offset is not specified in the query request, the default value is used.
          example: 0
          default: 0
          minimum: 0
        totalCount:
          type: integer
          format: int32
          description: The total count of results, which is one greater than the offset of the last item in the entire collection.
          example: 4001
        reports:
          type: array
          items:
            $ref: '#/components/schemas/QueryReportsResponseItem'
    QueryReportsResponseItem:
      type: object
      properties:
        id:
          type: string
          example: '1650426960:CBADETRPT:99887766'
          description: The id of report data file can be downloaded.
        reportDate:
          type: string
          format: date-time
          example: '2022-04-20T01:01:01.001Z'
          description: The date when the file was produced, which is set according to RFC 3339 standard in UTC time.
        size:
          type: integer
          format: int64
          example: 500000
          description: The size of the file in bytes.
        reportType:
          $ref: "#/components/schemas/ReportTypeEnum"
        reportPeriod:
          type: string
          example: '2022-04'
          description: The time period for the report.
    InvoiceTypeEnum:
      type: string
      description: The invoice types.
      example: INVOICE
      x-extensible-enum:
        - INVOICE
        - INV_DET
    QueryInvoicesResponse:
      type: object
      properties:
        limit:
          type: integer
          format: int32
          description: The limit used for this page of results. This will be the same as the limit query parameter unless it exceeded the maximum value if it is specified in query request. If the limit parameter not specified in query request, the default value is used.
          example: 10000
          default: 10000
          minimum: 1
          maximum: 10000
        offset:
          type: integer
          format: int32
          description: The offset used for this page of results. This will be the same as the offset query parameter if it is specified in query request. If the offset is not specified in the query request, the default value is used.
          example: 0
          default: 0
          minimum: 0
        totalCount:
          type: integer
          format: int32
          description: The total count of results, which is one greater than the offset of the last item in the entire collection.
          example: 4001
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/QueryInvoicesResponseItem'
    QueryInvoicesResponseItem:
      type: object
      properties:
        id:
          type: string
          example: '1650426960:INVOICE:99887766'
          description: The id of inovice data file can be downloaded.
        invoiceName:
          type: string
          example: '2022-04-20-11-56-00C99887766TINVOICE.pdf'
        reportDate:
          type: string
          format: date-time
          example: '2022-04-20T01:01:01.001Z'
          description: The date when the file was produced, which is set according to RFC 3339 standard in UTC time.
        size:
          type: integer
          format: int64
          example: 500000
          description: The size of the file in bytes.
        invoiceType:
          $ref: "#/components/schemas/InvoiceTypeEnum"
        invoicePeriod:
          type: string
          example: '2022-04'
          description: The time period for the invoice.
    QueryUsagesResponse:
      type: object
      properties:
        limit:
          type: integer
          format: int32
          description: The limit used for this page of results. This will be the same as the limit query parameter unless it exceeded the maximum value if it is specified in query request. If the limit parameter not specified in query request, the default value is used.
          example: 10000
          default: 10000
          minimum: 1
          maximum: 10000
        offset:
          type: integer
          format: int32
          description: The offset used for this page of results. This will be the same as the offset query parameter if it is specified in query request. If the offset is not specified in the query request, the default value is used.
          example: 0
          default: 0
          minimum: 0
        totalCount:
          type: integer
          format: int32
          description: The total count of results, which is one greater than the offset of the last item in the entire collection.
          example: 4001
        usages:
          type: array
          items:
            $ref: '#/components/schemas/QueryUsagesResponseItem'
    QueryUsagesResponseItem:
      type: object
      properties:
        id:
          type: string
          example: '1234567800000'
          description: The id of usage data file can be downloaded.
        date:
          type: string
          format: date-time
          example: '2022-04-20T01:01:01.001Z'
          description: The date when the file was created, which is set according to RFC 3339 standard in UTC time.
        size:
          type: integer
          format: int64
          example: 500000
          description: The size of the file in bytes.
    TrafficTypeEnum:
      type: string
      description: The traffice types.
      example: SMS
      x-extensible-enum:
        - SMS
        - DATA
    TrafficTopUsageSubscriptionsResponse:
      type: object
      properties:
        subscriptionTrafficUsageData:
          type: array
          items:
            $ref: '#/components/schemas/TrafficTopUsageSubscriptionsResponseItem'
    TrafficTopUsageSubscriptionsResponseItem:
      type: object
      properties:
        imsi:
          type: string
          example: '238208000000001'
          description: The IMSI of the subscription.
        msisdn:
          type: string
          example: '33123456789'
          description: The MSISDN of the subscription.
        volume:
          type: integer
          format: int64
          example: 500000
    DateRangeEnum:
      type: string
      description: |
        An enum which defines supported date range values:
          - LAST_DAY
          - LAST_2_DAYS
          - LAST_7_DAYS
          - LAST_30_DAYS
          - THIS_MONTH
      enum:
        - LAST_DAY
        - LAST_2_DAYS
        - LAST_7_DAYS
        - LAST_30_DAYS
        - THIS_MONTH
  parameters:
    FromDate:
      name: fromDate
      in: query
      description: >
        Specifies the earliest date to search for aggregated traffic usage, in the following format: YYYY-MM-DD.
        Traffic usage data is available only from the last 31 days.
      required: false
      schema:
        type: string
        format: date
      example: '2022-04-20'
    ToDate:
      name: toDate
      in: query
      description: >
        Specifies the latest date to search for aggregated traffic usage, in the following format: YYYY-MM-DD.
        The starting and ending dates must define a period of 1, 7, or 30 days. Otherwise, an error is returned.
      required: false
      schema:
        type: string
        format: date
      example: '2022-04-20'
    ResultLimit:
      name: resultLimit
      in: query
      required: true
      description: >
        Specifies the number of results the query returns. Maximum possible value is 250.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 250
      example: 5
    TrafficType:
      name: trafficType
      in: query
      required: true
      description: >
        Specifies the traffic type to search for.
      schema:
        $ref: "#/components/schemas/TrafficTypeEnum"
    OrganizationId:
      name: organizationId
      in: query
      required: false
      description: >
        Specifies the organization ID.
      schema:
        type: string
      example: '3.88.2'
    DateRange:
      name: dateRange
      in: query
      required: false
      description: |
        An optional parameter which is used to selects most common date ranges.
        Valid values are:
          - LAST_DAY
          - LAST_2_DAYS
          - LAST_7_DAYS
          - LAST_30_DAYS
          - THIS_MONTH

        This parameter takes precedence over 'fromDate' and 'toDate' and calculates the dates automatically
        based on the selected dateRange. If user provides all parameters 'fromDate', 'toDate' and 'dateRange'
        then 'fromDate', 'toDate' provided by user are ignored.
      schema:
        $ref: '#/components/schemas/DateRangeEnum'
      example: LAST_DAY
  securitySchemes:
    Oauth2_auth:
      type: oauth2
      flows:
        password:
          tokenUrl:
            /iot/api/auth/token
          scopes:
            cnx_report_download_operator: |-
              Download monthly reports - for TCXN (old)
            cnx_report_download_operator_2: |-
              Download monthly reports - for TCXN
            cnx_report_download_opco: |-
              Download monthly reports - for operators (old)
            cnx_report_download_opco_2: |-
              Download monthly reports - for operators
            cnx_report_download: |-
              Download monthly reports - for TCXN (old)
            cnx_report_download_2: |-
              Download monthly reports - for enterprises
            cnx_report_download_no_invoice: |-
              Download monthly reports (no billing-related reports) - for enterprises (old)
            cnx_report_download_no_invoice_2: |-
              Download monthly reports (no billing-related reports) - for enterprises
            cnx_invoice_download_supplier: |-
              Download invoices + invoice deletion - for supplier
            cnx_invoice_download_operator: |-
              Download invoices + invoice deletion - for operators (old)
            cnx_invoice_download_operator_2: |-
              Download invoices + invoice deletion
            cnx_invoice_download: |-
              Download invoices - for enterprises (old)
            cnx_invoice_download_2: |-
              Download invoices
            cnx_usage_data_download: |-
              Download usage data (old)
            cnx_usage_data_download_2: |-
              Download usage data
            cnx_top_traffic_subscr_gprs: |-
              API: Subscriptions with most data traffic
            cnx_top_traffic_subscr_sms: |-
              API: Subscriptions with most SMS traffic
