openapi: "3.0.0"
info:
  # version field is replaced by bazel with the value set in version.bzl
  version: v0.0.0
  title: MasBilling API
  description: This API features a set of MasStack endpoints related to MasBilling domain.
  contact:
    name: MasBilling

servers:
  - url: https://billing.masstack.com/v1/
    description: production
  - url: https://billing.sta.masstack.com/v1/
    description: staging

security:
  - bearerAuth: [ ]

tags:
  - name: Consumptions
    description: Rating API for retrieving subscriptions consumption info
  - name: Movements
    description: Billing API for managing different types of billing movements (discounts, recurring charges...)
  - name: Adjustments
    description: Billing API for managing billing adjustments
  - name: Refunds
    description: Billing API for managing billing refunds
  - name: Invoices
    description: Billing API for managing invoices
  - name: LocationTax
    description: Billing API for fetching location taxes
  - name: BillingInfo
    description: Commons API for fetching tenants billing info

paths:
  /orgs/{orgId}:
    get:
      tags: [ BillingInfo ]
      summary: Gets billing info related to an organization
      description: This endpoint retrieves the billing info associated to a tenant by its tenant name
      operationId: getBillingInfoByOrgId
      parameters:
        - $ref: '#/components/parameters/OrgIdParam'
      responses:
        "200":
          description: "Billing info"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInfoDto'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalServerError'

  "/orgs/{orgId}/subscription/{subscriptionId}/consumptions":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
    get:
      tags: [ Consumptions ]
      summary: Get subscription general consumptions info
      description: >
        Show subscription general consumptions info (bonus and monetary balances).
        <ul>
        <li>This service will provide information for prepaid and postpaid subscriptions.</li>
        <li>Prepaid subscriptions
        <ul>
        <li>This service will inform only about the subscription monetary balance at the request moment.</li>
        </ul>
        </li>
        <li>Postpaid subscriptions
        <ul>
        <li>This service will inform about monetary and bonus balances of the current billing cycle, i.e., from the period between 1st day of the current billing cycle and the request moment.</li>
        <li>This service will only inform about subscriptions that have been active during the current billing cycle. For terminated subscriptions in previous billing cycles, no information will be offered.</li>
        </ul>
        </li>
        </ul>
      operationId: getSubscription
      responses:
        '200':
          description: Subscription balances details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseDTO'
              #              TODO: Adapt to multiple examples when https://jiranext.masmovil.com/browse/DP-145 is resolved
              #              examples:
              #                Postpaid:
              #                  value:
              #                    id: "123456789"
              #                    ... copy here data from current example
              #                Prepaid:
              #                  value:
              #                    id: "123456789"
              #                    msisdn: "623529562"
              #                    tenant: "masmovil"
              #                    billingType: 1
              #                    monetary:
              #                      - id: "623529562-23002923-MONETARY_DEFAULT"
              #                        currentValue: 50
              #                        currentValueWithTaxes: 0
              #                        unit: "EUR"
              #                        activationDatetime: "2022-02-05T00:00:00Z"
              #                        expirationDatetime: "2022-03-06T00:00:00Z"
              #                    bonuses:
              #                      data: []
              #                      sms: []
              #                      voice: []
              example:
                id: "123456789"
                msisdn: "666554433"
                tenant: "masmovil"
                billingType: 2
                monetary:
                  - id: "666554433-123456789-MONETARY_DEFAULT-2020-09-01T00:00:00+02:00"
                    currentValue: -4.7
                    currentValueWithTaxes: -5.69
                    unit: "EUR"
                    activationDatetime: "2020-08-31T22:00:00Z"
                    expirationDatetime: "2021-09-30T21:59:59.999999999Z"
                    counters:
                      - type: "internationalVoice"
                        value: -1.34234534
                      - type: "premium"
                        value: 0
                      - type: "roamingVoice"
                        value: -15.7
                      - type: "estimatedTotal"
                        value: -27.04234534
                      - type: "estimatedRoamingVoice"
                        value: -20.6
                bonuses:
                  data:
                    - id: "666554433-123456789-BONUS_TEMPLATE-3072-76789123-2020-09-01T00:00:00+02:00"
                      initialValue: 3221225472
                      currentValue: 3048467002
                      unit: "byte"
                      activationDatetime: "2020-08-31T22:00:00Z"
                      expirationDatetime: "2021-09-30T21:59:59.999999999Z"
                      renovationsCount: 3
                      catalogBonusId: "4321"
                      customerBonusId: "76789123"
                      isShared: false
                    - id: "432156789-777554433-223456789-BONUS_TEMPLATE-4096-66789123-2020-09-01T00:00:00+02:00"
                      initialValue: 4294967296
                      currentValue: 3948568002
                      unit: "byte"
                      activationDatetime: "2020-08-31T22:00:00Z"
                      expirationDatetime: "2021-09-30T21:59:59.999999999Z"
                      renovationsCount: 3
                      catalogBonusId: "5321"
                      customerBonusId: "66789123"
                      isShared: true
                  sms:
                    - id: "666554433-123456789-BONUS_TEMPLATE-1000-56789123-2020-09-01T00:00:00+02:00"
                      initialValue: 1000
                      currentValue: 982
                      unit: "sms"
                      activationDatetime: "2020-08-31T22:00:00Z"
                      expirationDatetime: "2021-09-30T21:59:59.999999999Z"
                      renovationsCount: 3
                      catalogBonusId: "6321"
                      customerBonusId: "56789123"
                      isShared: false
                  voice:
                    - id: "666554433-123456789-BONUS_TEMPLATE-100-46789123-2020-09-01T00:00:00+02:00"
                      initialValue: 6000
                      currentValue: 4781
                      unit: "second"
                      activationDatetime: "2020-08-31T22:00:00Z"
                      expirationDatetime: "2021-09-30T21:59:59.999999999Z"
                      renovationsCount: 3
                      catalogBonusId: "7321"
                      customerBonusId: "46789123"
                      isShared: false
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "subscriptionNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "getSubscription"

  "/orgs/{orgId}/subscription/{subscriptionId}/consumptions/details":
    parameters:
      - $ref: '#/components/parameters/CdrTypeParam'
      - $ref: '#/components/parameters/DatetimeFromParam'
      - $ref: '#/components/parameters/DatetimeToParam'
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
    get:
      tags: [ Consumptions ]
      summary: Get subscription consumptions details
      description: >
        Show subscription consumptions details (subscription cdrs details). Consumption details could be filtered by period and traffic type ("data", "sms", "voice").
        <ul>
        <li>This service will provide information for prepaid and postpaid subscriptions.</li>
        <li>Prepaid subscriptions
        <ul>
        <li>If a period is not specified, this service will offer consumption details for the last 30 days.</li>
        <li>If a period is specified, this service will offer consumption details for a maximum of the last 90 days.
        For example, if we are at "2021-09-15T16:01:03Z" (note that dates are in UTC) we could request a maximum period that spans from "2021-06-17T16:01:03Z"
        to "2021-09-15T16:01:03Z". Out of this period, service will return an error indicating that the requested period is outside the limits.
        </li>
        </ul>
        </li>
        <li>Postpaid subscriptions
        <ul>
        <li>If a period is not specified, this service will offer consumption details of the current billing cycle, that is, the period between beginning of the billing cycle and the request moment.</li>
        <li>If a period is specified, this service will offer consumption details for a maximum of 3 billing cycles prior to the current one.
        For example, if we are at "2021-09-15T16:01:03Z" (note that dates are in UTC) we could request a maximum period that spans from "2021-05-31T22:00:00Z"
        to "2021-09-15T16:01:03Z" for a tenant whose billing cycle start on the first day of the month.
        Out of this period, the service will return an error indicating that the requested period is outside the limits.
        </li>
        </ul>
        </li>
        </ul>
      operationId: getCdrsBySubscription
      responses:
        '200':
          description: Subscription cdrs details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CdrsByTypeResponseDTO'
              example:
                data:
                  - id: "18ba3a8322cb67ad7df47fb28996144ec185479"
                    originNumber: "610545315"
                    destinationNumber: ""
                    initialDate: "2021-12-18T00:00:00Z"
                    usage: 58411055
                    unit: "byte"
                    costWithoutTaxes: 0
                    taxPercentage: 21
                    ratingCaseCategory: "DATA_NATIONAL"
                    debitCase: "bonus"
                    debitCatalogId: "321"
                    debitCustomerId: "24920761"
                sms:
                  - id: "088f5b34429b17be13bdc5787adcaa1d54aec1a4"
                    originNumber: "610545315"
                    destinationNumber: "600124932"
                    initialDate: "2022-01-04T15:50:49Z"
                    usage: 1
                    unit: "sms"
                    costWithoutTaxes: 0.08
                    taxPercentage: 21
                    ratingCaseCategory: "SMS_NATIONAL"
                    debitCase: "rating_plan"
                    debitCatalogId: "316"
                    debitCustomerId: ""
                voice:
                  - id: "f802dff30b5ebec9ea9d886c81cb553d5dbb330a"
                    originNumber: "610545315"
                    destinationNumber: "636648371"
                    initialDate: "2021-12-17T11:24:45Z"
                    usage: 13
                    unit: "second"
                    costWithoutTaxes: 0.165289
                    taxPercentage: 21
                    ratingCaseCategory: "VOICE_NATIONAL"
                    debitCase: "rating_plan"
                    debitCatalogId: "316"
                    debitCustomerId: ""
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "wrongPrepaidRequestedPeriod"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "subscriptionNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "getSubscription"

  "/orgs/{orgId}/account/{accountId}/adjustment":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      tags: [ Adjustments ]
      operationId: getAccountAdjustments
      summary: Get a list of all account adjustments
      description: Retrieve a list of all account adjustments for a given account.
      responses:
        '200':
          description: Retrieve a list of all account adjustments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountAdjustmentResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'
    post:
      tags: [ Adjustments ]
      operationId: createAccountAdjustment
      summary: Create a new account adjustment
      description: Create a new account adjustment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountAdjustmentRequestDTO'
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/account/{accountId}/adjustment/{adjustmentId}":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/AdjustmentIdParam'
    get:
      tags: [ Adjustments ]
      operationId: getAccountAdjustment
      summary: Get a single account adjustment
      description: Retrieve a single account adjustment.
      responses:
        '200':
          description: Retrieve a single account adjustment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdjustmentResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'
    put:
      tags: [ Adjustments ]
      operationId: updateAccountAdjustment
      summary: Update a single account adjustment
      description: Update an existing account adjustment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountAdjustmentRequestDTO'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'
    delete:
      tags: [ Adjustments ]
      operationId: deleteAccountAdjustment
      summary: Delete a single account adjustment
      description: Delete an existing account adjustment.
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/subscription/{subscriptionId}/adjustment":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
    post:
      tags: [ Adjustments ]
      operationId: "createAdjustment"
      summary: "Create a new billing movement of type adjustment"
      description: >
        Create a new billing movement of type adjustment.


        **Validation Requirements:**

        - `adjustment_datetime`: Must be set and the subscription must be active at this date/time.

        - `external_adjustment_unique_id`: Must be unique within the subscription. Cannot duplicate an existing adjustment's external ID.

        - `transaction_type_id`: Must exist in the catalogue and be valid for this subscription's commercial product.

        - `description`: Required and cannot be empty.

        - `amount`: Either `value_without_taxes` OR `value_with_taxes` must be provided (not both), and the value must be greater than 0.

        - `period_start_datetime` and `period_end_datetime`: Both must be provided together, or neither. If both are provided, `adjustment_datetime` must fall within this period (inclusive).

        - Subscription must have a postpaid billing type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustmentRequestDTO'
            example:
              adjustment_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_without_taxes: 10.76549736
              external_adjustment_unique_id: "987654321"
              transaction_type_id: "5432167890"
              description: "February invoice"
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/subscription/{subscriptionId}/adjustment/{adjustmentId}":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
      - $ref: '#/components/parameters/AdjustmentIdParam'
    put:
      tags: [ Adjustments ]
      operationId: "updateAdjustment"
      summary: "Update a single billing movement of type adjustment"
      description: >
        Update an existing billing movement of type adjustment. Adjustments can only be updated if they have not been invoiced, that is,
        if their invoice_id field is empty.


        **Validation Requirements:**

        - `adjustment_datetime`: Must be set and the subscription must be active at this date/time.

        - `external_adjustment_unique_id`: Must be unique within the subscription. Cannot duplicate another adjustment's external ID (can match the same adjustment being updated).

        - `transaction_type_id`: Must exist in the catalogue and be valid for this subscription's commercial product.

        - `description`: Required and cannot be empty.

        - `amount`: Either `value_without_taxes` OR `value_with_taxes` must be provided (not both), and the value must be greater than 0.

        - `period_start_datetime` and `period_end_datetime`: Both must be provided together, or neither. If both are provided, `adjustment_datetime` must fall within this period (inclusive).

        - Subscription must have a postpaid billing type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustmentRequestDTO'
            example:
              adjustment_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_without_taxes: 10.76549736
              external_adjustment_unique_id: "987654321"
              transaction_type_id: "5432167890"
              description: "February invoice"
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
    get:
      tags: [ Movements ]
      parameters:
        - $ref: '#/components/parameters/DatetimeFromParam'
        - $ref: '#/components/parameters/DatetimeToParam'
        - $ref: '#/components/parameters/MovementTypeParam'
        - $ref: '#/components/parameters/OperationTypeParam'
      operationId: "getMovements"
      summary: "Get a list of all billing movements, related to a subscription"
      description: >
        In the context of a given subscription, retrieves a list of all related billing movements.
      responses:
        '200':
          description: "List of all subscription billing movements"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MovementResponseDTO'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "subscriptionNotFound"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "getMovements"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "getMovements"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
    post:
      tags: [ Movements ]
      operationId: "createMovement"
      summary: "Create a new billing movement"
      description: >
        Create a new billing movement.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovementRequestDTO'
            example:
              type: "RECURRING_CHARGE"
              movement_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_with_taxes: 13.02625181
                value_without_taxes: 10.76549736
                tax:
                  type: "IVA"
                  percentage: 21
              external_invoice_id: "123456789"
              external_movement_unique_id: "987654321"
              billable: false
              description: "February invoice"
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "wrongMovementBody"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "createMovement"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "createMovement"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
      - $ref: '#/components/parameters/MovementIdParam'
    get:
      tags: [ Movements ]
      operationId: "getMovement"
      summary: "Get a single billing movement"
      description: >
        Retrieves a single billing movement.
      responses:
        '200':
          description: "Retrieve a billing movement"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MovementResponseDTO'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "subscriptionNotFound"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "movementNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "getMovement"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "getMovement"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
    put:
      tags: [ Movements ]
      description: >
        Update an existing billing movement. Movements can only be updated if they have not been invoiced, that is, if their invoice_id field is empty.
      summary: "Update a single billing movement"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovementRequestDTO'
            example:
              type: "RECURRING_CHARGE"
              movement_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_with_taxes: 13.02625181
                value_without_taxes: 10.76549736
                tax:
                  type: "IVA"
                  percentage: 21
              external_invoice_id: "123456789"
              external_movement_unique_id: "987654321"
              billable: false
              description: "February invoice"
      operationId: "updateMovement"
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "wrongMovementBody"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "movementNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "updateMovement"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "updateMovement"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
    delete:
      tags: [ Movements ]
      operationId: "deleteMovement"
      summary: "Delete a single billing movement"
      description: >
        Delete an existing billing movement. Movements can only be deleted if they have not been invoiced, that is, if their invoice_id field is empty.
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "subscriptionNotFound"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "movementNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "deleteMovement"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "deleteMovement"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement-non-subscribable-products":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
    post:
      tags: [ Movements ]
      operationId: "createMovementNonSubscribableProducts"
      summary: "Create a new billing movement (for non subscribable products)"
      description: >
        Create a new billing movement (for non subscribable products).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovementNonSubscribableProductsRequestDTO'
            example:
              type: "RECURRING_CHARGE"
              movement_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_with_taxes: 13.02625181
                value_without_taxes: 10.76549736
                tax:
                  type: "IVA"
                  percentage: 21
              external_invoice_id: "123456789"
              external_movement_unique_id: "987654321"
              transaction_type_id: "5432167890"
              description: "February invoice"
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "wrongMovementBody"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "createMovementNonSubscribableProducts"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "createMovementNonSubscribableProducts"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement-non-subscribable-products/{movementId}":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
      - $ref: '#/components/parameters/MovementIdParam'
    put:
      tags: [ Movements ]
      operationId: "updateMovementNonSubscribableProducts"
      description: >
        Update an existing billing movement (for non subscribable products). Movements (for non subscribable products) can only be updated
        if they have not been invoiced, that is, if their invoice_id field is empty.
      summary: "Update a single billing movement (for non subscribable products)"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovementNonSubscribableProductsRequestDTO'
            example:
              type: "RECURRING_CHARGE"
              movement_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_with_taxes: 13.02625181
                value_without_taxes: 10.76549736
                tax:
                  type: "IVA"
                  percentage: 21
              external_invoice_id: "123456789"
              external_movement_unique_id: "987654321"
              transaction_type_id: "5432167890"
              description: "February invoice"
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "wrongMovementBody"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "movementNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "updateMovementNonSubscribableProducts"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "updateMovementNonSubscribableProducts"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
    delete:
      deprecated: true
      tags: [ Movements ]
      operationId: "deleteMovementNonSubscribableProducts"
      summary: "Delete a single billing movement (for non subscribable products)"
      description: >
        Delete an existing billing movement (for non subscribable products). Movements (for non subscribable products) can only be deleted if
        they have not been invoiced, that is, if their invoice_id field is empty.
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          description: The request could not be processed because it was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "subscriptionNotFound"
        '401':
          description: The user is not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '403':
          description: The user does not have permission to access that resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "movementNonSubscribableProductsNotFound"
        '500':
          description: The request failed to be processed by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "deleteMovementNonSubscribableProducts"
        '502':
          description: A third party connection is not responding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'
              example:
                error: "deleteMovementNonSubscribableProducts"
        '504':
          description: The request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponseDTO'

  "/orgs/{orgId}/subscription/{subscriptionId}/refund":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
    get:
      tags: [ Refunds ]
      parameters:
        - $ref: '#/components/parameters/DatetimeFromParam'
        - $ref: '#/components/parameters/DatetimeToParam'
      operationId: "getRefundsBySubscription"
      summary: "Get a list of all billing refunds, related to a subscription"
      description: >
        In the context of a given subscription, retrieves a list of all related billing refunds.
      responses:
        '200':
          description: "List of all subscription billing refunds"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RefundResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
      - $ref: '#/components/parameters/MovementIdParam'
    get:
      tags: [ Refunds ]
      operationId: "getRefundsByMovement"
      summary: "Get a list of all billing refunds, related to a billing movement"
      description: >
        In the context of a given billing movement, retrieves a list of all related billing refunds.
      responses:
        '200':
          description: "List of all movement billing refunds"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RefundResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'
    post:
      tags: [ Refunds ]
      operationId: "createRefund"
      summary: "Create a new billing refund"
      description: >
        Create a new billing refund. Refunds can only be created if their related billing movement has been invoiced, that is, if their related
        billing movement invoice_id field is not empty.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequestDTO'
            example:
              refund_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_with_taxes: 13.02625181
                value_without_taxes: 10.76549736
                tax:
                  type: "IVA"
                  percentage: 21
              external_invoice_id: "123456789"
              external_refund_unique_id: "987654321"
              billable: false
              description: "February invoice"
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund/{refundId}":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
      - $ref: '#/components/parameters/MovementIdParam'
      - $ref: '#/components/parameters/RefundIdParam'
    get:
      tags: [ Refunds ]
      operationId: "getRefund"
      summary: "Get a single billing refund"
      description: >
        Retrieves a single billing refund.
      responses:
        '200':
          description: "Retrieve a billing refund"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'
    put:
      tags: [ Refunds ]
      description: >
        Update an existing billing refund. Refunds can only be updated if they have not been invoiced, that is, if their invoice_id field is empty.
      summary: "Update a single billing refund"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequestDTO'
            example:
              refund_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_with_taxes: 13.02625181
                value_without_taxes: 10.76549736
                tax:
                  type: "IVA"
                  percentage: 21
              external_invoice_id: "123456789"
              external_refund_unique_id: "987654321"
              billable: false
              description: "February invoice"
      operationId: "updateRefund"
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'
    delete:
      tags: [ Refunds ]
      operationId: "deleteRefund"
      summary: "Delete a single billing refund"
      description: >
        Delete an existing billing refund. Refunds can only be deleted if they have not been invoiced, that is, if their invoice_id field is empty.
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund-non-subscribable-products":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/SubscriptionIdParam'
      - $ref: '#/components/parameters/MovementIdParam'
    post:
      tags: [ Refunds ]
      operationId: "createRefundNonSubscribableProducts"
      summary: "Create a new billing refund (for non subscribable products)"
      description: >
        Create a new billing refund (for non subscribable products). Refunds (for non subscribable products) can only be created if their
        related billing movement has been invoiced, that is, if their related billing movement invoice_id field is not empty.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundNonSubscribableProductsRequestDTO'
            example:
              refund_datetime: "2022-02-24T13:45:10Z"
              period_start_datetime: "2022-01-31T23:00:00Z"
              period_end_datetime: "2022-02-28T22:59:59.999999999Z"
              amount:
                value_without_taxes: 10.76549736
              external_invoice_id: "123456789"
              external_refund_unique_id: "987654321"
              transaction_type_id: "5432167890"
              description: "February invoice"
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/accounts/{accountId}/invoices":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/DatetimeFromParam'
      - $ref: '#/components/parameters/DatetimeToParam'
    get:
      tags: [ Invoices ]
      operationId: getInvoicesByAccount
      summary: "Get a list of all invoices, related to an account"
      description: >
        In the context of a given account, retrieves a list of all related invoices.
      responses:
        '200':
          description: "List of all account invoices"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicesResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/accounts/{accountId}/invoices/{invoiceId}/movements":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/InvoiceIdParam'
    get:
      tags: [ Invoices ]
      operationId: getInvoiceMovements
      summary: Get a list of all movements related to an invoice
      description: Retrieve a list of all movements related to a specific invoice in an account.
      responses:
        '200':
          description: Retrieve a list of all movements related to an invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceMovementsResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/accounts/{accountId}/invoices/{invoiceId}/public_link":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/InvoiceIdParam'
    get:
      tags: [ Invoices ]
      operationId: getAccountInvoicePublicLink
      summary: Retrieve a public link to an invoice to download the document
      description: Get a public link to the invoice of a given account. The public link allows to download the invoice document.
      responses:
        '200':
          description: Retrieve an account invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePublicLinkResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/accounts/{accountId}/invoices/sales/{invoiceSequence}/public_link":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/InvoiceSequenceParam'
    get:
      tags: [ Invoices ]
      operationId: getSalesAccountInvoicePublicLink
      summary: Retrieve a public link to a sales invoice to download the document
      description: Get a public link to the sales invoice of a given account. The sales invoice document must have been generated before calling this endpoint.
      responses:
        '200':
          description: Retrieve a sales invoice public link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePublicLinkResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/accounts/{accountId}/billing_details":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      tags: [ Invoices ]
      operationId: getAccountBillingDetails
      summary: Retrieve the next billing date
      description: >
        In the context of a given account, retrieves the next billing date.
      responses:
        '200':
          description: "Account next billing date"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBillingDetailsResponseDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '504':
          $ref: '#/components/responses/Timeout'

  "/orgs/{orgId}/location-taxes/{stateId}":
    parameters:
      - $ref: '#/components/parameters/OrgIdParam'
      - $ref: '#/components/parameters/StateIdParam'
    get:
      tags:
        - LocationTax
      operationId: getLocationTaxByStateId
      summary: "Get the location tax of a given state id"
      description: >
        Get the location tax of a given state id. The location tax is the percentage and tax type that applies to a given state.
        State ids are defined by INE
      responses:
        '200':
          description: "Location tax information"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationTaxDTO'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/Timeout'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  x-releaseInfo:
    description: |
      ## Release Notes

      * **1.27.4**
        - Add endpoint to retrieve sales invoice public links.

      * **1.27.3**
        - Float fields changed from float to double to support float64 values.

      * **1.27.1**
        - Add release notes section
        - Documented all validation requirements in endpoint descriptions (subscription active date, external ID uniqueness, transaction type validation, etc.)

  parameters:
    CdrTypeParam:
      in: query
      name: type
      description: Cdr type used as filter
      required: false
      example: "data"
      schema:
        type: string
        enum: [ "data", "sms", "voice" ]
    DatetimeFromParam:
      in: query
      name: fromDate
      description: From datetime used as filter
      required: false
      example: "2021-10-10T22:00:00Z"
      schema:
        type: string
        format: date-time
    DatetimeToParam:
      in: query
      name: toDate
      description: To datetime used as filter
      required: false
      example: "2021-10-20T22:00:00Z"
      schema:
        type: string
        format: date-time
    MovementTypeParam:
      in: query
      name: movementType
      description: Movement type used as filter
      required: false
      example: "RECURRING_CHARGE"
      schema:
        $ref: '#/components/schemas/MovementTypeDTO'
    OperationTypeParam:
      in: query
      name: operationType
      description: Operation type used as filter
      required: false
      example: "DEBIT"
      schema:
        $ref: '#/components/schemas/OperationTypeDTO'
    OrgIdParam:
      in: path
      name: orgId
      description: Executes the request in the context of the given organization
      required: true
      example: "masmovil"
      schema:
        type: string
    AccountIdParam:
      in: path
      name: accountId
      description: Executes the request in the context of the given account
      required: true
      example: "123456789"
      schema:
        type: string
    SubscriptionIdParam:
      in: path
      name: subscriptionId
      description: Executes the request in the context of the given subscription
      required: true
      example: "123456789"
      schema:
        type: string
    AdjustmentIdParam:
      in: path
      name: adjustmentId
      description: Executes the request in the context of the given billing adjustment
      required: true
      example: "eca565cf-8c87-4be5-a189-0a320f5dd1cd"
      schema:
        type: string
    MovementIdParam:
      in: path
      name: movementId
      description: Executes the request in the context of the given billing movement
      required: true
      example: "eca565cf-8c87-4be5-a189-0a320f5dd1cd"
      schema:
        type: string
    RefundIdParam:
      in: path
      name: refundId
      description: Executes the request in the context of the given billing refund
      required: true
      example: "36d64f0a-71c8-466b-be65-2b0e5adeead5"
      schema:
        type: string
    StateIdParam:
      in: path
      name: stateId
      description: Executes the request in the context of the given location (state id)
      required: true
      example: 28
      schema:
        type: integer
        minimum: 1
        maximum: 52
    InvoiceIdParam:
      in: path
      name: invoiceId
      description: Executes the request in the context of the given invoice
      required: true
      example: "MC240000000000"
      schema:
        type: string
    InvoiceSequenceParam:
      in: path
      name: invoiceSequence
      description: Executes the request in the context of the given sales invoice sequence
      required: true
      example: "SALE240000000000"
      schema:
        type: string

  responses:
    NoContent:
      description: Ok with empty body
    Created:
      description: Resource created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericCreatedResponseDTO'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    BadRequest:
      description: The request could not be processed because it was malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    InternalServerError:
      description: The request failed to be processed by the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    Unauthorized:
      description: The user is not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    Forbidden:
      description: The user does not have permission to access that resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    BadGateway:
      description: A third party connection is not responding
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    Timeout:
      description: The request timed out
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'
    UnknownError:
      description: The request failed for an unknown reason
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponseDTO'

  schemas:
    BillingInfoDto:
      type: object
      required:
        - language
        - invoice_cycle_start_day
      properties:
        language:
          description: Default language for the tenant. This follows IETF language tag, which combine sub-tags from other
            standards such as ISO 639, ISO 15924, ISO 3166-1 and UN M.49
          type: string
          example: "es"
        invoice_cycle_start_day:
          description: Day of the month in which the invoice cycle starts
          type: integer
          example: 22
    AccountAdjustmentRequestDTO:
      type: object
      required: [ adjustment_datetime, amount, operation_type, external_adjustment_unique_id, transaction_type_id, description ]
      properties:
        adjustment_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AdjustmentAmountRequestDTO'
        external_adjustment_unique_id:
          type: string
          example: "987654321"
        transaction_type_id:
          type: string
          example: "5432167890"
        description:
          type: string
          example: "February invoice"
    AccountAdjustmentResponseDTO:
      type: object
      required: [ id, adjustment_datetime, period_start_datetime, period_end_datetime, amount, operation_type, external_adjustment_unique_id, transaction_type_id, invoice_id, invoice_cycle_date, description ]
      properties:
        id:
          type: string
          example: "eca565cf-8c87-4be5-a189-0a320f5dd1cd"
        adjustment_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AmountResponseDTO'
        operation_type:
          $ref: '#/components/schemas/OperationTypeDTO'
        external_adjustment_unique_id:
          type: string
          example: "987654321"
        transaction_type_id:
          type: string
          example: "5432167890"
        invoice_id:
          type: string
          example: "987654321"
        invoice_cycle_date:
          type: string
          format: date-time
          description: "If the invoice_id field is empty, this field indicates the expected invoice cycle date of the movement. On the other hand, if the invoice_id field is already filled, this field indicates the current invoice cycle date of the movement."
          example: "2022-02-28T23:00:00Z"
        description:
          type: string
          example: "February invoice"
    CdrResponseDTO:
      type: object
      required: [ id, originNumber, destinationNumber, initialDate, usage, unit, costWithoutTaxes, taxPercentage, ratingCaseCategory, ratingCaseDescription, debitCase, debitCatalogId, debitCustomerId ]
      properties:
        id:
          type: string
          description: CDR id
          example: "b0b007d221b62fb6443b5be9f8ef66222c2f2798"
        originNumber:
          type: string
          description: CDR origin number
          example: "666554433"
        destinationNumber:
          type: string
          description: CDR destination number (empty for "data" cdr type)
          example: "933008151"
        initialDate:
          type: string
          format: date-time
          description: CDR date (start date of the call for "voice" cdr type)
          example: "2020-09-05T15:14:01Z"
        usage:
          type: integer
          format: int64
          description: Amount of usage of the CDR
          example: 150
        unit:
          type: string
          enum: [ "byte", "sms", "second" ]
          description: Unit of the CDR usage
          example: "second"
        costWithoutTaxes:
          type: number
          format: double
          description: Cost of the CDR without taxes
          example: 0
        taxPercentage:
          type: number
          format: double
          description: Tax percentage that should be applied to CDR cost
          example: 21
        ratingCaseCategory:
          type: string
          enum: [ "VOICE_NATIONAL", "SMS_NATIONAL", "DATA_NATIONAL", "VOICE_INTERNATIONAL", "SMS_INTERNATIONAL", "VOICE_ROAMING_UE", "SMS_ROAMING_UE", "DATA_ROAMING_UE", "VOICE_ROAMING", "SMS_ROAMING", "DATA_ROAMING", "VOICE_SPECIAL", "SMS_SPECIAL", "VOICE_PREMIUM", "SMS_PREMIUM", "UNKNOWN" ]
          description: Rating category of the CDR. In Prepaid is empty.
          example: "VOICE_NATIONAL"
        ratingCaseDescription:
          type: string
          description: Description of the rating case. Empty for prepaid.
          example: "NUMERACIÓN ESPECIAL"
        debitCase:
          type: string
          enum: [ "bonus", "rating_plan" ]
          description: Debit category of the CDR (if it was debited from a bonus or from a rating plan). In Prepaid is rating_plan.
          example: "bonus"
        debitCatalogId:
          type: string
          description: Depending on 'debitCase' field, catalog rating plan id or catalog bonus id (MMId) used to debit the CDR
          example: "4321"
        debitCustomerId:
          type: string
          description: Customer bonus id (PackageSubscriptionServiceId) used to debit the CDR (empty if it was debited from rating plan). In Prepaid is empty.
          example: "46789123"
        additionalDetails:
          $ref: '#/components/schemas/AdditionalDetailsDTO'
    SubscriptionResponseDTO:
      type: object
      required: [ id, msisdn, tenant, billingType, monetary, bonuses ]
      properties:
        id:
          type: string
          description: Subscription id
          example: "123456789"
        msisdn:
          type: string
          description: Subscription msisdn
          example: "666554433"
        tenant:
          type: string
          description: Subscription organization
          example: "masmovil"
        billingType:
          type: integer
          format: int64
          enum: [ 1, 2, 4 ]
          description: >
            Subscription type id (prepaid: 1, postpaid: 2, landline: 4)
          example: 2
        monetary:
          type: array
          description: List of subscription monetary balances
          items:
            $ref: '#/components/schemas/MonetaryBalanceResponseDTO'
        bonuses:
          $ref: '#/components/schemas/BonusBalancesByTypeResponseDTO'
    CdrsByTypeResponseDTO:
      type: object
      description: >
        Subscription cdrs types: "data", "sms", "voice"
      properties:
        data:
          type: array
          description: List of subscription data cdrs
          items:
            $ref: '#/components/schemas/CdrResponseDTO'
        sms:
          type: array
          description: List of subscription sms cdrs
          items:
            $ref: '#/components/schemas/CdrResponseDTO'
        voice:
          type: array
          description: List of subscription voice cdrs
          items:
            $ref: '#/components/schemas/CdrResponseDTO'
    MonetaryBalanceResponseDTO:
      type: object
      required: [ id, currentValue, currentValueWithTaxes, unit, activationDatetime, expirationDatetime, counters ]
      properties:
        id:
          type: string
          description: Monetary balance id
          example: "666554433-123456789-MONETARY_DEFAULT-2020-09-01T00:00:00+02:00"
        currentValue:
          type: number
          format: double
          description: Current value of the monetary balance
          example: -4.7
        currentValueWithTaxes:
          type: number
          format: double
          description: Current value with taxes of the monetary balance. In Prepaid is 0.
          example: -5.69
        unit:
          type: string
          enum: [ EUR ]
          description: Unit of the monetary balance value
          example: "EUR"
        activationDatetime:
          type: string
          format: date-time
          description: Start date of the monetary balance period (UTC). Null date = 0001-01-01T00:00:00Z
          example: "2020-08-31T22:00:00Z"
        expirationDatetime:
          type: string
          format: date-time
          description: End date of the monetary balance period (UTC). Null date = 0001-01-01T00:00:00Z
          example: "2021-09-30T21:59:59.999999999Z"
        counters:
          type: array
          description: List of available counters for that balance
          items:
            $ref: '#/components/schemas/MonetaryBalanceCountersResponseDTO'
    MonetaryBalanceCountersResponseDTO:
      type: object
      required: [ type, value ]
      properties:
        type:
          type: string
          description: counter type
          example: internationalVoice
        value:
          type: number
          format: double
          description: current value for that counter in the specified balance
          example: -12.3
    BonusBalancesByTypeResponseDTO:
      type: object
      required: [ data, sms, voice ]
      properties:
        data:
          type: array
          description: List of subscription data bonus balances
          items:
            $ref: '#/components/schemas/BonusBalanceResponseDTO'
        sms:
          type: array
          description: List of subscription sms bonus balances
          items:
            $ref: '#/components/schemas/BonusBalanceResponseDTO'
        voice:
          type: array
          description: List of subscription voice bonus balances
          items:
            $ref: '#/components/schemas/BonusBalanceResponseDTO'
    BonusBalanceResponseDTO:
      type: object
      required: [ id, initialValue, currentValue, unit, activationDatetime, expirationDatetime, renovationsCount, catalogBonusId, customerBonusId, isShared ]
      properties:
        id:
          type: string
          description: Bonus balance id
          example: "666554433-123456789-BONUS_TEMPLATE-100-46789123-2020-09-01T00:00:00+02:00"
        initialValue:
          type: number
          format: double
          description: Initial value of the bonus balance
          example: 6000
        currentValue:
          type: number
          format: double
          description: Current value of the bonus balance
          example: 6000
        unit:
          type: string
          enum: [ "byte", "sms", "second" ]
          description: Unit of the bonus balance value
          example: "second"
        activationDatetime:
          type: string
          format: date-time
          description: Start date of the bonus balance period (UTC)
          example: "2020-08-31T22:00:00Z"
        expirationDatetime:
          type: string
          format: date-time
          description: End date of the bonus balance period (UTC)
          example: "2021-09-30T21:59:59.999999999Z"
        renovationsCount:
          type: integer
          description: Number of renovations of the bonus
          example: 3
        catalogBonusId:
          type: string
          description: Catalog bonus id of the bonus (MMId)
          example: "4321"
        customerBonusId:
          type: string
          description: Customer bonus id of the bonus (PackageSubscriptionServiceId)
          example: "46789123"
        isShared:
          type: boolean
          description: Indicates if the bonus balance is shared or not
          example: false
    AdditionalDetailsDTO:
      type: object
      description: Additional details of the consumption
      properties:
        smsPremiumInfo:
          $ref: '#/components/schemas/SmsPremiumInfoDTO'
    SmsPremiumInfoDTO:
      type: object
      properties:
        description:
          type: string
          description: Description of the premium SMS
          example: "A very short description"
        supplierName:
          type: string
          description: Name of the supplier
          example: "PREMIUM SERVICE S.L."
    AdjustmentRequestDTO:
      type: object
      required: [ adjustment_datetime, amount, external_adjustment_unique_id, transaction_type_id, description ]
      properties:
        adjustment_datetime:
          type: string
          format: date-time
          description: "Date and time when the adjustment occurs. The subscription must be active at this date/time. Cannot be empty."
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          description: "Start of the billing period this adjustment applies to. If provided, period_end_datetime must also be provided. The adjustment_datetime must fall within the period (inclusive)."
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          description: "End of the billing period this adjustment applies to. If provided, period_start_datetime must also be provided. The adjustment_datetime must fall within the period (inclusive)."
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AdjustmentAmountRequestDTO'
        external_adjustment_unique_id:
          type: string
          description: "Unique identifier for this adjustment from the external system. Must be unique within the subscription. Cannot be empty."
          example: "987654321"
        transaction_type_id:
          type: string
          description: "ID of the transaction type from the catalogue. Must be valid for the subscription's commercial product. Cannot be empty."
          example: "5432167890"
        description:
          type: string
          description: "Human-readable description of the adjustment. Cannot be empty."
          example: "February invoice"
    MovementResponseDTO:
      type: object
      required: [ id, type, movement_datetime, period_start_datetime, period_end_datetime, amount, invoice_id, external_invoice_id, invoice_cycle_date, external_movement_unique_id, billable, transaction_type_id, operation_type, description ]
      properties:
        id:
          type: string
          example: "8da2b117-ef72-413d-98ce-36d1eb544e44"
        type:
          $ref: '#/components/schemas/MovementTypeDTO'
        movement_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AmountResponseDTO'
        invoice_id:
          type: string
          example: "987654321"
        external_invoice_id:
          type: string
          example: "123456789"
        invoice_cycle_date:
          type: string
          format: date-time
          description: "If the invoice_id field is empty, this field indicates the expected invoice cycle date of the movement. On the other hand, if the invoice_id field is already filled, this field indicates the current invoice cycle date of the movement."
          example: "2022-02-28T23:00:00Z"
        external_movement_unique_id:
          type: string
          example: "987654321"
        billable:
          type: boolean
          example: false
        transaction_type_id:
          type: string
          example: "100"
        operation_type:
          $ref: '#/components/schemas/OperationTypeDTO'
        description:
          type: string
          example: "February invoice"
    MovementRequestDTO:
      type: object
      required: [ type, movement_datetime, amount, external_movement_unique_id, billable, description ]
      properties:
        type:
          $ref: '#/components/schemas/MovementTypeDTO'
        movement_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AmountRequestDTO'
        external_invoice_id:
          type: string
          example: "123456789"
        external_movement_unique_id:
          type: string
          example: "987654321"
        billable:
          type: boolean
          example: false
        description:
          type: string
          example: "February invoice"
    MovementNonSubscribableProductsRequestDTO:
      type: object
      required: [ type, movement_datetime, amount, transaction_type_id, external_movement_unique_id, description ]
      properties:
        type:
          $ref: '#/components/schemas/MovementTypeDTO'
        movement_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AmountRequestDTO'
        external_invoice_id:
          type: string
          example: "123456789"
        external_movement_unique_id:
          type: string
          example: "987654321"
        transaction_type_id:
          type: string
          example: "5432167890"
        description:
          type: string
          example: "February invoice"
    RefundResponseDTO:
      type: object
      required: [ id, refund_datetime, period_start_datetime, period_end_datetime, amount, invoice_id, external_invoice_id, external_refund_unique_id, billable, description ]
      properties:
        id:
          type: string
          example: "36d64f0a-71c8-466b-be65-2b0e5adeead5"
        refund_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AmountResponseDTO'
        invoice_id:
          type: string
          example: "987654321"
        external_invoice_id:
          type: string
          example: "123456789"
        external_refund_unique_id:
          type: string
          example: "987654321"
        billable:
          type: boolean
          example: false
        description:
          type: string
          example: "February invoice"
    RefundRequestDTO:
      type: object
      required: [ refund_datetime, amount, external_refund_unique_id, billable, description ]
      properties:
        refund_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/AmountRequestDTO'
        external_invoice_id:
          type: string
          example: "123456789"
        external_refund_unique_id:
          type: string
          example: "987654321"
        billable:
          type: boolean
          example: false
        description:
          type: string
          example: "February invoice"
    RefundNonSubscribableProductsRequestDTO:
      type: object
      required: [ refund_datetime, amount, transaction_type_id, description ] ## TODO include external_refund_unique_id as required
      properties:
        refund_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59.999999999Z"
        amount:
          $ref: '#/components/schemas/BillableAmountRequestDTO'
        external_invoice_id:
          type: string
          example: "123456789"
        external_refund_unique_id:
          type: string
          example: "987654321"
        transaction_type_id:
          type: string
          example: "5432167890"
        description:
          type: string
          example: "February invoice"
    AmountResponseDTO:
      type: object
      required: [ value_with_taxes, value_without_taxes, tax ]
      description: Numeric value with a maximum precision of 8 decimal places.
      properties:
        value_with_taxes:
          type: number
          format: double
          minimum: 0
          example: 13.02625181
        value_without_taxes:
          type: number
          format: double
          minimum: 0
          example: 10.76549736
        tax:
          $ref: '#/components/schemas/TaxDTO'
    AmountRequestDTO:
      type: object
      description: Numeric value with a maximum precision of 8 decimal places.
      properties:
        value_with_taxes:
          type: number
          format: double
          minimum: 0
          example: 13.02625181
        value_without_taxes:
          type: number
          format: double
          minimum: 0
          example: 10.76549736
        tax:
          $ref: '#/components/schemas/TaxDTO'
    AdjustmentAmountRequestDTO:
      type: object
      description: "Amount of an adjustment. Exactly one of value_without_taxes or value_with_taxes must be provided, but not both. The value must be greater than 0."
      oneOf:
        - required: [ value_without_taxes ]
        - required: [ value_with_taxes ]
      properties:
        value_without_taxes:
          type: number
          format: double
          minimum: 0
          example: 10.76549736
          description: "Amount without taxes. Must be greater than 0. Provide either this field OR value_with_taxes, but not both."
        value_with_taxes:
          type: number
          format: double
          minimum: 0
          example: 13.02625181
          description: "Amount with taxes. Must be greater than 0. Provide either this field OR value_without_taxes, but not both."
    BillableAmountRequestDTO:
      type: object
      properties:
        value_without_taxes:
          type: number
          format: double
          minimum: 0
          example: 10.76549736
    InvoicesResponseDTO:
      type: object
      required: [ invoices ]
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceResponseDTO'
    InvoiceResponseDTO:
      type: object
      required: [ invoice_id, issue_date, due_date, location_tax_type, invoice_amounts ]
      properties:
        invoice_id:
          type: string
          example: "OS220000000001"
        issue_date:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
          description: "Emission date of invoice in RFC3339 format"
        due_date:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
          description: "Date of charge in RFC3339 format"
        location_tax_type:
          $ref: '#/components/schemas/LocationTaxTypeDTO'
        invoice_amounts:
          $ref: '#/components/schemas/InvoiceAmountsResponseDTO'
    InvoiceMovementsResponseDTO:
      type: object
      required: [ account_movements, subscription_movements ]
      properties:
        account_movements:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceMovementDTO'
        subscription_movements:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionMovementsResponseDTO'
    InvoiceAmountsResponseDTO:
      type: object
      required: [ tax_base, non_tax_base, tax_amount, total_amount_in_invoice, total_amount_out_of_invoice, total_amount ]
      properties:
        tax_base:
          type: number
          format: double
          minimum: 0
          example: 10.45
          description: "Sum of amounts without taxes of all taxed concepts. Includes concepts with generic and exempted taxes."
        non_tax_base:
          type: number
          format: double
          minimum: 0
          example: 5.15
          description: "Sum of amounts without taxes of all non-taxed concepts"
        tax_amount:
          type: number
          format: double
          minimum: 0
          example: 2.64
          description: "Sum of all tax amounts of all concepts (GENERIC + EXEMPTED)"
        total_amount_in_invoice:
          type: number
          format: double
          minimum: 0
          example: 18.24
          description: "Sum of all amounts with taxes of all taxed and non-taxed concepts (GENERIC + EXEMPTED + NOT_TAXED)"
        total_amount_out_of_invoice:
          type: number
          format: double
          minimum: 0
          example: 4.57
          description: "Sum of all amounts with taxes of all concepts out of invoice. Taxes do not apply to these concepts."
        total_amount:
          type: number
          format: double
          minimum: 0
          example: 22.81
          description: "Sum of total amounts in and out of invoice, including taxes"
    InvoicePublicLinkResponseDTO:
      type: object
      required: [ public_link ]
      properties:
        public_link:
          type: string
          example: "https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d"
    AccountBillingDetailsResponseDTO:
      type: object
      required: [ billing_status ]
      properties:
        next_billing_date:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
          description: "Next billing date in RFC3339 format"
        billing_status:
          type: string
          enum:
            - ACTIVATED
            - DEACTIVATED
          example: "ACTIVATED"
          description: "Billing status of the account."
    TaxDTO:
      type: object
      required: [ type, percentage ]
      properties:
        type:
          type: string
          enum:
            - EXEMPTED
            - IGIC
            - IPSI_CEUTA
            - IPSI_MELILLA
            - IVA
            - NOT_APPLY
            - NOT_TAXED
          example: "IVA"
        percentage:
          type: number
          format: double
          minimum: 0
          example: 21
    LocationTaxDTO:
      type: object
      required: [ type, percentage ]
      properties:
        type:
          $ref: '#/components/schemas/LocationTaxTypeDTO'
        percentage:
          type: number
          format: double
          minimum: 0
          example: 21
    LocationTaxTypeDTO:
      type: string
      enum:
        - IVA
        - IGIC
        - IPSI_CEUTA
        - IPSI_MELILLA
      example: "IVA"
    MovementTypeDTO:
      type: string
      enum:
        - ADJUSTMENT
        - DISCOUNT
        - INSTALLATION_FEE
        - ONE_TIME_FEE
        - RECURRING_CHARGE
        - SUSPENSION_SERVICE_FEE
        - UNRETURNED_EQUIPMENT_FEE
      example: "RECURRING_CHARGE"
    OperationTypeDTO:
      type: string
      enum:
        - CREDIT
        - DEBIT
      example: "DEBIT"
    InvoiceMovementDTO:
      type: object
      required: [ id, account_id, amount, tax, movement_datetime, period_start_datetime, period_end_datetime, transaction_type_id, description ]
      properties:
        id:
          type: string
          example: "uuid-1234-5678-90ab-cdef12345678"
        account_id:
          type: string
          example: "123456789"
        amount:
          $ref: '#/components/schemas/AmountResponseDTO'
        movement_datetime:
          type: string
          format: date-time
          example: "2022-02-24T13:45:10Z"
        period_start_datetime:
          type: string
          format: date-time
          example: "2022-01-31T23:00:00Z"
        period_end_datetime:
          type: string
          format: date-time
          example: "2022-02-28T22:59:59Z"
        transaction_type_id:
          type: string
          example: "5432167890"
        description:
          type: string
          example: "February invoice"
    SubscriptionMovementsResponseDTO:
      type: object
      required: [ subscription_id, movements ]
      properties:
        subscription_id:
          type: string
          example: "123456789"
        movements:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceMovementDTO'
    GenericResponseDTO:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        trace_id:
          type: string
    GenericCreatedResponseDTO:
      type: object
      properties:
        id:
          type: string
          example: "8da2b117-ef72-413d-98ce-36d1eb544e44"
