> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finsync.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances workflow

> Read balance snapshots the same way the app does, and apply manual corrections safely with the FinSync API.

# 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

## Historical range for trends

* `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

```bash theme={null}
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.