
---
openapi: 3.0.1
info:
  title: AutoInvoice Billing API
  description: |
    ## Authentication

    A consumer is authenticated by providing a OAuth 2.0 bearer token in the HTTP Authorization header.
    The tokens are obtained using the AX API `/oauth2/token` endpoint. More details about the endpoint can be found from [here](https://swagger.maventa.com/#/oauth2/postOauth2Token).

    Example on fetching a new token:

    ```
    curl -X POST "https://ax.maventa.com/oauth2/token" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "grant_type=client_credentials" -F "client_id=COMPANY_UUID" -F "client_secret=USER_API_KEY" -F "scope=billing:reports" -F "vendor_api_key=VENDOR_API_KEY"
    ```

    The token endpoint will on success return a JSON with the token and some additional information about the token to the consumer.

    ```
    {
      "access_token":"THE_TOKEN",
      "token_type":"bearer",
      "expires_in":3600,
      "scope":"billing:reports"
    }
    ```

    The token is to be included in the Authorization header when the actual resource is called.
    ```
    curl -X GET "https://bling-stage.maventa.com/billing/api/v2/reports/billing_company_transactions?year=2021&month=1" -H "accept: application/json" -H "Authorization: Bearer THE_TOKEN"
    ```

    To reduce overhead it is recommended to reuse the token as long as it's valid.


    ## Error handling

    Errors are represented in a simple JSON format.
    ```
    {
      "message": "The error message in human readable form"
    }
    ```
  version: "0.0.346"
tags:
  - name: Billing API V2
paths:
  /api/billing/v2/reports/billing_company_transactions:
    get:
      tags:
        - Billing API V2
      description: |
        Returns transaction counts that are assigned to the authenticated billing company (partner). The endpoint contains transactions for the current quarter.
        
        **Data for the current month is susceptible for change up until the 1st working day of the next month 14:00 EET!**
        
        **Current quarter's data is kept until the 15th of the first month of the next quarter.**
      parameters:
       - in: query
         name: year
         schema:
           type: integer
         description: The year for the report
       - in: query
         name: month
         schema:
           type: integer
         description: The month for the report

      responses:
        200:
          description: Transaction listing for selected month
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/transaction"
        400:
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      security:
      - company_auth:
        - billing:reports

  /api/billing/v2/reports/billing_company_transactions/available:
    get:
      tags:
        - Billing API V2
      description: |
        [EXPERIMENTAL] Provides the latest available month for complete billing company transaction data, indicating whether the data for the current calendar month is complete or still being aggregated.

      responses:
        200:
          description: Latest available complete month of transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  latest_available_month:
                    type: string
                    description: The latest month for which data is fully available.
                    example: "2024-07"
        400:
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      security:
      - company_auth:
        - billing:reports

  /api/billing/v2/actions:
    post:
      tags:
        - Billing API V2
      description: Creates a new action
      parameters:
       - in: query
         name: software_origin_id
         required: true
         schema:
           type: string
         description: Software id in the source system
       - in: query
         name: software_origin
         required: true
         schema:
           type: string
         description: Software source system
       - in: query
         name: company_origin_id
         required: true
         schema:
           type: string
         description: Company id in the source system
       - in: query
         name: company_origin
         required: true
         schema:
           type: string
         description: Company source system
       - in: query
         name: action_name
         required: true
         schema:
           type: string
         description: Action name
       - in: query
         name: origin_id
         required: true
         schema:
           type: string
         description: Action id in the source system
       - in: query
         name: origin_time
         required: true
         schema:
           type: string
           format: date-time
         description: Action timestamp in the source system
       - in: query
         name: description
         required: false
         schema:
           type: string
         description: Optional description
       - in: query
         name: license_key
         required: false
         schema:
           type: string
         description: License key from source system
       - in: query
         name: license_meta
         required: false
         schema:
           type: string
         description: License key meta information from source system
       - in: query
         name: action_item_count
         required: false
         schema:
           type: integer
         description: Number of this same action
      responses:
        200:
          description: Action already exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/action"
        201:
          description: Action successfully created
        400:
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      security:
      - operator_auth:
        - operator:billing:actions
components:
  schemas:
    transaction:
      type: object
      properties:
        company_id:
          description: "Company name"
          type: string
        company_name:
          description: "Company name"
          type: string
        company_bid:
          description: "Company BID"
          type: string
        software_name:
          description: "Software"
          type: string
        action_name:
          description: "Action name"
          type: string
        licensing_system:
          description: "Licensing system"
          type: string
        license_key:
          description: "License key"
          type: string
        license_meta:
          description: "License meta"
          type: string
        action_count:
          description: "Number of actions"
          type: integer
    error:
      type: object
      properties:
        message:
          description: "Error message"
          type: string
    action:
      type: object
      properties:
        id:
          description: "Action id"
          type: string
        software_origin_id:
          description: "Software id in the origin system"
          type: string
        software_origin:
          description: "Software origin system"
          type: string
        company_origin_id:
          description: "Company id in the origin system"
          type: string
        company_origin:
          description: "Company origin system"
          type: string
        action_name:
          description: "Action name"
          type: string
        origin_id:
          description: "Action id in the origin system"
          type: string
        origin:
          description: "Origin system"
          type: string
        origin_time:
          description: "Action time in the origin system"
          type: string
          format: date-time
        description:
          description: "Action description"
          type: string
        license_key:
          description: "License key"
          type: string
        license_meta:
          description: "License meta"
          type: string
        licensing_system:
          description: "Licensing system"
          type: string
        action_item_count:
          description: "Action item count"
          type: integer
  securitySchemes:
    company_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://ax.maventa.com/oauth2/token
          scopes:
            billing:reports: grants access to the AutoInvoice billing service
    operator_auth:
          type: oauth2
          flows:
            clientCredentials:
              tokenUrl: https://ax.maventa.com/oauth2/token
              scopes:
                operator:billing:actions: grants access to the AutoInvoice billing service


