Skip to main content

​
Balances workflow

The balances area in the application is about more than a raw account total. The wiki frames it as a financial position view:
  • current balances across internal and external accounts
  • pending movements that are not yet finalized
  • historical evolution over time
  • operational volume that explains how balances changed
The API workflows below mirror that model.

​
Balance interpretation rules

Before you automate reporting, keep the app’s accounting interpretation in mind:
  • Internal balances (cajas, assets): positive is favorable because it means available company funds.
  • External balances (cuentas corrientes): negative is favorable because it means the counterparty owes the company.
That is why historical endpoints distinguish internal and external positions instead of treating every balance sign the same way.

​
Historical snapshot for one date

Use GET /api/balances/historical?date=YYYY-MM-DD to retrieve a closing snapshot for a specific day. This route is useful for:
  • reconciliation at period close
  • point-in-time liquidity checks
  • rebuilding the same current-vs-pending view used in the balances metrics UI
The response groups balances by currency and client type and includes:
  • total_balance
  • favorable_balance
  • unfavorable_balance
  • pending balance totals for the same snapshot date
  • GET /api/balances/historical
  • GET /api/balances/historical-range
  • GET /api/balances/historical-volume
Use GET /api/balances/historical-range?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD when you want the time series view behind the balances chart. This endpoint returns daily grouped data, including:
  • the date
  • the balances recorded for that date
  • operation_count for the same day
It is the best input for dashboards, trend charts, and period-over-period comparisons.

​
Historical volume for movement analysis

Use GET /api/balances/historical-volume?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD to analyze completed movement volume over time. The response is grouped by:
  • operation date
  • operation type name
  • transaction type name
  • currency
This complements the balance history endpoints by showing not only where balances ended up, but also what categories of completed movements contributed to that change.

​
Manual balance adjustments

Use POST /api/accounts/{id}/manual-balance when an account needs a direct correction. The request body supports one of two patterns:
  • Set a new absolute balance
  • Apply an adjustment delta
curl --request POST \
  --url "https://finsync.ar/api/accounts/123/manual-balance" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "adjustment": -250
  }'
The response returns balance_before, balance_after, and the effective adjustment, which makes this endpoint suitable for audit-friendly reconciliation tooling. Because this route writes directly to the ledger-backed account balance, use it only for controlled correction workflows, not for normal operational movement.

​
Notes from the application wiki

  • The balances area in the app also highlights DSO and exchange-rate management as analysis tools.
  • Those concepts are part of the broader balances module, but the workflow endpoints above focus on snapshots, movement volume, and direct balance corrections.