openapi: 3.1.0
info:
  title: Tidely Public API
  version: 2.0.0
  description: >
    # Introduction


    Welcome to the Tidely Public API v2. This API enables customers to integrate
    with Tidely's

    financial planning and cash flow management platform.


    ## Key Features


    - **Financial Planning**: Create and manage financial plans with flexible
    periods (daily, weekly, monthly)

    - **Invoice Management**: Import and sync invoices from external systems

    - **Categories**: Access and organize financial categories

    - **Scenarios**: Work with multiple financial scenarios for planning


    ## Authentication


    All API requests require authentication using an API key sent in the
    `X-Authorization` header.

    You can create and manage your API tokens in the Tidely application under
    Settings > API Keys

    (e.g., https://app.sam.tidely.com/settings/openapi for staging environment).


    ## Support


    For technical support, integration questions, or to report issues:


    - **Email**: [support@tidely.com](mailto:support@tidely.com)

    - **Website**: [www.tidely.com/kontakt](https://www.tidely.com/kontakt)
servers:
  - url: https://api.tidely.com/public/v2
    description: Production server
  - url: https://api.sam.tidely.com/public/v2
    description: Staging server
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: |
      Verify your API credentials and check authentication status.
      All other endpoints require a valid API key in the X-Authorization header.
  - name: Companies
    description: |
      View companies.
  - name: Categories
    description: >
      Create, retrieve, update, and delete financial categories for organizing
      transactions and plans.

      Categories are hierarchical and classified by type (income/expense,
      operational/investment/financing).
  - name: Plans
    description: >
      Create, update, and delete financial plans for cash flow forecasting.

      Plans can be created for different periods (daily, weekly, monthly) and
      scenarios.

      Supports both single and bulk plan creation.
  - name: Invoices
    description: |
      Import invoices from external systems into Tidely.
      Supports sales invoices, purchase invoices, and credit notes.
      Automatically categorizes and integrates with cash flow planning.
  - name: Scenarios
    description: >
      Access financial planning scenarios for what-if analysis.

      Each account has a base scenario and can create additional scenarios for
      comparison.
  - name: Bank Accounts
    description: |
      View and manage your bank accounts.
  - name: Bank Account Transactions
    description: |
      View and manage bank account transactions.
  - name: Cashflow
    description: >
      Retrieve the aggregated cashflow per period (month, week or day) for a
      scenario,

      including opening and closing balances, sales and purchases totals,
      amounts per

      category, and per-period overdraft and liquidity information.
paths:
  /plans:
    post:
      tags:
        - Plans
      summary: Create plan
      description: Creates a new financial plan for a specific category and scenario
      operationId: createPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanCreateDto'
            examples:
              monthlyPlan:
                summary: Monthly plan example
                value:
                  categoryId: 123
                  amount: 5000
                  period: MONTHLY
                  date: '2024-10-01'
                  type: ONE_TIME
                  name: October Revenue Plan
                  scenarioId: 1
                  replaceCurrentValuesForThePeriod: false
      responses:
        '201':
          description: Plan created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanCreateResponse'
        '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'
    delete:
      tags:
        - Plans
      summary: Delete plans
      description: Deletes all plans for a specific category and scenario combination
      operationId: deletePlans
      parameters:
        - name: categoryId
          in: query
          required: true
          description: The ID of the category
          schema:
            type: integer
            format: int64
          example: 123
        - name: scenarioId
          in: query
          required: true
          description: The ID of the scenario
          schema:
            type: integer
            format: int64
          example: 1
      responses:
        '200':
          description: Plans deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanDeleteResponse'
        '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'
  /plans/bulk:
    post:
      tags:
        - Plans
      summary: Create multiple plans
      description: Creates multiple financial plans in a single request
      operationId: createPlans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PlanCreateDto'
            examples:
              multiplePlans:
                summary: Multiple plans example
                value:
                  - categoryId: 123
                    amount: 5000
                    period: MONTHLY
                    date: '2024-10-01'
                    type: ONE_TIME
                    name: October Revenue Plan
                  - categoryId: 124
                    amount: -2000
                    period: MONTHLY
                    date: '2024-10-01'
                    type: ONE_TIME
                    name: October Expense Plan
      responses:
        '201':
          description: Plans created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPlanCreateResponse'
        '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'
  /invoices:
    get:
      tags:
        - Invoices
      summary: Get invoices
      description: Get all invoices
      operationId: getInvoices
      parameters:
        - name: invoiceTypeFilter
          in: query
          description: Type of invoices to retrieve
          required: true
          schema:
            $ref: '#/components/schemas/InvoiceTypeFilter'
        - name: externalId
          in: query
          description: >
            Filter invoices by external identifier. Repeat the parameter to
            filter by multiple external IDs (e.g.
            `?externalId=INV-001&externalId=INV-002`). Limited to 100 values per
            request to avoid exceeding URL length limits.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
              maxLength: 255
            maxItems: 100
        - name: page
          in: query
          description: Page number (0-based)
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: pageSize
          in: query
          description: Number of invoices per page
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Invoices retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicesResponse'
              examples:
                invoices:
                  summary: Invoices list example
                  value:
                    success: true
                    message: Invoices retrieved successfully
                    number: 0
                    size: 50
                    totalElements: 2
                    totalPages: 1
                    data:
                      - id: 1
                        externalId: INV-2024-001
                        invoiceDate: '2024-10-15'
                        dueDate: '2024-11-15'
                        invoiceNumber: 2024-001
                        contactName: ACME Corp
                        invoiceType: SALES_INVOICE
                        totalGrossAmount: 11900
                        openAmount: 11900
                        invoiceStatus: OPEN
                        note: sale invoice
                        categoryId: 1
                      - id: 2
                        externalId: INV-2024-002
                        invoiceDate: '2024-10-20'
                        dueDate: '2024-11-20'
                        invoiceNumber: 2024-002
                        contactName: Beta GmbH
                        invoiceType: SALES_INVOICE
                        totalGrossAmount: 5950
                        openAmount: 5950
                        invoiceStatus: OPEN
                        note: invoice
                        categoryId: 1
        '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'
    post:
      tags:
        - Invoices
      summary: Create invoice
      description: Creates a new invoice
      operationId: createInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreateRequest'
            examples:
              salesInvoice:
                summary: Sales invoice example
                value:
                  externalId: INV-2024-001
                  invoiceDate: '2024-10-15'
                  dueDate: '2024-11-15'
                  invoiceNumber: 2024-001
                  contactName: ACME Corp
                  invoiceType: SALES_INVOICE
                  totalGrossAmount: 11900
                  openAmount: 11900
                  invoiceStatus: OPEN
      responses:
        '200':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
        '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'
  /invoices/bulk:
    post:
      tags:
        - Invoices
      summary: Create multiple invoices
      description: >
        Creates multiple invoices in a single request. A maximum of **1000
        invoices** per request is allowed. Requests exceeding this limit will be
        rejected with a `400 Bad Request` response.
      operationId: createInvoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceBulkCreateRequest'
            examples:
              multipleInvoices:
                summary: Multiple invoices example
                value:
                  invoices:
                    - invoiceNumber: 2024-001
                      externalId: '1'
                      invoiceDate: '2024-10-15'
                      dueDate: '2024-11-15'
                      contactName: ACME Corp
                      invoiceType: SALES_INVOICE
                      totalGrossAmount: 11900
                      openAmount: 11900
                      invoiceStatus: OPEN
                      note: simple note
                      categoryId: null
                    - invoiceNumber: 2024-002
                      externalId: '1'
                      invoiceDate: '2024-10-20'
                      dueDate: '2024-11-20'
                      contactName: Beta GmbH
                      invoiceType: PURCHASE_INVOICE
                      totalGrossAmount: 5950
                      openAmount: 5950
                      invoiceStatus: OPEN
                      note: simple note
                      categoryId: 1
      responses:
        '200':
          description: Invoices created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInvoiceCreateResponse'
        '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'
  /invoices/{id}:
    get:
      tags:
        - Invoices
      summary: Get invoice
      description: Get invoice by id
      operationId: getInvoice
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the invoice
          schema:
            type: integer
            format: int64
        - name: invoiceTypeFilter
          in: query
          description: Type of invoices to retrieve
          required: true
          schema:
            $ref: '#/components/schemas/InvoiceTypeFilter'
      responses:
        '200':
          description: Invoice retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
        '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'
    patch:
      tags:
        - Invoices
      summary: Update invoice
      description: >
        Updates an invoice.

        Invoices that originate from an ERP integration are **read-only** —
        update and delete operations are not allowed.
      operationId: updateInvoice
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the invoice
          schema:
            type: integer
            format: int64
        - name: invoiceTypeFilter
          in: query
          description: Type of invoices to retrieve
          required: true
          schema:
            $ref: '#/components/schemas/InvoiceTypeFilter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceUpdateRequest'
            examples:
              invoiceUpdate:
                summary: Invoice update example
                value:
                  invoiceDate: '2024-10-15'
                  dueDate: '2024-11-15'
                  invoiceNumber: 2024-001
                  contactName: ACME Corp
                  totalGrossAmount: 11900
                  openAmount: 11900
                  invoiceStatus: PAID
                  currency: EUR
                  paidDate: '2024-11-10'
      responses:
        '200':
          description: Invoice updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
        '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'
    delete:
      tags:
        - Invoices
      summary: Delete invoice
      description: >
        Deletes an invoice by id.

        Invoices that originate from an ERP integration are **read-only** —
        update and delete operations are not allowed.
      operationId: deleteInvoice
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the invoice
          schema:
            type: integer
            format: int64
        - name: invoiceTypeFilter
          in: query
          description: Type of invoices to retrieve
          required: true
          schema:
            $ref: '#/components/schemas/InvoiceTypeFilter'
      responses:
        '200':
          description: Invoice deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDeleteResponse'
        '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'
  /scenarios:
    get:
      tags:
        - Scenarios
      summary: Get scenarios
      description: Retrieves all scenarios for the authenticated user
      operationId: getScenarios
      responses:
        '200':
          description: Scenarios retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScenarioOpenApiDto'
              examples:
                scenarios:
                  summary: Scenarios list example
                  value:
                    - id: 1
                      name: Base Case
                      isBaseCase: true
                    - id: 2
                      name: Optimistic Scenario
                      isBaseCase: false
        '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'
  /scenarios/{scenarioId}:
    get:
      tags:
        - Scenarios
      summary: Get scenario
      description: Retrieves a single scenario by its ID
      operationId: getScenario
      parameters:
        - name: scenarioId
          in: path
          required: true
          description: The ID of the scenario to retrieve
          schema:
            type: integer
            format: int64
          example: 1
      responses:
        '200':
          description: Scenario retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioOpenApiDto'
        '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'
  /categories:
    get:
      tags:
        - Categories
      summary: Get categories
      description: Retrieves all categories for the authenticated user
      operationId: getCategories
      responses:
        '200':
          description: Categories retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
              examples:
                categories:
                  summary: Categories list example
                  value:
                    - id: 123
                      name: E-Commerce Revenue
                      type: INCOME_OPERATIONAL
                      parentId: 100
                      enabledForPlannedTransactions: true
        '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'
    post:
      tags:
        - Categories
      summary: Create category
      description: >-
        Creates a new financial category, type is ignored if parentId is
        specified
      operationId: createCategory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryCreateRequest'
            examples:
              newCategory:
                summary: New category example
                value:
                  name: E-Commerce Revenue
                  type: INCOME_OPERATIONAL
                  parentId: 100
      responses:
        '200':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                newCategory:
                  summary: Created category example
                  value:
                    id: 123
                    name: E-Commerce Revenue
                    type: INCOME_OPERATIONAL
                    parentId: 100
                    enabledForPlannedTransactions: true
        '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'
  /categories/{id}:
    get:
      tags:
        - Categories
      summary: Get category
      description: Retrieves a single category by ID
      operationId: getCategory
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the category
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Category retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                category:
                  summary: Category example
                  value:
                    id: 123
                    name: E-Commerce Revenue
                    type: INCOME_OPERATIONAL
                    parentId: 100
                    enabledForPlannedTransactions: true
        '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'
    patch:
      tags:
        - Categories
      summary: Update category
      description: Updates an existing category
      operationId: updateCategory
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the category
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryUpdateRequest'
            examples:
              updateCategory:
                summary: Update category example
                value:
                  name: E-Commerce Revenue Updated
                  type: INCOME_OPERATIONAL
      responses:
        '200':
          description: Category updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                updatedCategory:
                  summary: Updated category example
                  value:
                    id: 123
                    name: E-Commerce Revenue Updated
                    type: INCOME_OPERATIONAL
                    parentId: 100
                    enabledForPlannedTransactions: true
        '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'
    delete:
      tags:
        - Categories
      summary: Delete category
      description: Deletes a category by ID
      operationId: deleteCategory
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the category
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Category deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryDeleteResponse'
        '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'
  /authentication/verify-auth:
    get:
      tags:
        - Authentication
      summary: Verify token
      description: Verifies that the authentication token is valid
      operationId: verifyAuth
      responses:
        '200':
          description: Token is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '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'
  /bank-accounts:
    get:
      tags:
        - Bank Accounts
      summary: Get bank accounts
      description: Get all bank accounts
      operationId: getBankAccounts
      responses:
        '200':
          description: Bank accounts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountsResponse'
              examples:
                bankAccountList:
                  summary: Bank accounts list example
                  value:
                    success: true
                    message: Bank accounts retrieved successfully
                    data:
                      - id: 1
                        externalId: '123'
                        iban: DE89370400440532113000
                        accountNumber: '1234567891'
                        accountCurrency: EUR
                        accountName: First Bank Account
                        bankName: Deutsche Bank
                        accountType: CHECKING
                        provider: ONLINE
                        balanceReference: 2400
                        balanceDate: '2025-03-10'
                      - id: 2
                        externalId: '124'
                        iban: DE89370400440532214000
                        accountNumber: '1234567892'
                        accountCurrency: EUR
                        accountName: Second Bank Account
                        bankName: Deutsche Bank
                        accountType: CHECKING
                        provider: OFFLINE
                        balanceReference: 2500
                        balanceDate: '2025-03-10'
        '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'
    post:
      tags:
        - Bank Accounts
      summary: Create bank account
      description: Creates a new bank account
      operationId: createBankAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreateRequest'
            examples:
              mainBusinessAccount:
                summary: Main Business account example
                value:
                  externalId: '123'
                  iban: DE89370400440532013000
                  accountNumber: '1234567890'
                  accountCurrency: EUR
                  accountName: Main Business Account
                  bankName: Deutsche Bank
                  companyId: 1
                  accountType: CHECKING
                  balanceReference: 2100
                  balanceDate: '2025-03-10'
      responses:
        '200':
          description: Bank account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountResponse'
        '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'
  /bank-accounts/{id}:
    get:
      tags:
        - Bank Accounts
      summary: Get bank account
      description: Get bank account by id
      operationId: getBankAccount
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the bank account
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Bank account retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountResponse'
        '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'
    patch:
      tags:
        - Bank Accounts
      summary: Update bank account
      description: Updates a bank account
      operationId: updateBankAccount
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the bank account
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountUpdateRequest'
            examples:
              testBankAccount:
                summary: Test bank account example
                value:
                  externalId: '123'
                  iban: DE89370400440532213000
                  accountNumber: '1234567890'
                  accountCurrency: EUR
                  accountName: Test bank account
                  bankName: Deutsche Bank
                  accountType: CHECKING
                  balanceDate: '2026-03-11'
                  companyId: 1
                  balanceReference: 2400
      responses:
        '200':
          description: Bank account updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountResponse'
        '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'
    delete:
      tags:
        - Bank Accounts
      summary: Delete bank accounts
      description: Deletes bank account by id
      operationId: deleteBankAccount
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the bank account
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Bank account deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountDeleteResponse'
        '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'
  /bank-accounts/{id}/balances:
    get:
      tags:
        - Bank Accounts
      summary: Get bank account balances
      description: Get all balances for a bank account
      operationId: getBankAccountBalances
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the bank account
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          description: Page number (0-based)
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: pageSize
          in: query
          description: Number of balances per page
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Bank accounts balances retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountBalancesResponse'
              examples:
                scenarios:
                  summary: Bank account balances list example
                  value:
                    success: true
                    message: Bank account balances retrieved successfully
                    number: 0
                    size: 20
                    totalElements: 125
                    totalPages: 8
                    data:
                      - date: '2024-10-15'
                        amount: 2500
                      - date: '2024-10-16'
                        amount: 2700
        '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'
  /bank-account-transactions:
    get:
      tags:
        - Bank Account Transactions
      summary: Get bank account transactions
      description: Get all bank account transactions
      operationId: getBankAccountTransactions
      parameters:
        - name: bankAccountId
          in: query
          description: ID of the bank account to filter transactions
          required: true
          schema:
            type: integer
            format: int64
        - name: page
          in: query
          description: Page number (0-based)
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: pageSize
          in: query
          description: Number of transactions per page
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Bank account transactions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountTransactionsResponse'
              examples:
                transactions:
                  summary: Bank account transactions list example
                  value:
                    success: true
                    message: Transactions retrieved successfully
                    number: 0
                    size: 20
                    totalElements: 125
                    totalPages: 8
                    data:
                      - id: 1001
                        externalId: '1234'
                        bankAccountId: 10
                        categoryId: 5
                        bookingDate: '2024-10-15'
                        amount: -120.5
                        counterpartName: Amazon EU
                        counterpartAccountNumber: '9876543210'
                        counterpartIban: DE44500105175407324931
                        purpose: Office supplies purchase
                        counterpartCustomerReference: reference
                      - id: 1002
                        externalId: '1235'
                        bankAccountId: 10
                        categoryId: 2
                        bookingDate: '2024-10-16'
                        amount: 2500
                        counterpartName: Client ABC GmbH
                        counterpartAccountNumber: '1231231230'
                        counterpartIban: DE89370400440532013000
                        purpose: Invoice payment INV-2024-10
                        counterpartCustomerReference: reference
        '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'
    post:
      tags:
        - Bank Account Transactions
      summary: Create bank account transaction
      description: Creates a new bank account transaction
      operationId: createBankAccountTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountTransactionCreateRequest'
            examples:
              transaction:
                summary: Transaction create example
                value:
                  bankAccountId: 10
                  transaction:
                    externalId: '1234'
                    categoryId: 5
                    bookingDate: '2024-10-15'
                    amount: -120.5
                    counterpartName: Amazon EU
                    counterpartAccountNumber: '9876543210'
                    counterpartIban: DE44500105175407324931
                    purpose: Office supplies purchase
                    counterpartCustomerReference: reference
      responses:
        '200':
          description: Bank account transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountTransactionResponse'
        '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'
  /bank-account-transactions/bulk:
    post:
      tags:
        - Bank Account Transactions
      summary: Create multiple bank account transactions
      description: >
        Creates multiple bank account transactions in a single request. A
        maximum of **1000 transactions** per bank account entry is allowed per
        request. Requests exceeding this limit will be rejected with a `400 Bad
        Request` response.
      operationId: createBankAccountTransactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountTransactionBulkCreateRequest'
            examples:
              multipleTransactions:
                summary: Multiple transactions example
                value:
                  bankAccountId: 10
                  transactions:
                    - categoryId: 5
                      externalId: '1234'
                      bookingDate: '2024-10-15'
                      amount: -120.5
                      counterpartName: Amazon EU
                      counterpartAccountNumber: '9876543210'
                      counterpartIban: DE44500105175407324931
                      purpose: Office supplies purchase
                      counterpartCustomerReference: REF-001
                    - categoryId: 2
                      externalId: '1235'
                      bookingDate: '2024-10-16'
                      amount: 2500
                      counterpartName: Client ABC GmbH
                      counterpartAccountNumber: '1231231230'
                      counterpartIban: DE89370400440532013000
                      purpose: Invoice payment INV-2024-10
                      counterpartCustomerReference: REF-002
                    - categoryId: 5
                      externalId: '1236'
                      bookingDate: '2024-10-17'
                      amount: -85
                      counterpartName: Office Depot
                      counterpartAccountNumber: '5555555555'
                      counterpartIban: DE12500105170648489890
                      purpose: Stationery supplies
                      counterpartCustomerReference: REF-003
      responses:
        '200':
          description: Bank account transactions created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkBankAccountTransactionCreateResponse'
        '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'
  /bank-account-transactions/exists:
    post:
      tags:
        - Bank Account Transactions
      summary: Check existence of bank account transactions by external ID
      description: >
        Checks whether transactions with the given external IDs already exist
        for a bank account. Useful for deduplication checks before a bulk
        create, or for inline reconciliation after a resend. A maximum of **1000
        external IDs** per request is allowed.
      operationId: checkBankAccountTransactionsExist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountTransactionExistsRequest'
            examples:
              existsCheck:
                summary: Existence check example
                value:
                  bankAccountId: 10
                  externalIds:
                    - '1234'
                    - '1235'
                    - '1236'
      responses:
        '200':
          description: Existence check completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountTransactionExistsResponse'
              examples:
                existsResult:
                  summary: Existence check result example
                  value:
                    success: true
                    data:
                      - externalId: '1234'
                        exists: true
                      - externalId: '1235'
                        exists: false
                      - externalId: '1236'
                        exists: true
        '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'
  /bank-account-transactions/{id}:
    get:
      tags:
        - Bank Account Transactions
      summary: Get bank account transaction
      description: Get bank account transaction by id
      operationId: getBankAccountTransaction
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the bank account transaction
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Bank account transaction retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountTransactionResponse'
        '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'
    patch:
      tags:
        - Bank Account Transactions
      summary: Update bank account transaction
      description: Updates a bank account transaction
      operationId: updateBankAccountTransaction
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the bank account transaction
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountTransactionUpdateRequest'
            examples:
              transactionUpdate:
                summary: Transaction update example
                value:
                  categoryId: 5
                  externalId: '1234'
                  bookingDate: '2024-10-15'
                  amount: -120.5
                  counterpartName: Amazon EU
                  counterpartAccountNumber: '9876543210'
                  counterpartIban: DE44500105175407324931
                  purpose: Office supplies purchase
                  counterpartCustomerReference: reference
      responses:
        '200':
          description: Bank account transaction updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountTransactionResponse'
        '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'
    delete:
      tags:
        - Bank Account Transactions
      summary: Delete bank account transactions
      description: Deletes bank account transaction by id
      operationId: deleteBankAccountTransaction
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the bank account transaction
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Bank account transaction deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountTransactionDeleteResponse'
        '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'
  /companies:
    get:
      tags:
        - Companies
      summary: Get companies
      description: Get companies
      operationId: getCompanies
      parameters:
        - name: page
          in: query
          description: Page number (0-based)
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: pageSize
          in: query
          description: Number of balances per page
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Companies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompaniesResponse'
              examples:
                companyList:
                  summary: Companies list example
                  value:
                    success: true
                    message: Companies retrieved successfully
                    number: 0
                    size: 20
                    totalElements: 125
                    totalPages: 8
                    data:
                      - id: 1
                        parentId: 3
                        name: Test GmbH
                        currency: EUR
                        country: Germany
                        industry: ECOMMERCE
                      - id: 2
                        parentId: 4
                        name: Test2 GmbH
                        currency: EUR
                        country: Germany
                        industry: PUBLIC_SECTOR
        '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'
  /cashflow:
    get:
      tags:
        - Cashflow
      summary: Get cashflow
      description: >
        Retrieves the cashflow of the authenticated company aggregated per
        period.

        Each period bucket contains the opening and closing balances (actual,
        prognosed, total

        and plan), the sales and purchases totals, the amounts per category, the
        aggregated

        income and expense details, and any non-financial KPIs. Per-period
        overdraft and

        liquidity figures are returned alongside, keyed by the same period start
        dates.

        All amounts are returned with two decimals. Only periods within the
        resolved

        `from`/`to` range are returned.


        When `scenarioId` is omitted, the base forecast scenario is used.

        When `from`/`to` are omitted, the range defaults to 6 periods in the
        past and 18 periods

        in the future. The range between `from` and `to` must not exceed 36
        periods.
      operationId: getCashflow
      parameters:
        - name: scenarioId
          in: query
          description: >-
            ID of the scenario to calculate the cashflow for. Defaults to the
            base forecast scenario.
          required: false
          schema:
            type: integer
            format: int64
          example: 1
        - name: period
          in: query
          description: Aggregation period of the cashflow buckets.
          required: false
          schema:
            $ref: '#/components/schemas/CashflowPeriod'
        - name: from
          in: query
          description: >
            Start of the range in ISO 8601 format (yyyy-MM-dd). Must be the
            first day of the

            requested period (first day of the month for MONTH, Monday for
            WEEK).

            When omitted it defaults to 6 periods before `to`, or before the
            current date

            when `to` is omitted as well.
          required: false
          schema:
            type: string
            format: date
          example: '2025-01-01'
        - name: to
          in: query
          description: >
            End of the range in ISO 8601 format (yyyy-MM-dd). Must be the last
            day of the

            requested period (last day of the month for MONTH, Sunday for WEEK)
            and not before `from`.

            When omitted it defaults to 18 periods after `from`, or after the
            current date

            when `from` is omitted as well.
          required: false
          schema:
            type: string
            format: date
          example: '2025-12-31'
      responses:
        '200':
          description: Cashflow retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashflowResponse'
              examples:
                cashflow:
                  summary: Monthly cashflow example
                  value:
                    cashflow:
                      data:
                        '2025-06-01':
                          totalSales: 0
                          totalPurchases: 0
                          startBalance: 0
                          planStartBalance: 0
                          amountPerCategory:
                            '1163025':
                              sumOfBankTransactions: -7455.9
                              sumOfInvoices: 0
                              sumOfPlannedValues: 0
                              amount: -7455.9
                              remainingAmount: 0
                              planDeviation: -7455.9
                          incomeDetails:
                            sumOfBankTransactions: 211941.3
                            sumOfInvoices: 0
                            sumOfPlannedValues: 72850
                            prognosed: 211941.3
                            remainingAmount: 0
                            planDeviation: 139091.3
                            planAchievementPct: 291
                          expenseDetails:
                            sumOfBankTransactions: -83574.9
                            sumOfInvoices: 0
                            sumOfPlannedValues: -32575.5
                            prognosed: -113427.9
                            remainingAmount: -29853
                            planDeviation: -50999.4
                            planAchievementPct: 257
                          actualEndBalance: 128366
                          prognosedEndBalance: 98513
                          totalEndBalance: 128366
                          planEndBalance: 40275
                          nfKpis: {}
                          categoriesWithNotes: {}
                      overdraftData:
                        '2025-06-01':
                          overdraftLimit: 100000
                          totalLiquidity: 228366.4
                          totalPlannedLiquidity: 198513.4
        '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'
  /companies/{id}:
    get:
      tags:
        - Companies
      summary: Get company
      description: Get company by id
      operationId: getCompany
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the company
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Company retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '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'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Authorization
      description: API key for authentication
  responses:
    BadRequest:
      description: Bad Request - The request was invalid or cannot be served
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExceptionDetails'
    Unauthorized:
      description: >-
        Unauthorized - Authentication is required and has failed or has not been
        provided
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExceptionDetails'
    Forbidden:
      description: Forbidden - The request is valid but the server is refusing action
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExceptionDetails'
    NotFound:
      description: Not Found - The requested resource could not be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExceptionDetails'
    InternalServerError:
      description: Internal Server Error - The server encountered an unexpected condition
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExceptionDetails'
  schemas:
    PlanCreateDto:
      type: object
      description: Data transfer object for creating a financial plan
      required:
        - amount
        - name
        - type
        - period
        - date
      properties:
        categoryId:
          type: integer
          format: int64
          description: >-
            Unique identifier of the category. If neither categoryId nor
            categoryName is specified, plan will go to uncategorized expenses
            for negative amounts and uncategorized income for positive amounts.
        categoryName:
          type: string
          description: >-
            Category path as a string (e.g., 'Einzahlungen aus
            Geschäftstätigkeit->E-COMMERCE->Plattform 1'). Used if categoryId is
            not provided.
        amount:
          type: number
          description: Amount of the plan (negative for expenses, positive for income)
          minimum: -10000000000000000
          maximum: 10000000000000000
        period:
          type: string
          description: Period for which the plan value applies
          enum:
            - DAILY
            - WEEKLY
            - MONTHLY
        date:
          type: string
          format: date
          description: >-
            The date of the plan in ISO 8601 format (yyyy-MM-dd). For MONTHLY
            period, use the first day of the month. For WEEKLY period, use the
            first day of the week.
        type:
          type: string
          description: Type of the plan
          enum:
            - ONE_TIME
        name:
          type: string
          description: Name of the plan
          minLength: 1
          maxLength: 100
        scenarioId:
          type: integer
          format: int64
          description: >-
            Identifier of the scenario. If not specified, the plan will be
            created for the Base scenario.
        scenarioName:
          type: string
          description: >-
            Name of the scenario. Used if scenarioId is not provided. If neither
            is specified, the Base scenario is used.
        replaceCurrentValuesForThePeriod:
          type: boolean
          description: >-
            If true, replaces existing values for the period. If false, adds to
            existing values.
          default: false
    ApiResponse:
      type: object
      description: Standard API response wrapper
      properties:
        success:
          type: boolean
          description: Indicates whether the operation was successful
        message:
          type: string
          description: Optional informational message
    PlanCreateResponse:
      type: object
      description: Response after creating a plan
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            planId:
              type: integer
              format: int64
              description: ID of the created plan
      required:
        - planId
        - success
    ExceptionDetails:
      type: object
      description: Standard error response structure
      required:
        - timestamp
        - error
        - message
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when the error occurred
        error:
          type: string
          description: >-
            Stable, machine-readable error code (e.g. `USER_NOT_FOUND`,
            `SSO_NOT_ENABLED`). Use this for programmatic error handling.
        message:
          type: string
          description: >-
            Human-readable description of the error. For display/logging only —
            do not match on it.
    PlanDeleteResponse:
      type: object
      description: Response after deleting plans
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            deletedCount:
              type: integer
              description: Number of plans deleted
      required:
        - success
        - deletedCount
    BulkPlanCreateResponse:
      type: object
      description: Response after creating multiple plans
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            createdCount:
              type: integer
              description: Number of plans successfully created
            planIds:
              type: array
              items:
                type: integer
                format: int64
              description: IDs of the created plans
      required:
        - success
        - createdCount
    InvoiceTypeFilter:
      type: string
      description: Invoice type filter for querying invoices
      enum:
        - SALE
        - PURCHASE
    PaginationMetadata:
      type: object
      description: Pagination information
      properties:
        number:
          type: integer
          description: Current page number (0-based)
          example: 0
        size:
          type: integer
          description: Number of items per page
          example: 20
        totalElements:
          type: integer
          format: int64
          description: Total number of elements
          example: 125
        totalPages:
          type: integer
          description: Total number of pages
          example: 8
    InvoiceUpdateBase:
      type: object
      description: Mutable invoice fields shared between create and update
      properties:
        invoiceDate:
          type: string
          format: date
          description: Invoice date in ISO 8601 format
        dueDate:
          type: string
          format: date
          description: Due date of the invoice in ISO 8601 format
        paidDate:
          type: string
          format: date
          description: Invoice payment date and time in ISO 8601 format
          nullable: true
        invoiceNumber:
          type: string
          description: Invoice number
          minLength: 1
        contactName:
          type: string
          description: Recipient name of the invoice
          minLength: 1
        totalGrossAmount:
          type: number
          description: Total gross amount including tax
          minimum: -10000000000000000
          maximum: 10000000000000000
        invoiceStatus:
          type: string
          description: Status of the invoice
          enum:
            - DRAFT
            - OPEN
            - PAID
            - PARTIALLY_PAID
            - CANCELED
            - WITHHELD
        openAmount:
          type: number
          description: Open (unpaid) amount of the invoice
          minimum: -10000000000000000
          maximum: 10000000000000000
          nullable: true
        note:
          type: string
          description: Description or notes for the invoice
          nullable: true
        categoryId:
          type: integer
          format: int64
          description: Unique identifier of the category
          nullable: true
    InvoiceTypeEnum:
      type: string
      description: Type of invoice
      enum:
        - SALES_INVOICE
        - SALES_CREDIT_NOTE
        - PURCHASE_INVOICE
        - PURCHASE_CREDIT_NOTE
    InvoiceBase:
      type: object
      description: Invoice base model
      allOf:
        - $ref: '#/components/schemas/InvoiceUpdateBase'
        - type: object
          properties:
            externalId:
              type: string
              description: >-
                External identifier of the invoice, used for integration with
                external systems
            invoiceType:
              $ref: '#/components/schemas/InvoiceTypeEnum'
    Invoice:
      type: object
      description: >
        Invoice with id and system metadata.

        Invoices that originate from an ERP integration are **read-only** —
        update and delete operations are not allowed.
      required:
        - id
      allOf:
        - $ref: '#/components/schemas/InvoiceBase'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the invoice
    InvoicesResponse:
      description: Standard API response wrapper for invoice list
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - $ref: '#/components/schemas/PaginationMetadata'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Invoice'
    InvoiceCreateRequest:
      type: object
      description: Invoice create object
      allOf:
        - $ref: '#/components/schemas/InvoiceBase'
      required:
        - invoiceNumber
        - contactName
        - invoiceType
        - totalGrossAmount
    InvoiceResponse:
      type: object
      description: Standard API response wrapper for an invoice
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Invoice'
    InvoiceBulkCreateRequest:
      type: object
      description: Bulk create invoices
      required:
        - invoices
      properties:
        invoices:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/InvoiceCreateRequest'
    BulkOperationError:
      type: object
      description: Details of a single failed item in a bulk operation
      properties:
        index:
          type: integer
          description: Index of the failed item in the request array
        reason:
          type: string
          description: Reason for the failure
    BulkInvoiceCreateResponse:
      type: object
      description: Response after creating multiple invoices
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            createdCount:
              type: integer
              description: Number of invoices successfully created
            invoiceIds:
              type: array
              items:
                type: integer
                format: int64
              description: IDs of the created invoices
            failedCount:
              type: integer
              description: Number of invoices that failed to create
            errors:
              type: array
              items:
                $ref: '#/components/schemas/BulkOperationError'
              description: Details of any failed invoice creations
      required:
        - success
        - createdCount
    InvoiceDeleteResponse:
      type: object
      description: Response after deleting an invoice
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the deleted invoice
      required:
        - success
        - id
    InvoiceUpdateRequest:
      type: object
      description: Invoice update object
      allOf:
        - $ref: '#/components/schemas/InvoiceUpdateBase'
    ScenarioOpenApiDto:
      type: object
      description: Scenario information
      required:
        - id
        - name
        - isBaseCase
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the scenario
        name:
          type: string
          description: Name of the scenario
        isBaseCase:
          type: boolean
          description: Indicates whether this is the base case scenario
    CategoryType:
      type: string
      description: Type of category indicating income or expense classification
      enum:
        - INCOME_OPERATIONAL
        - INCOME_INVESTMENT
        - INCOME_FINANCING
        - EXPENSE_OPERATIONAL
        - EXPENSE_INVESTMENT
        - EXPENSE_FINANCING
    Category:
      type: object
      description: Financial category information
      required:
        - id
        - name
        - type
        - enabledForPlannedTransactions
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the category
        name:
          type: string
          description: Name of the category
        type:
          $ref: '#/components/schemas/CategoryType'
        parentId:
          type: integer
          format: int64
          description: ID of the parent category for hierarchical categorization
          nullable: true
        enabledForPlannedTransactions:
          type: boolean
          description: Indicates whether this category can be used for planned transactions
    CategoryCreateRequest:
      type: object
      description: Data transfer object for creating a category
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Name of the category
        type:
          $ref: '#/components/schemas/CategoryType'
        parentId:
          type: integer
          format: int64
          description: ID of the parent category for hierarchical categorization
          nullable: true
    CategoryDeleteResponse:
      type: object
      description: Response after deleting a category
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the deleted category
      required:
        - success
        - id
    CategoryUpdateRequest:
      type: object
      description: Data transfer object for updating a category
      properties:
        name:
          type: string
          description: Name of the category
        type:
          $ref: '#/components/schemas/CategoryType'
    AuthenticationResponse:
      type: object
      description: Response from authentication verification
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            name:
              type: string
              description: Name of the authenticated user
              nullable: true
      required:
        - success
    Currency:
      type: string
      description: ISO 4217 currency codes
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTC
        - BTN
        - BWP
        - BYR
        - BYN
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHN
        - CHW
        - CLF
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GGP
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - IMP
        - INR
        - IQD
        - IRR
        - ISK
        - JEP
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KID
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LTL
        - LVL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NIS
        - NOK
        - NPR
        - NTD
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PRB
        - PYG
        - QAR
        - RMB
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLL
        - SLS
        - SOS
        - SRD
        - SSP
        - STD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TVD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - USN
        - UYI
        - UYU
        - UYW
        - UZS
        - VEF
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XBA
        - XBB
        - XBC
        - XBD
        - XCD
        - XDR
        - XOF
        - XPD
        - XPF
        - XPT
        - XSU
        - XTS
        - XUA
        - XXX
        - YER
        - ZAR
        - ZMK
        - ZMW
        - ZWB
        - ZWL
    AccountType:
      type: string
      description: Type of account
      enum:
        - CHECKING
        - SAVINGS
        - CREDITCARD
        - SECURITY
        - LOAN
        - POCKET
        - MEMBERSHIP
        - BAUSPAREN
    BankAccount:
      type: object
      description: Bank account base model
      properties:
        companyId:
          type: integer
          format: int64
          description: ID of the company the bank account belongs to
        iban:
          type: string
          description: International Bank Account Number
        accountNumber:
          type: string
          description: Local account number
        accountCurrency:
          $ref: '#/components/schemas/Currency'
          default: EUR
        accountName:
          type: string
          description: Name of the account
        bankName:
          type: string
          maxLength: 255
          description: Bank of the account
        balanceReference:
          type: number
          description: >-
            Start-of-day balance of the bank account on the date specified in
            balanceDate. This balance will be used as a reference for
            calculating past and future balances based on the bank account's
            transactions.
          minimum: -1000000000000
          maximum: 1000000000000
        balanceDate:
          type: string
          format: date
          description: >-
            The date of the balance specified in balanceReference in ISO 8601
            format (yyyy-MM-dd).
        accountType:
          $ref: '#/components/schemas/AccountType'
        externalId:
          type: string
          description: >-
            External identifier for the bank account, used for integration with
            external systems
    BankProvider:
      type: string
      enum:
        - OFFLINE
        - ONLINE
    BankAccountWithId:
      type: object
      description: Bank account response
      required:
        - id
      allOf:
        - $ref: '#/components/schemas/BankAccount'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the bank account
            provider:
              $ref: '#/components/schemas/BankProvider'
    BankAccountsResponse:
      type: object
      description: Standard API response wrapper for bank account list
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/BankAccountWithId'
    BankAccountCreateRequest:
      type: object
      description: Data transfer object for creating a bank account
      allOf:
        - $ref: '#/components/schemas/BankAccount'
        - type: object
          required:
            - bankName
            - accountName
            - accountType
            - accountCurrency
    BankAccountResponse:
      type: object
      description: Standard API response wrapper for a bank account
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/BankAccountWithId'
    BankAccountDeleteResponse:
      type: object
      description: Response after deleting a bank account
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the deleted bank account
      required:
        - success
        - id
    BankAccountUpdateRequest:
      type: object
      description: Data transfer object for updating a bank account
      allOf:
        - $ref: '#/components/schemas/BankAccount'
    BankAccountBalanceResponse:
      type: object
      description: Bank account balance response
      properties:
        date:
          type: string
          format: date
          description: Balance date in ISO 8601 format
        amount:
          type: number
          description: Balance amount
    BankAccountBalancesResponse:
      description: Standard API response wrapper for bank account balance list
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - $ref: '#/components/schemas/PaginationMetadata'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/BankAccountBalanceResponse'
    BankAccountTransactionBase:
      type: object
      description: Bank account transaction base model
      properties:
        categoryId:
          type: integer
          format: int64
          description: ID of the category
        bookingDate:
          type: string
          format: date
          description: Booking date in ISO 8601 format
        amount:
          type: number
          description: Transaction amount in bank account currency
          minimum: -10000000000000000
          maximum: 10000000000000000
        counterpartName:
          type: string
          description: Counterpart of the transaction
        counterpartAccountNumber:
          type: string
          description: Counterpart account number of the transaction
        counterpartIban:
          type: string
          description: Counterpart iban of the transaction
        purpose:
          type: string
          description: Description of the transaction
        counterpartCustomerReference:
          type: string
          description: Counterpart customer reference
        externalId:
          type: string
          description: >-
            External identifier for the transaction, used for integration with
            external systems
          maxLength: 255
    BankAccountTransaction:
      type: object
      description: Bank account transaction with id and bank account id
      required:
        - id
      allOf:
        - $ref: '#/components/schemas/BankAccountTransactionBase'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the bank account transaction
            bankAccountId:
              type: integer
              format: int64
              description: ID of the bank account
    BankAccountTransactionsResponse:
      description: Standard API response wrapper for bank account transaction list
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - $ref: '#/components/schemas/PaginationMetadata'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/BankAccountTransaction'
    BankAccountTransactionCreateRequest:
      type: object
      description: Bank account transaction create object
      required:
        - bankAccountId
        - transaction
      properties:
        bankAccountId:
          type: integer
          format: int64
        transaction:
          allOf:
            - $ref: '#/components/schemas/BankAccountTransactionBase'
          required:
            - bookingDate
            - amount
            - counterpartName
    BankAccountTransactionResponse:
      type: object
      description: Standard API response wrapper for a bank account transaction
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/BankAccountTransaction'
    BankAccountTransactionBulkCreateRequest:
      type: object
      description: Bulk create bank account transactions
      required:
        - bankAccountId
        - transactions
      properties:
        bankAccountId:
          type: integer
          format: int64
        transactions:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/BankAccountTransactionBase'
            required:
              - bookingDate
              - amount
              - counterpartName
    BulkOperationSkipped:
      type: object
      description: >-
        Details of a single skipped item in a bulk operation (e.g. already
        exists)
      properties:
        index:
          type: integer
          description: Index of the skipped item in the request array
        externalId:
          type: string
          description: External ID of the skipped item
    BulkBankAccountTransactionCreateResponse:
      type: object
      description: Response after creating multiple bank account transactions
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            createdCount:
              type: integer
              description: Number of transactions successfully created
            transactionIds:
              type: array
              items:
                type: integer
                format: int64
              description: IDs of the created transactions
            failedCount:
              type: integer
              description: Number of transactions that failed to create
            errors:
              type: array
              items:
                $ref: '#/components/schemas/BulkOperationError'
              description: Details of any failed transaction creations
            skippedCount:
              type: integer
              description: >-
                Number of transactions skipped because they already exist
                (matched by externalId)
            skipped:
              type: array
              items:
                $ref: '#/components/schemas/BulkOperationSkipped'
              description: >-
                Details of skipped transactions; present on clean resends where
                createdCount is 0
      required:
        - success
        - createdCount
    BankAccountTransactionExistsRequest:
      type: object
      description: >-
        Request body for checking existence of bank account transactions by
        external ID
      properties:
        bankAccountId:
          type: integer
          format: int64
          description: ID of the bank account to check against
        externalIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 1000
          description: External IDs to check
      required:
        - bankAccountId
        - externalIds
    BankAccountTransactionExistsItem:
      type: object
      description: Existence result for a single external ID
      properties:
        externalId:
          type: string
          description: The external ID that was checked
        exists:
          type: boolean
          description: Whether a transaction with this external ID already exists
      required:
        - externalId
        - exists
    BankAccountTransactionExistsResponse:
      type: object
      description: Response for the bulk-exists check
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/BankAccountTransactionExistsItem'
              description: Existence result for each requested external ID
      required:
        - success
    BankAccountTransactionDeleteResponse:
      type: object
      description: Response after deleting a bank account transaction
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: ID of the deleted bank account transaction
      required:
        - success
        - id
    BankAccountTransactionUpdateRequest:
      type: object
      description: Bank account transaction update object
      allOf:
        - $ref: '#/components/schemas/BankAccountTransactionBase'
    CompanyIndustry:
      type: string
      description: Company industry
      enum:
        - ECOMMERCE
        - CONSULTING
        - REAL_ESTATE
        - CONSTRUCTION
        - SOFTWARE
        - ADVERTISING
        - STARTUP
        - OTHER
        - EDUCATION
        - ENERGY
        - FINANCIAL_SERVICES
        - LEISURE
        - HEALTHCARE
        - AGRICULTURE
        - FOOD_AND_CONSUMER_GOODS
        - MEDIA
        - PERSONNEL_SERVICES
        - PRODUCTION
        - OTHER_SERVICES
        - TELECOMMUNICATIONS
        - TRANSPORT_AND_LOGISTICS
        - ASSOCIATIONS
        - PUBLIC_SECTOR
    Company:
      type: object
      description: Company base model
      properties:
        id:
          type: integer
          format: int64
          description: ID of the company
        parentId:
          type: integer
          format: int64
          description: ID of the parent company
        name:
          type: string
          description: Local account number
        currency:
          type: string
          description: Currency of the account
          default: EUR
        country:
          type: string
          description: Name of the account
        industry:
          $ref: '#/components/schemas/CompanyIndustry'
    CompaniesResponse:
      description: Standard API response wrapper for companies list
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - $ref: '#/components/schemas/PaginationMetadata'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Company'
    CashflowPeriod:
      type: string
      description: Aggregation period of the cashflow buckets
      default: MONTH
      enum:
        - MONTH
        - WEEK
        - DAY
    CashflowAmountPerCategory:
      type: object
      description: >-
        Amounts of a single category within a period. All amounts have two
        decimals.
      properties:
        sumOfBankTransactions:
          type: number
          description: Sum of the realised bank transactions of the category
        sumOfInvoices:
          type: number
          description: Sum of the open invoices of the category
        sumOfPlannedValues:
          type: number
          description: Sum of the planned values of the category
        amount:
          type: number
          description: Displayed amount of the category for the period
        remainingAmount:
          type: number
          description: Remaining amount still expected for the category
        planDeviation:
          type: number
          description: Deviation of bank transactions plus invoices from the plan
        planAchievementPct:
          type: number
          description: >-
            Plan achievement percentage. Only present when the category has a
            percentage.
    CashflowAmountDetails:
      type: object
      description: >-
        Aggregated income or expense details of a period. All amounts have two
        decimals.
      properties:
        sumOfBankTransactions:
          type: number
          description: Sum of the realised bank transactions
        sumOfInvoices:
          type: number
          description: Sum of the open invoices
        sumOfPlannedValues:
          type: number
          description: Sum of the planned values
        prognosed:
          type: number
          description: Projected amount of the period
        remainingAmount:
          type: number
          description: Remaining amount still expected
        planDeviation:
          type: number
          description: Deviation of bank transactions plus invoices from the plan
        planAchievementPct:
          type: number
          description: >-
            Plan achievement percentage. Only present when the calculation
            produced a numeric one.
    CashflowCategoryNote:
      type: object
      description: Reference to the plan note attached to a category in a period
      properties:
        noteId:
          type: integer
          format: int64
          description: Identifier of the plan note
    CashflowPeriodValues:
      type: object
      description: >-
        Cashflow figures for a single period bucket. All amounts have two
        decimals.
      properties:
        totalSales:
          type: number
          description: Total sales (open sales invoices) of the period
        totalPurchases:
          type: number
          description: Total purchases (open purchase invoices) of the period
        startBalance:
          type: number
          description: >-
            Total balance across the company bank accounts at the start of the
            period
        planStartBalance:
          type: number
          description: Planned total balance at the start of the period
        amountPerCategory:
          type: object
          description: Amounts per category, keyed by category id
          additionalProperties:
            $ref: '#/components/schemas/CashflowAmountPerCategory'
        incomeDetails:
          $ref: '#/components/schemas/CashflowAmountDetails'
        expenseDetails:
          $ref: '#/components/schemas/CashflowAmountDetails'
        actualEndBalance:
          type: number
          description: Realised total balance at the end of the period
        prognosedEndBalance:
          type: number
          description: Projected total balance at the end of the period
        totalEndBalance:
          type: number
          description: Total balance at the end of the period (realised plus projected)
        planEndBalance:
          type: number
          description: Planned total balance at the end of the period
        nfKpis:
          type: object
          description: Non-financial KPI values, keyed by KPI id
          additionalProperties:
            type: number
        categoriesWithNotes:
          type: object
          description: Plan notes per category, keyed by category id
          additionalProperties:
            $ref: '#/components/schemas/CashflowCategoryNote'
    CashflowOverdraft:
      type: object
      description: >-
        Overdraft and liquidity information of a period. All amounts have two
        decimals.
      properties:
        overdraftLimit:
          type: number
          description: Total overdraft limit across the company bank accounts
        totalLiquidity:
          type: number
          description: Total available liquidity
        totalPlannedLiquidity:
          type: number
          description: Total planned liquidity
    CashflowData:
      type: object
      description: Cashflow payload keyed by period start date
      properties:
        data:
          type: object
          description: Per-period cashflow figures, keyed by period start date (ISO 8601)
          additionalProperties:
            $ref: '#/components/schemas/CashflowPeriodValues'
        overdraftData:
          type: object
          description: >-
            Per-period overdraft information, keyed by period start date (ISO
            8601)
          additionalProperties:
            $ref: '#/components/schemas/CashflowOverdraft'
    CashflowResponse:
      type: object
      description: >-
        Cashflow of the authenticated company for the resolved scenario and date
        range
      required:
        - cashflow
      properties:
        cashflow:
          $ref: '#/components/schemas/CashflowData'
    CompanyResponse:
      type: object
      description: Standard API response wrapper for a company
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Company'
