Banking
Bank accounts, imported statements and bank transactions (read-only; statement import via CAMT.053/CODA).
List the organization's bank accounts
GET /api/v1/bank-accounts
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_accounts.view
Banking module. Requires the bank_accounts.view scope. Accounts are created/managed in the UI; the API surface is read-only plus statement import.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
status |
query | string | non | |
per_page |
query | string | non |
Réponses
| Statut | Description |
|---|---|
| 200 | Paginated bank accounts |
| 422 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-accounts" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Show one bank account
GET /api/v1/bank-accounts/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_accounts.view
Returns 404 for accounts outside the requesting organization (IDOR guard).
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Bank account |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-accounts/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Upload and import a bank statement file (CSV, CAMT.053, CODA)
POST /api/v1/bank-accounts/{id}/import-statement
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.import
Requires the bank_transactions.import scope. Parses the file and ingests transactions with idempotent dedupe (re-importing the same file is a no-op). Returns the import session summary. Archived accounts reject new statements (422).
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 201 | Import session summary |
| 422 | |
| 403 | Token lacks the bank_transactions.import scope |
| 404 | Account not found in this organization |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/bank-accounts/{id}/import-statement" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Reconciliation report for an account and period
GET /api/v1/bank-accounts/{id}/reconciliation-report
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_accounts.view
Matched vs unmatched (count + sum) per status for the period, reconciliation rate, and a closing-balance check: the sum of ALL imported lines up to the period end against the provider-reported balance snapshot. Requires the bank_accounts.view scope.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
from |
query | string | oui | |
to |
query | string | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Report |
| 422 | |
| 404 | Account not found in this organization |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-accounts/{id}/reconciliation-report" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
List bank rules
GET /api/v1/bank-rules
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_rules.view
All rules of the organization, priority order. Requires the bank_rules.view scope.
Réponses
| Statut | Description |
|---|---|
| 200 | Rules |
| 422 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-rules" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create a bank rule
POST /api/v1/bank-rules
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_rules.create
Conditions ALL must match; the action describes the money record to create. Rules suggest by default — auto_add (default false) books matching lines automatically at import, and only when no invoice or expense matches (a rule never shadows a document match). Referenced bank_account_id / actions.counterparty_id must belong to the organization (404 otherwise). Requires the bank_rules.create scope.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
name |
string | oui | |
is_active |
boolean | non | |
bank_account_id |
integer | non | |
direction |
string | non | |
conditions |
array | oui | |
actions |
object | oui | |
auto_add |
boolean | non | |
priority |
integer | non |
Réponses
| Statut | Description |
|---|---|
| 201 | Created rule |
| 422 | Validation error (e.g. unknown condition type) |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/bank-rules" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"is_active": true,
"bank_account_id": 1,
"direction": "string",
"conditions": [],
"actions": {},
"auto_add": true,
"priority": 1
}'
Show one bank rule
GET /api/v1/bank-rules/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_rules.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Rule |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-rules/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Update a bank rule
PUT /api/v1/bank-rules/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_rules.update
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
name |
string | oui | |
is_active |
boolean | non | |
bank_account_id |
integer | non | |
direction |
string | non | |
conditions |
array | oui | |
actions |
object | oui | |
auto_add |
boolean | non | |
priority |
integer | non |
Réponses
| Statut | Description |
|---|---|
| 200 | Updated rule |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X PUT "https://kworia.com/api/v1/bank-rules/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"is_active": true,
"bank_account_id": 1,
"direction": "string",
"conditions": [],
"actions": {},
"auto_add": true,
"priority": 1
}'
Delete a bank rule
DELETE /api/v1/bank-rules/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_rules.delete
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Deleted |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X DELETE "https://kworia.com/api/v1/bank-rules/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
List imported bank transactions
GET /api/v1/bank-transactions
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.view
Requires the bank_transactions.view scope. A bank_account_id filter pointing at another organization's account returns 404 (IDOR guard).
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
bank_account_id |
query | integer | non | |
status |
query | string | non | |
date_from |
query | string | non | |
date_to |
query | string | non | |
per_page |
query | string | non |
Réponses
| Statut | Description |
|---|---|
| 200 | Paginated bank transactions |
| 422 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-transactions" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Bulk confirm suggested bank transactions
POST /api/v1/bank-transactions/bulk-confirm
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.update
Per line the TOP document suggestion is confirmed; a matching bank rule is the fallback when the matcher is empty; anything ambiguous or already claimed is skipped — bulk never guesses. Concurrency-safe: the reconciliation transition is compare-and-swap, so a concurrent confirm makes the loser a skip, never a double payment. Requires the bank_transactions.update scope.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
transaction_ids |
array | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Counts |
| 422 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/bank-transactions/bulk-confirm" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"transaction_ids": []
}'
Show one bank transaction
GET /api/v1/bank-transactions/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Bank transaction |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-transactions/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create an expense or invoice from a bank transaction
POST /api/v1/bank-transactions/{id}/create-document
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.update
The one sanctioned reconciliation-drives-documents flow: creates an expense (debit) or a single-line invoice (credit) through the regular Invoicing services and confirms the match in the same database transaction. The document is born reconciled with created_money_record=true, so a later unmatch reverses the payment but keeps the document. A new counterparty is created when counterparty_name is given without counterparty_id (the bank IBAN is stored on it for future matching). Requires the bank_transactions.update scope.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
counterparty_id |
integer | non | Existing customer/vendor of the requesting organization |
counterparty_name |
string | non | Name for a NEW counterparty; defaults to the bank counterparty name |
description |
string | non | Defaults to the bank remittance text |
date |
string | non | Defaults to the booking date |
category |
string | non | Expense category (debits only) |
Réponses
| Statut | Description |
|---|---|
| 201 | Created match (document ids in invoice_id/expense_id, created_money_record=true) |
| 422 | Already matched, foreign counterparty, or missing customer for an invoice |
| 404 | Transaction not found in this organization |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/bank-transactions/{id}/create-document" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"counterparty_id": 1,
"counterparty_name": "string",
"description": "string",
"date": "string",
"category": "string"
}'
Prefill for creating a document from a bank transaction
GET /api/v1/bank-transactions/{id}/document-prefill
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.view
Everything a create-expense/create-invoice form can be prefilled with: document type by amount sign (debit=expense, credit=invoice), absolute amount, currency, booking date, remittance text, and a resolved counterparty (exact IBAN match first, then fuzzy name against the org's customers/vendors). Requires the bank_transactions.view scope.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Prefill payload |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-transactions/{id}/document-prefill" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Confirm a reconciliation match
POST /api/v1/bank-transactions/{id}/match
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.update
Records a Payment (invoice) or marks the expense paid; fee/writeoff deltas post to the ledger. Requires the bank_transactions.update scope. Concurrent confirms on one transaction serialize - losers receive 422. Cross-currency matches are rejected (422).
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
invoice_id |
integer | non | Exactly one of invoice_id / expense_id / credit_note_id |
expense_id |
integer | non | |
credit_note_id |
integer | non | Sent credit note settled by an outgoing refund (debit lines) — applied on confirm, reverted on unmatch |
allocated_amount |
number | non | Defaults to the transaction amount (+ fee_adjustment) |
fee_adjustment |
number | non | |
type |
string | non | |
link_payment_id |
integer | non | |
allow_overpayment |
boolean | non | Explicitly allow paying beyond the invoice balance — a duplicate customer payment. Default false; without it a payment beyond the balance is rejected (422). Recorded as signals.overpayment=true on the match. |
Réponses
| Statut | Description |
|---|---|
| 201 | Created match |
| 422 | Already matched, cross-currency, or allocation exceeds the open balance |
| 404 | Transaction or document not found in this organization |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/bank-transactions/{id}/match" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": 1,
"expense_id": 1,
"credit_note_id": 1,
"allocated_amount": 1,
"fee_adjustment": 1,
"type": "string",
"link_payment_id": 1,
"allow_overpayment": true
}'
Ranked reconciliation match suggestions
GET /api/v1/bank-transactions/{id}/suggestions
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.view
Matching engine output: candidates with confidence bands (suggest-only) and a per-suggestion signal breakdown (structured_reference, amount_exact, counterparty_name, fee_delta, reference_in_description). Requires the bank_transactions.view scope.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | Transaction + ranked suggestions |
| 404 | Not found (or belongs to another organization) |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/bank-transactions/{id}/suggestions" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Undo the active match on a transaction
POST /api/v1/bank-transactions/{id}/unmatch
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : bank_transactions.update
Reverses the payment record and returns the line to the queue; the match row is kept as an audit record. Requires the bank_transactions.update scope.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
reason |
string | non |
Réponses
| Statut | Description |
|---|---|
| 200 | The match, now status=unmatched |
| 422 | No active match on this transaction |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/bank-transactions/{id}/unmatch" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"reason": "string"
}'