gnubok
Kom igång

Reconciliation

Run bank-to-ledger reconciliation and read the current matching status.

Endpoints

GET /api/v1/companies/:companyId/reconciliation/bank/status {#get-reconciliation-bank-status}

reconciliation.bank.status · scope transactions:read

Bank-reconciliation health snapshot.

Returns matched / unmatched counts and the balance delta between the bank ledger and the GL for the requested window. Optional ?date_from / ?date_to (default: company history).

Use when: You're building a dashboard widget, an audit report, or a pre-close check that needs to know how many bank transactions are still unbooked.

Don't use for: Running the matcher — that's POST /reconciliation/bank/run. Per-transaction detail — use the transaction list with ?status=unbooked.

Pitfalls

  • A non-zero difference is normal between sync runs (uncleared cheques, in-flight transfers). Investigate only if it persists across reconciliations.
  • total_unmatched_amount is the absolute sum — positive even when the unmatched rows include both credits and debits.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Example response

{
  "data": {
    "matched_transactions": 142,
    "unmatched_transactions": 3,
    "unmatched_gl_lines": 2,
    "total_unmatched_amount": 1850,
    "bank_balance": 50000,
    "gl_balance": 48150,
    "difference": 1850
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/reconciliation/bank/run {#post-reconciliation-bank-run}

reconciliation.bank.run · scope transactions:write

Run the bank-reconciliation matcher.

Walks all unbooked bank transactions in the requested date range and pairs them with open GL lines (1930-side) by amount + date proximity. Applies confirmed matches by setting transactions.journal_entry_id (the GL row already exists). Dry-runnable.

Use when: You want to auto-match outstanding bank transactions against existing journal entries — typically as the closing step of a sync. Dry-run first to inspect proposed matches.

Don't use for: Creating new journal entries — this only links bank transactions to existing GL lines. Matching to invoices — use :match-invoice or :match-supplier-invoice for explicit invoice payments.

Pitfalls

  • date_from / date_to default to the company's full bank history if omitted. Specify a window for predictable performance.
  • Idempotency-Key is mandatory.
  • matches.confidence is between 0 and 1; the matcher only applies matches above the internal threshold (currently ~0.85).

Risk: medium · Idempotent: yes · Reversible: no · Dry-run supported: yes

Example request

{
  "date_from": "2026-05-01",
  "date_to": "2026-05-31"
}

Example response

{
  "data": {
    "matches": [],
    "applied": 0,
    "errors": []
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}