backbone-banking 0.7.1

openapi: '3.0.3'
info:
  title: Backbone API
  version: '1.0.0'
  description: |
    Auto-generated by backbone-cli.
    This API provides 11 standard CRUD endpoints for each model.

servers:
  - url: /
    description: Development server

tags:
  - name: Banks
    description: Bank management endpoints
  - name: BankAccounts
    description: BankAccount management endpoints
  - name: BankClearances
    description: BankClearance management endpoints
  - name: BankReconciliations
    description: BankReconciliation management endpoints
  - name: BankStatementImports
    description: BankStatementImport management endpoints
  - name: BankTransactions
    description: BankTransaction management endpoints
  - name: FxGainLosses
    description: FxGainLoss management endpoints
  - name: ReconcilePresets
    description: ReconcilePreset management endpoints

paths:
  /api/v1/banking/banks:
    get:
      tags:
        - Banks
      summary: List Banks
      description: Get a paginated list of Banks with optional filtering and sorting
      operationId: listBanks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Banks
      summary: Create Bank
      description: Create a new Bank
      operationId: createBank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/banks/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Banks
      summary: Get Bank by ID
      operationId: getBank
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Banks
      summary: Update Bank (full)
      operationId: updateBank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Banks
      summary: Update Bank (partial)
      operationId: patchBank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBankRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Banks
      summary: Delete Bank (soft)
      operationId: deleteBank
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/banks/bulk:
    post:
      tags:
        - Banks
      summary: Bulk create Banks
      operationId: bulkCreateBanks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBankRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bank'
    put:
      tags:
        - Banks
      summary: Bulk update Banks (full, atomic)
      operationId: bulkUpdateBanks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBankRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Banks
      summary: Bulk partial-update Banks (atomic)
      operationId: bulkPatchBanks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/banks/upsert:
    post:
      tags:
        - Banks
      summary: Upsert Bank
      operationId: upsertBank
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'

  /api/v1/banking/banks/trash:
    get:
      tags:
        - Banks
      summary: List deleted Banks
      operationId: listDeletedBanks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankList'

  /api/v1/banking/banks/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Banks
      summary: Restore deleted Bank
      operationId: restoreBank
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bank'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/banks/empty:
    delete:
      tags:
        - Banks
      summary: Empty trash for Banks
      operationId: emptyTrashBanks
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/banks/delete/bulk:
    post:
      tags:
        - Banks
      summary: Bulk soft-delete Banks by ids (atomic)
      operationId: bulkDeleteBanks
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/banks/restore/bulk:
    post:
      tags:
        - Banks
      summary: Bulk restore Banks by ids (atomic)
      operationId: bulkRestoreBanks
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/banks/restore/all:
    post:
      tags:
        - Banks
      summary: Restore all soft-deleted Banks
      operationId: restoreAllBanks
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/banks/trash/bulk:
    delete:
      tags:
        - Banks
      summary: Bulk permanently-delete Banks from trash by ids (atomic)
      operationId: bulkPermanentDeleteBanks
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_accounts:
    get:
      tags:
        - BankAccounts
      summary: List BankAccounts
      description: Get a paginated list of BankAccounts with optional filtering and sorting
      operationId: listBankAccounts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - BankAccounts
      summary: Create BankAccount
      description: Create a new BankAccount
      operationId: createBankAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankAccountRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/bank_accounts/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - BankAccounts
      summary: Get BankAccount by ID
      operationId: getBankAccount
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - BankAccounts
      summary: Update BankAccount (full)
      operationId: updateBankAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankAccountRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - BankAccounts
      summary: Update BankAccount (partial)
      operationId: patchBankAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBankAccountRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - BankAccounts
      summary: Delete BankAccount (soft)
      operationId: deleteBankAccount
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_accounts/bulk:
    post:
      tags:
        - BankAccounts
      summary: Bulk create BankAccounts
      operationId: bulkCreateBankAccounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBankAccountRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccount'
    put:
      tags:
        - BankAccounts
      summary: Bulk update BankAccounts (full, atomic)
      operationId: bulkUpdateBankAccounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBankAccountRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - BankAccounts
      summary: Bulk partial-update BankAccounts (atomic)
      operationId: bulkPatchBankAccounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_accounts/upsert:
    post:
      tags:
        - BankAccounts
      summary: Upsert BankAccount
      operationId: upsertBankAccount
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankAccountRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'

  /api/v1/banking/bank_accounts/trash:
    get:
      tags:
        - BankAccounts
      summary: List deleted BankAccounts
      operationId: listDeletedBankAccounts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountList'

  /api/v1/banking/bank_accounts/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - BankAccounts
      summary: Restore deleted BankAccount
      operationId: restoreBankAccount
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_accounts/empty:
    delete:
      tags:
        - BankAccounts
      summary: Empty trash for BankAccounts
      operationId: emptyTrashBankAccounts
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/bank_accounts/delete/bulk:
    post:
      tags:
        - BankAccounts
      summary: Bulk soft-delete BankAccounts by ids (atomic)
      operationId: bulkDeleteBankAccounts
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_accounts/restore/bulk:
    post:
      tags:
        - BankAccounts
      summary: Bulk restore BankAccounts by ids (atomic)
      operationId: bulkRestoreBankAccounts
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_accounts/restore/all:
    post:
      tags:
        - BankAccounts
      summary: Restore all soft-deleted BankAccounts
      operationId: restoreAllBankAccounts
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/bank_accounts/trash/bulk:
    delete:
      tags:
        - BankAccounts
      summary: Bulk permanently-delete BankAccounts from trash by ids (atomic)
      operationId: bulkPermanentDeleteBankAccounts
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_clearances:
    get:
      tags:
        - BankClearances
      summary: List BankClearances
      description: Get a paginated list of BankClearances with optional filtering and sorting
      operationId: listBankClearances
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearanceList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - BankClearances
      summary: Create BankClearance
      description: Create a new BankClearance
      operationId: createBankClearance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankClearanceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearance'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/bank_clearances/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - BankClearances
      summary: Get BankClearance by ID
      operationId: getBankClearance
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearance'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - BankClearances
      summary: Update BankClearance (full)
      operationId: updateBankClearance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankClearanceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearance'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - BankClearances
      summary: Update BankClearance (partial)
      operationId: patchBankClearance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBankClearanceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearance'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - BankClearances
      summary: Delete BankClearance (soft)
      operationId: deleteBankClearance
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_clearances/bulk:
    post:
      tags:
        - BankClearances
      summary: Bulk create BankClearances
      operationId: bulkCreateBankClearances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBankClearanceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankClearance'
    put:
      tags:
        - BankClearances
      summary: Bulk update BankClearances (full, atomic)
      operationId: bulkUpdateBankClearances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBankClearanceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearanceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - BankClearances
      summary: Bulk partial-update BankClearances (atomic)
      operationId: bulkPatchBankClearances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearanceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_clearances/upsert:
    post:
      tags:
        - BankClearances
      summary: Upsert BankClearance
      operationId: upsertBankClearance
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankClearanceRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearance'

  /api/v1/banking/bank_clearances/trash:
    get:
      tags:
        - BankClearances
      summary: List deleted BankClearances
      operationId: listDeletedBankClearances
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearanceList'

  /api/v1/banking/bank_clearances/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - BankClearances
      summary: Restore deleted BankClearance
      operationId: restoreBankClearance
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearance'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_clearances/empty:
    delete:
      tags:
        - BankClearances
      summary: Empty trash for BankClearances
      operationId: emptyTrashBankClearances
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/bank_clearances/delete/bulk:
    post:
      tags:
        - BankClearances
      summary: Bulk soft-delete BankClearances by ids (atomic)
      operationId: bulkDeleteBankClearances
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_clearances/restore/bulk:
    post:
      tags:
        - BankClearances
      summary: Bulk restore BankClearances by ids (atomic)
      operationId: bulkRestoreBankClearances
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankClearanceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_clearances/restore/all:
    post:
      tags:
        - BankClearances
      summary: Restore all soft-deleted BankClearances
      operationId: restoreAllBankClearances
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/bank_clearances/trash/bulk:
    delete:
      tags:
        - BankClearances
      summary: Bulk permanently-delete BankClearances from trash by ids (atomic)
      operationId: bulkPermanentDeleteBankClearances
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_reconciliations:
    get:
      tags:
        - BankReconciliations
      summary: List BankReconciliations
      description: Get a paginated list of BankReconciliations with optional filtering and sorting
      operationId: listBankReconciliations
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliationList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - BankReconciliations
      summary: Create BankReconciliation
      description: Create a new BankReconciliation
      operationId: createBankReconciliation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankReconciliationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/bank_reconciliations/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - BankReconciliations
      summary: Get BankReconciliation by ID
      operationId: getBankReconciliation
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliation'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - BankReconciliations
      summary: Update BankReconciliation (full)
      operationId: updateBankReconciliation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankReconciliationRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliation'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - BankReconciliations
      summary: Update BankReconciliation (partial)
      operationId: patchBankReconciliation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBankReconciliationRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliation'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - BankReconciliations
      summary: Delete BankReconciliation (soft)
      operationId: deleteBankReconciliation
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_reconciliations/bulk:
    post:
      tags:
        - BankReconciliations
      summary: Bulk create BankReconciliations
      operationId: bulkCreateBankReconciliations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBankReconciliationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankReconciliation'
    put:
      tags:
        - BankReconciliations
      summary: Bulk update BankReconciliations (full, atomic)
      operationId: bulkUpdateBankReconciliations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBankReconciliationRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliationBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - BankReconciliations
      summary: Bulk partial-update BankReconciliations (atomic)
      operationId: bulkPatchBankReconciliations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliationBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_reconciliations/upsert:
    post:
      tags:
        - BankReconciliations
      summary: Upsert BankReconciliation
      operationId: upsertBankReconciliation
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankReconciliationRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliation'

  /api/v1/banking/bank_reconciliations/trash:
    get:
      tags:
        - BankReconciliations
      summary: List deleted BankReconciliations
      operationId: listDeletedBankReconciliations
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliationList'

  /api/v1/banking/bank_reconciliations/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - BankReconciliations
      summary: Restore deleted BankReconciliation
      operationId: restoreBankReconciliation
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliation'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_reconciliations/empty:
    delete:
      tags:
        - BankReconciliations
      summary: Empty trash for BankReconciliations
      operationId: emptyTrashBankReconciliations
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/bank_reconciliations/delete/bulk:
    post:
      tags:
        - BankReconciliations
      summary: Bulk soft-delete BankReconciliations by ids (atomic)
      operationId: bulkDeleteBankReconciliations
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_reconciliations/restore/bulk:
    post:
      tags:
        - BankReconciliations
      summary: Bulk restore BankReconciliations by ids (atomic)
      operationId: bulkRestoreBankReconciliations
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankReconciliationBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_reconciliations/restore/all:
    post:
      tags:
        - BankReconciliations
      summary: Restore all soft-deleted BankReconciliations
      operationId: restoreAllBankReconciliations
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/bank_reconciliations/trash/bulk:
    delete:
      tags:
        - BankReconciliations
      summary: Bulk permanently-delete BankReconciliations from trash by ids (atomic)
      operationId: bulkPermanentDeleteBankReconciliations
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_statement_imports:
    get:
      tags:
        - BankStatementImports
      summary: List BankStatementImports
      description: Get a paginated list of BankStatementImports with optional filtering and sorting
      operationId: listBankStatementImports
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImportList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - BankStatementImports
      summary: Create BankStatementImport
      description: Create a new BankStatementImport
      operationId: createBankStatementImport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankStatementImportRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/bank_statement_imports/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - BankStatementImports
      summary: Get BankStatementImport by ID
      operationId: getBankStatementImport
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImport'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - BankStatementImports
      summary: Update BankStatementImport (full)
      operationId: updateBankStatementImport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankStatementImportRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImport'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - BankStatementImports
      summary: Update BankStatementImport (partial)
      operationId: patchBankStatementImport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBankStatementImportRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImport'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - BankStatementImports
      summary: Delete BankStatementImport (soft)
      operationId: deleteBankStatementImport
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_statement_imports/bulk:
    post:
      tags:
        - BankStatementImports
      summary: Bulk create BankStatementImports
      operationId: bulkCreateBankStatementImports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBankStatementImportRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankStatementImport'
    put:
      tags:
        - BankStatementImports
      summary: Bulk update BankStatementImports (full, atomic)
      operationId: bulkUpdateBankStatementImports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBankStatementImportRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImportBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - BankStatementImports
      summary: Bulk partial-update BankStatementImports (atomic)
      operationId: bulkPatchBankStatementImports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImportBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_statement_imports/upsert:
    post:
      tags:
        - BankStatementImports
      summary: Upsert BankStatementImport
      operationId: upsertBankStatementImport
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankStatementImportRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImport'

  /api/v1/banking/bank_statement_imports/trash:
    get:
      tags:
        - BankStatementImports
      summary: List deleted BankStatementImports
      operationId: listDeletedBankStatementImports
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImportList'

  /api/v1/banking/bank_statement_imports/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - BankStatementImports
      summary: Restore deleted BankStatementImport
      operationId: restoreBankStatementImport
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImport'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_statement_imports/empty:
    delete:
      tags:
        - BankStatementImports
      summary: Empty trash for BankStatementImports
      operationId: emptyTrashBankStatementImports
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/bank_statement_imports/delete/bulk:
    post:
      tags:
        - BankStatementImports
      summary: Bulk soft-delete BankStatementImports by ids (atomic)
      operationId: bulkDeleteBankStatementImports
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_statement_imports/restore/bulk:
    post:
      tags:
        - BankStatementImports
      summary: Bulk restore BankStatementImports by ids (atomic)
      operationId: bulkRestoreBankStatementImports
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatementImportBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_statement_imports/restore/all:
    post:
      tags:
        - BankStatementImports
      summary: Restore all soft-deleted BankStatementImports
      operationId: restoreAllBankStatementImports
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/bank_statement_imports/trash/bulk:
    delete:
      tags:
        - BankStatementImports
      summary: Bulk permanently-delete BankStatementImports from trash by ids (atomic)
      operationId: bulkPermanentDeleteBankStatementImports
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_transactions:
    get:
      tags:
        - BankTransactions
      summary: List BankTransactions
      description: Get a paginated list of BankTransactions with optional filtering and sorting
      operationId: listBankTransactions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - BankTransactions
      summary: Create BankTransaction
      description: Create a new BankTransaction
      operationId: createBankTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankTransactionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/bank_transactions/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - BankTransactions
      summary: Get BankTransaction by ID
      operationId: getBankTransaction
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - BankTransactions
      summary: Update BankTransaction (full)
      operationId: updateBankTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankTransactionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - BankTransactions
      summary: Update BankTransaction (partial)
      operationId: patchBankTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBankTransactionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - BankTransactions
      summary: Delete BankTransaction (soft)
      operationId: deleteBankTransaction
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_transactions/bulk:
    post:
      tags:
        - BankTransactions
      summary: Bulk create BankTransactions
      operationId: bulkCreateBankTransactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBankTransactionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankTransaction'
    put:
      tags:
        - BankTransactions
      summary: Bulk update BankTransactions (full, atomic)
      operationId: bulkUpdateBankTransactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBankTransactionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - BankTransactions
      summary: Bulk partial-update BankTransactions (atomic)
      operationId: bulkPatchBankTransactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_transactions/upsert:
    post:
      tags:
        - BankTransactions
      summary: Upsert BankTransaction
      operationId: upsertBankTransaction
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBankTransactionRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'

  /api/v1/banking/bank_transactions/trash:
    get:
      tags:
        - BankTransactions
      summary: List deleted BankTransactions
      operationId: listDeletedBankTransactions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionList'

  /api/v1/banking/bank_transactions/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - BankTransactions
      summary: Restore deleted BankTransaction
      operationId: restoreBankTransaction
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransaction'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/bank_transactions/empty:
    delete:
      tags:
        - BankTransactions
      summary: Empty trash for BankTransactions
      operationId: emptyTrashBankTransactions
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/bank_transactions/delete/bulk:
    post:
      tags:
        - BankTransactions
      summary: Bulk soft-delete BankTransactions by ids (atomic)
      operationId: bulkDeleteBankTransactions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_transactions/restore/bulk:
    post:
      tags:
        - BankTransactions
      summary: Bulk restore BankTransactions by ids (atomic)
      operationId: bulkRestoreBankTransactions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankTransactionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/bank_transactions/restore/all:
    post:
      tags:
        - BankTransactions
      summary: Restore all soft-deleted BankTransactions
      operationId: restoreAllBankTransactions
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/bank_transactions/trash/bulk:
    delete:
      tags:
        - BankTransactions
      summary: Bulk permanently-delete BankTransactions from trash by ids (atomic)
      operationId: bulkPermanentDeleteBankTransactions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/fx_gain_losses:
    get:
      tags:
        - FxGainLosses
      summary: List FxGainLosses
      description: Get a paginated list of FxGainLosses with optional filtering and sorting
      operationId: listFxGainLosses
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLossList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - FxGainLosses
      summary: Create FxGainLoss
      description: Create a new FxGainLoss
      operationId: createFxGainLoss
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFxGainLossRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLoss'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/fx_gain_losses/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - FxGainLosses
      summary: Get FxGainLoss by ID
      operationId: getFxGainLoss
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLoss'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - FxGainLosses
      summary: Update FxGainLoss (full)
      operationId: updateFxGainLoss
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFxGainLossRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLoss'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - FxGainLosses
      summary: Update FxGainLoss (partial)
      operationId: patchFxGainLoss
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFxGainLossRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLoss'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - FxGainLosses
      summary: Delete FxGainLoss (soft)
      operationId: deleteFxGainLoss
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/fx_gain_losses/bulk:
    post:
      tags:
        - FxGainLosses
      summary: Bulk create FxGainLosses
      operationId: bulkCreateFxGainLosses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateFxGainLossRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FxGainLoss'
    put:
      tags:
        - FxGainLosses
      summary: Bulk update FxGainLosses (full, atomic)
      operationId: bulkUpdateFxGainLosses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateFxGainLossRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLossBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - FxGainLosses
      summary: Bulk partial-update FxGainLosses (atomic)
      operationId: bulkPatchFxGainLosses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLossBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/fx_gain_losses/upsert:
    post:
      tags:
        - FxGainLosses
      summary: Upsert FxGainLoss
      operationId: upsertFxGainLoss
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFxGainLossRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLoss'

  /api/v1/banking/fx_gain_losses/trash:
    get:
      tags:
        - FxGainLosses
      summary: List deleted FxGainLosses
      operationId: listDeletedFxGainLosses
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLossList'

  /api/v1/banking/fx_gain_losses/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - FxGainLosses
      summary: Restore deleted FxGainLoss
      operationId: restoreFxGainLoss
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLoss'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/fx_gain_losses/empty:
    delete:
      tags:
        - FxGainLosses
      summary: Empty trash for FxGainLosses
      operationId: emptyTrashFxGainLosses
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/fx_gain_losses/delete/bulk:
    post:
      tags:
        - FxGainLosses
      summary: Bulk soft-delete FxGainLosses by ids (atomic)
      operationId: bulkDeleteFxGainLosses
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/fx_gain_losses/restore/bulk:
    post:
      tags:
        - FxGainLosses
      summary: Bulk restore FxGainLosses by ids (atomic)
      operationId: bulkRestoreFxGainLosses
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxGainLossBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/fx_gain_losses/restore/all:
    post:
      tags:
        - FxGainLosses
      summary: Restore all soft-deleted FxGainLosses
      operationId: restoreAllFxGainLosses
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/fx_gain_losses/trash/bulk:
    delete:
      tags:
        - FxGainLosses
      summary: Bulk permanently-delete FxGainLosses from trash by ids (atomic)
      operationId: bulkPermanentDeleteFxGainLosses
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/reconcile_presets:
    get:
      tags:
        - ReconcilePresets
      summary: List ReconcilePresets
      description: Get a paginated list of ReconcilePresets with optional filtering and sorting
      operationId: listReconcilePresets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePresetList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - ReconcilePresets
      summary: Create ReconcilePreset
      description: Create a new ReconcilePreset
      operationId: createReconcilePreset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReconcilePresetRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePreset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/banking/reconcile_presets/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - ReconcilePresets
      summary: Get ReconcilePreset by ID
      operationId: getReconcilePreset
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePreset'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - ReconcilePresets
      summary: Update ReconcilePreset (full)
      operationId: updateReconcilePreset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReconcilePresetRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePreset'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - ReconcilePresets
      summary: Update ReconcilePreset (partial)
      operationId: patchReconcilePreset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchReconcilePresetRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePreset'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - ReconcilePresets
      summary: Delete ReconcilePreset (soft)
      operationId: deleteReconcilePreset
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/reconcile_presets/bulk:
    post:
      tags:
        - ReconcilePresets
      summary: Bulk create ReconcilePresets
      operationId: bulkCreateReconcilePresets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateReconcilePresetRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReconcilePreset'
    put:
      tags:
        - ReconcilePresets
      summary: Bulk update ReconcilePresets (full, atomic)
      operationId: bulkUpdateReconcilePresets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateReconcilePresetRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePresetBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - ReconcilePresets
      summary: Bulk partial-update ReconcilePresets (atomic)
      operationId: bulkPatchReconcilePresets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePresetBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/reconcile_presets/upsert:
    post:
      tags:
        - ReconcilePresets
      summary: Upsert ReconcilePreset
      operationId: upsertReconcilePreset
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReconcilePresetRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePreset'

  /api/v1/banking/reconcile_presets/trash:
    get:
      tags:
        - ReconcilePresets
      summary: List deleted ReconcilePresets
      operationId: listDeletedReconcilePresets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePresetList'

  /api/v1/banking/reconcile_presets/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - ReconcilePresets
      summary: Restore deleted ReconcilePreset
      operationId: restoreReconcilePreset
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePreset'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/banking/reconcile_presets/empty:
    delete:
      tags:
        - ReconcilePresets
      summary: Empty trash for ReconcilePresets
      operationId: emptyTrashReconcilePresets
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/banking/reconcile_presets/delete/bulk:
    post:
      tags:
        - ReconcilePresets
      summary: Bulk soft-delete ReconcilePresets by ids (atomic)
      operationId: bulkDeleteReconcilePresets
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/reconcile_presets/restore/bulk:
    post:
      tags:
        - ReconcilePresets
      summary: Bulk restore ReconcilePresets by ids (atomic)
      operationId: bulkRestoreReconcilePresets
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcilePresetBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/banking/reconcile_presets/restore/all:
    post:
      tags:
        - ReconcilePresets
      summary: Restore all soft-deleted ReconcilePresets
      operationId: restoreAllReconcilePresets
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/banking/reconcile_presets/trash/bulk:
    delete:
      tags:
        - ReconcilePresets
      summary: Bulk permanently-delete ReconcilePresets from trash by ids (atomic)
      operationId: bulkPermanentDeleteReconcilePresets
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    Bank:
      type: object
      required:
        - id
        - name
        - country
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 140
        swift_bic:
          nullable: true
          type: string
          maxLength: 11
        country:
          type: string
          maxLength: 2
        status:
          type: string
        metadata:
          type: object

    BankBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bank'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBankRequest:
      type: object
      required:
        - name
        - country
        - status
        - metadata
      properties:
        name:
          type: string
          maxLength: 140
        swift_bic:
          nullable: true
          type: string
          maxLength: 11
        country:
          type: string
          maxLength: 2
        status:
          type: string
        metadata:
          type: object

    UpdateBankRequest:
      type: object
      required:
        - name
        - country
        - status
        - metadata
      properties:
        name:
          type: string
          maxLength: 140
        swift_bic:
          nullable: true
          type: string
          maxLength: 11
        country:
          type: string
          maxLength: 2
        status:
          type: string
        metadata:
          type: object

    PatchBankRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 140
        swift_bic:
          nullable: true
          type: string
          maxLength: 11
        country:
          type: string
          maxLength: 2
        status:
          type: string
        metadata:
          type: object

    BankList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Bank'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    BankAccount:
      type: object
      required:
        - id
        - bank_id
        - account_name
        - account_number
        - gl_account_id
        - clearing_account_id
        - currency
        - account_type
        - is_default
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        branch_id:
          nullable: true
          type: string
          format: uuid
        bank_id:
          type: string
          format: uuid
        account_name:
          type: string
          maxLength: 140
        account_number:
          type: string
          maxLength: 60
        gl_account_id:
          type: string
          format: uuid
        clearing_account_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        account_type:
          type: string
        is_default:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    BankAccountBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBankAccountRequest:
      type: object
      required:
        - bank_id
        - account_name
        - account_number
        - gl_account_id
        - clearing_account_id
        - currency
        - account_type
        - is_default
        - status
        - metadata
      properties:
        branch_id:
          nullable: true
          type: string
          format: uuid
        bank_id:
          type: string
          format: uuid
        account_name:
          type: string
          maxLength: 140
        account_number:
          type: string
          maxLength: 60
        gl_account_id:
          type: string
          format: uuid
        clearing_account_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        account_type:
          type: string
        is_default:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    UpdateBankAccountRequest:
      type: object
      required:
        - bank_id
        - account_name
        - account_number
        - gl_account_id
        - clearing_account_id
        - currency
        - account_type
        - is_default
        - status
        - metadata
      properties:
        branch_id:
          nullable: true
          type: string
          format: uuid
        bank_id:
          type: string
          format: uuid
        account_name:
          type: string
          maxLength: 140
        account_number:
          type: string
          maxLength: 60
        gl_account_id:
          type: string
          format: uuid
        clearing_account_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        account_type:
          type: string
        is_default:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    PatchBankAccountRequest:
      type: object
      properties:
        branch_id:
          nullable: true
          type: string
          format: uuid
        bank_id:
          type: string
          format: uuid
        account_name:
          type: string
          maxLength: 140
        account_number:
          type: string
          maxLength: 60
        gl_account_id:
          type: string
          format: uuid
        clearing_account_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        account_type:
          type: string
        is_default:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    BankAccountList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    BankClearance:
      type: object
      required:
        - id
        - bank_transaction_id
        - matched_source_type
        - matched_source_id
        - matched_amount
        - match_method
        - clearance_date
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bank_transaction_id:
          type: string
          format: uuid
        matched_source_type:
          type: string
        matched_source_id:
          type: string
          format: uuid
        matched_amount:
          type: string
        match_method:
          type: string
        clearance_date:
          type: string
          format: date
        accounting_post_id:
          nullable: true
          type: string
          format: uuid
        journal_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    BankClearanceBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankClearance'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBankClearanceRequest:
      type: object
      required:
        - bank_transaction_id
        - matched_source_type
        - matched_source_id
        - matched_amount
        - match_method
        - clearance_date
        - metadata
      properties:
        bank_transaction_id:
          type: string
          format: uuid
        matched_source_type:
          type: string
        matched_source_id:
          type: string
          format: uuid
        matched_amount:
          type: string
        match_method:
          type: string
        clearance_date:
          type: string
          format: date
        accounting_post_id:
          nullable: true
          type: string
          format: uuid
        journal_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    UpdateBankClearanceRequest:
      type: object
      required:
        - bank_transaction_id
        - matched_source_type
        - matched_source_id
        - matched_amount
        - match_method
        - clearance_date
        - metadata
      properties:
        bank_transaction_id:
          type: string
          format: uuid
        matched_source_type:
          type: string
        matched_source_id:
          type: string
          format: uuid
        matched_amount:
          type: string
        match_method:
          type: string
        clearance_date:
          type: string
          format: date
        accounting_post_id:
          nullable: true
          type: string
          format: uuid
        journal_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    PatchBankClearanceRequest:
      type: object
      properties:
        bank_transaction_id:
          type: string
          format: uuid
        matched_source_type:
          type: string
        matched_source_id:
          type: string
          format: uuid
        matched_amount:
          type: string
        match_method:
          type: string
        clearance_date:
          type: string
          format: date
        accounting_post_id:
          nullable: true
          type: string
          format: uuid
        journal_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    BankClearanceList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankClearance'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    BankReconciliation:
      type: object
      required:
        - id
        - bank_account_id
        - from_date
        - to_date
        - statement_closing_balance
        - ledger_balance
        - computed_difference
        - unreconciled_count
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bank_account_id:
          type: string
          format: uuid
        from_date:
          type: string
          format: date
        to_date:
          type: string
          format: date
        statement_closing_balance:
          type: string
        ledger_balance:
          type: string
        computed_difference:
          type: string
        unreconciled_count:
          type: integer
          format: int32
        status:
          type: string
        preset_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    BankReconciliationBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankReconciliation'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBankReconciliationRequest:
      type: object
      required:
        - bank_account_id
        - from_date
        - to_date
        - statement_closing_balance
        - ledger_balance
        - computed_difference
        - unreconciled_count
        - status
        - metadata
      properties:
        bank_account_id:
          type: string
          format: uuid
        from_date:
          type: string
          format: date
        to_date:
          type: string
          format: date
        statement_closing_balance:
          type: string
        ledger_balance:
          type: string
        computed_difference:
          type: string
        unreconciled_count:
          type: integer
          format: int32
        status:
          type: string
        preset_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    UpdateBankReconciliationRequest:
      type: object
      required:
        - bank_account_id
        - from_date
        - to_date
        - statement_closing_balance
        - ledger_balance
        - computed_difference
        - unreconciled_count
        - status
        - metadata
      properties:
        bank_account_id:
          type: string
          format: uuid
        from_date:
          type: string
          format: date
        to_date:
          type: string
          format: date
        statement_closing_balance:
          type: string
        ledger_balance:
          type: string
        computed_difference:
          type: string
        unreconciled_count:
          type: integer
          format: int32
        status:
          type: string
        preset_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    PatchBankReconciliationRequest:
      type: object
      properties:
        bank_account_id:
          type: string
          format: uuid
        from_date:
          type: string
          format: date
        to_date:
          type: string
          format: date
        statement_closing_balance:
          type: string
        ledger_balance:
          type: string
        computed_difference:
          type: string
        unreconciled_count:
          type: integer
          format: int32
        status:
          type: string
        preset_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    BankReconciliationList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankReconciliation'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    BankStatementImport:
      type: object
      required:
        - id
        - bank_account_id
        - source_format
        - statement_period_start
        - statement_period_end
        - opening_balance
        - closing_balance
        - status
        - row_count
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bank_account_id:
          type: string
          format: uuid
        source_format:
          type: string
        statement_period_start:
          type: string
          format: date
        statement_period_end:
          type: string
          format: date
        opening_balance:
          type: string
        closing_balance:
          type: string
        file_ref:
          nullable: true
          type: string
          maxLength: 300
        status:
          type: string
        row_count:
          type: integer
          format: int32
        metadata:
          type: object

    BankStatementImportBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankStatementImport'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBankStatementImportRequest:
      type: object
      required:
        - bank_account_id
        - source_format
        - statement_period_start
        - statement_period_end
        - opening_balance
        - closing_balance
        - status
        - row_count
        - metadata
      properties:
        bank_account_id:
          type: string
          format: uuid
        source_format:
          type: string
        statement_period_start:
          type: string
          format: date
        statement_period_end:
          type: string
          format: date
        opening_balance:
          type: string
        closing_balance:
          type: string
        file_ref:
          nullable: true
          type: string
          maxLength: 300
        status:
          type: string
        row_count:
          type: integer
          format: int32
        metadata:
          type: object

    UpdateBankStatementImportRequest:
      type: object
      required:
        - bank_account_id
        - source_format
        - statement_period_start
        - statement_period_end
        - opening_balance
        - closing_balance
        - status
        - row_count
        - metadata
      properties:
        bank_account_id:
          type: string
          format: uuid
        source_format:
          type: string
        statement_period_start:
          type: string
          format: date
        statement_period_end:
          type: string
          format: date
        opening_balance:
          type: string
        closing_balance:
          type: string
        file_ref:
          nullable: true
          type: string
          maxLength: 300
        status:
          type: string
        row_count:
          type: integer
          format: int32
        metadata:
          type: object

    PatchBankStatementImportRequest:
      type: object
      properties:
        bank_account_id:
          type: string
          format: uuid
        source_format:
          type: string
        statement_period_start:
          type: string
          format: date
        statement_period_end:
          type: string
          format: date
        opening_balance:
          type: string
        closing_balance:
          type: string
        file_ref:
          nullable: true
          type: string
          maxLength: 300
        status:
          type: string
        row_count:
          type: integer
          format: int32
        metadata:
          type: object

    BankStatementImportList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankStatementImport'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    BankTransaction:
      type: object
      required:
        - id
        - bank_account_id
        - import_id
        - txn_date
        - deposit
        - withdrawal
        - currency
        - status
        - allocated_amount
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bank_account_id:
          type: string
          format: uuid
        import_id:
          type: string
          format: uuid
        txn_date:
          type: string
          format: date
        value_date:
          nullable: true
          type: string
          format: date
        description:
          nullable: true
          type: string
          maxLength: 300
        reference_no:
          nullable: true
          type: string
          maxLength: 140
        deposit:
          type: string
        withdrawal:
          type: string
        currency:
          type: string
          maxLength: 3
        status:
          type: string
        allocated_amount:
          type: string
        metadata:
          type: object

    BankTransactionBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankTransaction'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBankTransactionRequest:
      type: object
      required:
        - bank_account_id
        - import_id
        - txn_date
        - deposit
        - withdrawal
        - currency
        - status
        - allocated_amount
        - metadata
      properties:
        bank_account_id:
          type: string
          format: uuid
        import_id:
          type: string
          format: uuid
        txn_date:
          type: string
          format: date
        value_date:
          nullable: true
          type: string
          format: date
        description:
          nullable: true
          type: string
          maxLength: 300
        reference_no:
          nullable: true
          type: string
          maxLength: 140
        deposit:
          type: string
        withdrawal:
          type: string
        currency:
          type: string
          maxLength: 3
        status:
          type: string
        allocated_amount:
          type: string
        metadata:
          type: object

    UpdateBankTransactionRequest:
      type: object
      required:
        - bank_account_id
        - import_id
        - txn_date
        - deposit
        - withdrawal
        - currency
        - status
        - allocated_amount
        - metadata
      properties:
        bank_account_id:
          type: string
          format: uuid
        import_id:
          type: string
          format: uuid
        txn_date:
          type: string
          format: date
        value_date:
          nullable: true
          type: string
          format: date
        description:
          nullable: true
          type: string
          maxLength: 300
        reference_no:
          nullable: true
          type: string
          maxLength: 140
        deposit:
          type: string
        withdrawal:
          type: string
        currency:
          type: string
          maxLength: 3
        status:
          type: string
        allocated_amount:
          type: string
        metadata:
          type: object

    PatchBankTransactionRequest:
      type: object
      properties:
        bank_account_id:
          type: string
          format: uuid
        import_id:
          type: string
          format: uuid
        txn_date:
          type: string
          format: date
        value_date:
          nullable: true
          type: string
          format: date
        description:
          nullable: true
          type: string
          maxLength: 300
        reference_no:
          nullable: true
          type: string
          maxLength: 140
        deposit:
          type: string
        withdrawal:
          type: string
        currency:
          type: string
          maxLength: 3
        status:
          type: string
        allocated_amount:
          type: string
        metadata:
          type: object

    BankTransactionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BankTransaction'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    FxGainLoss:
      type: object
      required:
        - id
        - matched_source_id
        - currency
        - original_rate
        - realised_rate
        - base_amount_delta
        - direction
        - fx_account_id
        - metadata
      properties:
        id:
          type: string
          format: uuid
        bank_clearance_id:
          nullable: true
          type: string
          format: uuid
        matched_source_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        original_rate:
          type: string
        realised_rate:
          type: string
        base_amount_delta:
          type: string
        direction:
          type: string
        fx_account_id:
          type: string
          format: uuid
        metadata:
          type: object

    FxGainLossBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FxGainLoss'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateFxGainLossRequest:
      type: object
      required:
        - matched_source_id
        - currency
        - original_rate
        - realised_rate
        - base_amount_delta
        - direction
        - fx_account_id
        - metadata
      properties:
        bank_clearance_id:
          nullable: true
          type: string
          format: uuid
        matched_source_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        original_rate:
          type: string
        realised_rate:
          type: string
        base_amount_delta:
          type: string
        direction:
          type: string
        fx_account_id:
          type: string
          format: uuid
        metadata:
          type: object

    UpdateFxGainLossRequest:
      type: object
      required:
        - matched_source_id
        - currency
        - original_rate
        - realised_rate
        - base_amount_delta
        - direction
        - fx_account_id
        - metadata
      properties:
        bank_clearance_id:
          nullable: true
          type: string
          format: uuid
        matched_source_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        original_rate:
          type: string
        realised_rate:
          type: string
        base_amount_delta:
          type: string
        direction:
          type: string
        fx_account_id:
          type: string
          format: uuid
        metadata:
          type: object

    PatchFxGainLossRequest:
      type: object
      properties:
        bank_clearance_id:
          nullable: true
          type: string
          format: uuid
        matched_source_id:
          type: string
          format: uuid
        currency:
          type: string
          maxLength: 3
        original_rate:
          type: string
        realised_rate:
          type: string
        base_amount_delta:
          type: string
        direction:
          type: string
        fx_account_id:
          type: string
          format: uuid
        metadata:
          type: object

    FxGainLossList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FxGainLoss'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    ReconcilePreset:
      type: object
      required:
        - id
        - name
        - priority
        - match_on
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 80
        note:
          nullable: true
          type: string
          maxLength: 255
        priority:
          type: integer
          format: int32
        match_on:
          type: string
        tolerance_percent:
          nullable: true
          type: string
        days_window:
          nullable: true
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    ReconcilePresetBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReconcilePreset'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateReconcilePresetRequest:
      type: object
      required:
        - name
        - priority
        - match_on
        - status
        - metadata
      properties:
        name:
          type: string
          maxLength: 80
        note:
          nullable: true
          type: string
          maxLength: 255
        priority:
          type: integer
          format: int32
        match_on:
          type: string
        tolerance_percent:
          nullable: true
          type: string
        days_window:
          nullable: true
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    UpdateReconcilePresetRequest:
      type: object
      required:
        - name
        - priority
        - match_on
        - status
        - metadata
      properties:
        name:
          type: string
          maxLength: 80
        note:
          nullable: true
          type: string
          maxLength: 255
        priority:
          type: integer
          format: int32
        match_on:
          type: string
        tolerance_percent:
          nullable: true
          type: string
        days_window:
          nullable: true
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    PatchReconcilePresetRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 80
        note:
          nullable: true
          type: string
          maxLength: 255
        priority:
          type: integer
          format: int32
        match_on:
          type: string
        tolerance_percent:
          nullable: true
          type: string
        days_window:
          nullable: true
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    ReconcilePresetList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReconcilePreset'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          example: 100
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
        total_pages:
          type: integer
          example: 5

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        message:
          type: string
          example: Invalid input data
        details:
          type: object
          additionalProperties: true

  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid

    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    SortByParam:
      name: sort_by
      in: query
      schema:
        type: string

    SortOrderParam:
      name: sort_order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: asc

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  requestBodies:
    BatchIds:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [ids]
            properties:
              ids:
                type: array
                items: { type: string }

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

security:
  - bearerAuth: []