Sign in

v1

latestOpenAPI 3.0.02026-07-2422987517.5 KB
Transaction

List transactions

Returns a paginated list of accounting-ledger transactions for the company. Each row is a unified projection of a card transaction, bank transfer, payment, commission, invoice or balance correction, and carries its rendición (expense-tracking) custom-column values.

Key features

  • Pagination: _start / _end (default 25 items). Content-Range and X-Total-Count headers describe the window.
  • Sorting: _field / _order. Sortable virtual fields include cartola_date (the default), merchant_name, card_name, card_last4, amount, target_amount, cumulative_balance and created_at.
  • Filtering: any column can be filtered with a plain value or a JSON operator string (e.g. {"$gte": ...}, {"$in": [...]}, {"$like": "%...%"}).
  • Cumulative balances: pass _with_cumulative_balances=true to inject running balances (target_cumulative_balance_with_commission). This requires a resolvable company.
  • Hide commissions: pass _hide_commissions=true to omit commission rows.

Amount encoding

Most monetary fields are serialized as strings of integer cents. exchange_rate is a human-formatted string; use exchange_rate_value for a machine-parseable rate.

Authorization

Non-admin callers see only transactions of companies where they hold the transactions_view permission, plus their own transactions. Scoping is per-user across the caller's permitted companies (via policy scope); the company-id header is not used to scope this list and an absent/mismatched header does not by itself produce a 401.

get/v1/transactions

Query parameters

_startinteger

If all the transactions where in an array, this would represent the index of the first item returned in the response

_endinteger

If all the transactions where in an array, this would represent the index of the last item returned in the response

_order'asc' | 'desc'

The order method, which can be ascending or descending

_fieldstring
Example:created_at

The field used to sort, the example illustrates a response that would be sorted by the creation date

_with_cumulative_balances'true' | 'false'

When true, injects running balances. Requires a resolvable company.

_hide_commissions'true' | 'false'

When true, omits commission rows from the list.

transaction_typestring
Example:{"$in": ["card_transactions", "banking_bank_transactions"]}

Filter by transaction type (plain value or JSON operator).

statusstring
Example:{"$in": ["approved", "declined"]}

Filter by status (plain value or JSON operator).

cartola_idstring uuid

Filter by the cartola a transaction is assigned to.

cartola_datestring
Example:{"$gte": "2025-01-01T00:00:00Z", "$lt": "2025-02-01T00:00:00Z"}

Filter by accounting date (JSON operators supported).

Headers

company-idstring uuid required

UUID of the company on whose behalf the request is made. Required for every Accounting endpoint. See The company-id header for details on how to obtain a value for this header and the error responses to expect when it is missing or invalid.

Response

Paginated list of transactions

idstring uuid required

The transaction id. This is the accounting_ledger_tx_id and is the identifier used by the file, label and reconciliation endpoints.

accounting_ledger_tx_idstring uuid

The underlying Accounting::LedgerTx id. Equal to id; exposed as a distinct field for clients that key off the ledger id explicitly.

company_idstring uuid

The company that owns the transaction.

user_idstring nullable

The user associated with the transaction, if any.

account_idstring uuid nullable

The account the transaction belongs to.

accountobject nullable

The account record associated with the transaction.

card_idstring nullable

The card id, for card transactions.

card_namestring nullable

The card name, present only for card_transactions.

card_last4string nullable

Last four digits of the card, present only for card_transactions.

descriptionstring nullable

Human description of the transaction.

commentsstring nullable

Internal comments/notes on the transaction.

transaction_type'card_transactions' | 'banking_bank_transactions' | 'payments' | 'commissions' | 'commission_refunds' | 'invoices' required

The kind of underlying record projected into the ledger.

statusstring required

Current status of the transaction (values depend on the source type).

status_reasonstring nullable

Reason for the current status, present only for card_transactions.

amountstring nullable

Source amount in integer cents, serialized as a string.

currencystring nullable

Source currency (ISO 4217).

chargestring

Negative (or zero) side of the amount in integer cents (outflow), serialized as a string ("0" when there is no charge side).

depositstring

Positive (or zero) side of the amount in integer cents (inflow), serialized as a string ("0" when there is no deposit side).

amount_in_clpstring nullable

Amount converted to CLP in integer cents, serialized as a string.

exchange_ratestring

Human-formatted FX rate applied to the row (thousands separator ,, decimal .). Empty string when the rate is genuinely unknown. Use exchange_rate_value for a machine-parseable rate.

exchange_rate_valuestring nullable

Machine-parseable FX rate (no thousands separator), serialized as a string to preserve precision, or null for cross-currency rows whose rate is genuinely unknown.

target_amountstring nullable

Amount in the target currency in integer cents, serialized as a string.

target_currencystring nullable

Target currency (ISO 4217, lower-cased in the ledger view).

target_cumulative_balance_with_commissioninteger nullable

Running balance in cents including commissions. Only computed when the list is requested with cumulative balances (_with_cumulative_balances=true) or on the CSV export.

source_typestring nullable

Polymorphic type of the underlying source record.

source_idstring nullable

Polymorphic id of the underlying source record.

commission_amountstring

Commission amount in integer cents, serialized as a string. An empty string ("") is returned when the row has no associated commission ledger entry.

commission_currencystring nullable

Commission currency.

commission_percentagestring nullable

Commission percentage applied.

merchant_namestring nullable

Merchant/recipient name (card merchant or bank recipient).

merchant_image_urlstring nullable

Merchant logo URL (card transactions only).

affects_balanceboolean

Whether this transaction affects the account balance.

cartola_idstring uuid nullable

The cartola (statement) this transaction is assigned to, if any.

cartola_datestring date-time nullable

The accounting date used to place the transaction in a cartola.

authorized_atstring date-time nullable

Timestamp when the transaction was authorized.

cumulative_balanceinteger nullable

Running balance in cents. A virtual attribute aliased to the persisted ledger value (target_cumulative_balance_cents), so the key is always present — it holds the value stored on the ledger row. cumulative_balance and target_cumulative_balance are aliases of the SAME underlying value. Only the on-the-fly window-function recomputation of these balances is gated on _with_cumulative_balances=true (and on the CSV export); without it the persisted value is returned.

target_cumulative_balanceinteger nullable

Running balance in cents. Aliased to the SAME persisted ledger value as cumulative_balance (target_cumulative_balance_cents); both keys are always present and carry the same number. Only the window-function recomputation is gated on _with_cumulative_balances=true (or the CSV export).

created_atstring date-time

When the underlying transaction record was created.

updated_atstring date-time

When the underlying transaction record was last updated.

Example response

[
  {
    "id": "09f6cc5e-8a16-43ae-8bb1-637c0e1c0a6d",
    "accounting_ledger_tx_id": "09f6cc5e-8a16-43ae-8bb1-637c0e1c0a6d",
    "company_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "8e668a4e-8485-4248-86cc-a7a2201cf8c3",
    "card_name": "Marketing Visa",
    "card_last4": "4242",
    "description": "Pago proveedor 01/02",
    "transaction_type": "card_transactions",
    "status": "approved",
    "amount": "-150000",
    "currency": "CLP",
    "charge": "-150000",
    "deposit": "0",
    "amount_in_clp": "-150000",
    "exchange_rate": "1,032.5",
    "exchange_rate_value": "1032.5",
    "target_amount": "-150000",
    "target_currency": "clp",
    "commission_amount": "1500",
    "merchant_name": "Amazon Web Services",
    "affects_balance": true
  }
]