Find candidate transactions
find_candidate_transactionsFor an OUTSTANDING or OVERDUE invoice or bill, surface the candidate bank transactions that could settle it: OPEN (unreconciled) transactions within ±7 days of the document's due date whose amount matches its outstanding balance. Returns {documentid, direction, duedate, amount, doccurrency, basecurrency, candidates [transactions], best {transactionid, confidence 0.0-1.0, reason, proposal}} — best is the single strongest match (confidence >= 0.9 is a confident match). A bank line in another currency is offered when, converted at its own date's rate, it lands within 3% of the balance; its best never reaches 0.9 and carries requires_confirmation=true, because settling it needs the FX gain/loss the user confirms. Each candidate (and best) also carries a proposal: the adjusting line settling with it would require — {type :bank-charge|:fx-gain|:fx-loss, amount, currency, …} when the payment does not land exactly on the outstanding balance (a bank charge when the currencies match, an FX gain/loss when they differ), null for an exact match, or {type :indeterminate} when the dated FX rate is unavailable. READ-ONLY: it suggests a match and the adjusting line, never records either (settle bills via settle_bills; the adjusting line is for the user to confirm). To settle an invoice, first check whether the candidate's bank line already has its own income: list_transactions shows it in that line's $incomeids. If it does, settle with save_income, id = that income and accountid = the invoice id. Use record_document_payment only when the line has no income, because it always creates a new income and would count the money twice. Pass the document id (cont-… or inv-…). Run this whenever you report an overdue/outstanding invoice or bill so the likely payment is offered alongside it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| documentid | Yes | The invoice / bill / purchase document id (cont-… or inv-…) to find candidate settling bank transactions for. |