Bank Imports

Reconcile a single bank transaction

Update a transaction's reconciliation state. Setting status=MATCHED with one or more invoices, an expense or a revenue posts the corresponding payment journal entries (one per invoice). Setting it back to UNMATCHED or IGNORED reverses all of them. Setting status=CATEGORIZED with bookToAccountId posts a direct booking against the chosen chart-of-accounts account. Optional adjustments book bank fees / rounding alongside the main entry. Mutations on transactions whose journal date falls in a closed fiscal year are rejected.

put/bank-transactions/{id}

Request

  • Base URL: https://api.lumabill.ch/v1
  • URL: https://api.lumabill.ch/v1/bank-transactions/{id}
  • Auth: HTTP bearer

Request body

status'MATCHED' | 'UNMATCHED' | 'CATEGORIZED' | 'IGNORED' required
matchedInvoiceIdstring uuid nullable

Legacy single-invoice match, treated as matchedInvoiceIds = [id]. Do not send together with matchedInvoiceIds.

matchedInvoiceIdsstring[] nullable

Invoices paid by this bank transaction, in allocation order.

matchedExpenseIdstring uuid nullable

Legacy single-expense match, treated as matchedExpenseIds = [id]. Do not send together with matchedExpenseIds.

matchedExpenseIdsstring[] nullable

Expenses paid by this DEBIT bank transaction, in allocation order.

matchedRevenueIdstring uuid nullable
bookToAccountIdstring uuid nullable

Chart-of-accounts UUID (required when status=CATEGORIZED)

dryRunboolean

Preview: runs the exact booking (every check and refusal, the CHF value of the line, the released book value, the realized FX, the zero-saldo realization) in a transaction that is rolled back. Answers 200 { message, dryRun: true, fx? }; nothing is booked. Only for a request that books (status MATCHED with a document, or CATEGORIZED with bookToAccountId). A rate lookup during the preview may still fill the shared rate cache. Read strictly: true/false or the strings "true"/"false" (any case); any other value answers 400 and nothing is booked.

allowCrossCurrencyboolean

Confirms a cross-currency payment: a base-currency (CHF) line that settles a foreign-currency document. Without it such a match is refused with BANK_CURRENCY_MISMATCH and crossCurrencyPossible: true (see BankCurrencyMismatch). The CHF moved is the bank amount; the difference to the document's CHF book value is booked as realized FX. The rate it implies (bank amount per FW settled) must lie within 0.5x to 2x of the ESTV/BAZG rate of the value date, else 400 EXCHANGE_RATE_IMPLAUSIBLE (with impliedRate, officialRate, min, max). Read strictly like dryRun.

fwAmountnumber double

Cross-currency match only: the foreign-currency amount this line settles across the selected documents (default: everything still open). Positive; 400 INVALID_FW_AMOUNT otherwise. A part payment must send it: against everything open its implied rate is refused as EXCHANGE_RATE_IMPLAUSIBLE.

exchangeRatenumber double

Line on a foreign-currency bank account: override its CHF value with this rate (CHF per 1 unit of the line currency). Default: the statement's own CHF figure, else the ESTV/BAZG rate of the value date. Ignored in a cross-currency match.

baseAmountnumber double

Line on a foreign-currency bank account: the CHF amount that actually moved; wins over exchangeRate. Ignored in a cross-currency match.

Example request

{
  "adjustments": [
    {
      "description": "Bank fee",
      "amount": 5
    }
  ]
}

Response

Transaction updated (or, with dryRun, the booking previewed and rolled back). fx is present for a line on a foreign-currency bank account and for a confirmed cross-currency match.

messagestring required
dryRunboolean

Present (true) on a preview; nothing was booked

zeroSaldoSkipped'PRIOR_YEAR_NOT_CLOSED' | 'FX_ACCOUNT_MISSING'

Present when the booking emptied a foreign-currency bank account in FW but its residual CHF book value was not realized (zero-saldo rule): PRIOR_YEAR_NOT_CLOSED (the previous fiscal year is open, no Saldovortrag yet) or FX_ACCOUNT_MISSING (no FX result account). The booking itself is done.

Example response

{
  "message": "Transaction updated",
  "fx": {
    "currency": "CHF",
    "documents": [
      {
        "currency": "CHF"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.