> ## 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.

# Operations workflow

> Create, review, approve, and cancel FinSync operations using the same business model as the application wiki.

# Operations workflow

Operations are the core transactional primitive in FinSync. The application models an operation as one business event made up of one or more transactions.

That distinction matters for integrations:

* An operation is the full movement, such as a payout, collection, FX trade, or manual adjustment.
* Each transaction inside the operation is an individual `credit` or `debit` that affects one account.

## Accounting meaning of credit and debit

The app wiki makes an important point: `credit` and `debit` do not mean the same business outcome for every client type.

| Client side                          | Business meaning of `credit`                | Business meaning of `debit`                 |
| ------------------------------------ | ------------------------------------------- | ------------------------------------------- |
| Internal account (`caja`, asset)     | Increases company funds                     | Decreases company funds                     |
| External client (`cuenta corriente`) | Increases what the company owes that client | Decreases what the company owes that client |

Use this rule when you validate transaction types and when you explain balances back to downstream systems.

## Preflight lookups

Before creating operations, fetch the catalog data that drives payload construction:

* `GET /api/operation-types`
* `GET /api/transaction-types`

These endpoints let you resolve:

* which `operation_type_id` corresponds to `up`, `down`, `other`, or `exchange`
* which `transaction_type_id` should be used for regular movements versus commissions

## List and monitor operations

Use `GET /api/operations` to review existing operations, inspect their transactions, and monitor status transitions.

```bash theme={null}
curl --request GET \
  --url "https://finsync.ar/api/operations?dateFrom=2026-04-01&dateTo=2026-04-09&page=1&pageSize=20" \
  --header "x-api-key: YOUR_API_KEY"
```

Useful filters include:

* `dateFrom`
* `dateTo`
* `page`
* `pageSize`
* `operationType` with values such as `up`, `down`, `other`, `exchange`, `budget`, `interest`
* `status` with values `pending`, `completed`, or `adjusted`

When `page` and `pageSize` are omitted, the endpoint returns a simpler response shape. When pagination is supplied, it also returns `pagination` metadata.

## Choose the right creation payload

Use `POST /api/operations` with the payload shape that matches the workflow you want to automate.

The public API currently supports three main creation patterns:

* `UP` and `DOWN`: paired internal/external movements between one internal account and one external client
* `OTHER`: one or many custom transactions for special adjustments or bespoke accounting flows
* `EXCHANGE`: FX operations in either internal mode or external client mode

The application UI also teaches additional business modes for how money can move. In the API, those scenarios map to the payload families above rather than to a separate mode flag for `UP` and `DOWN`.

The current reference includes examples for:

* UP and DOWN operations
* OTHER operations
* Internal exchange operations
* External exchange operations

### Idempotent creates with `external_transaction_id`

Pass an optional `external_transaction_id` (your own payment or transfer reference) when creating an operation. FinSync stores it on the operation’s primary transaction and rejects duplicates with **409 Conflict**, including the existing `operation_id` and `status` (`pending` or `completed`). Cancelled operations (`adjusted`) release the id so you can reuse it.

Example `UP` or `DOWN` payload:

```bash theme={null}
curl --request POST \
  --url "https://finsync.ar/api/operations" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "operation_type_id": 1,
    "description": "Client payout",
    "external_transaction_id": "payout-2026-04-09-001",
    "internal_account_id": 123,
    "external_client_id": 456,
    "internal_amount": 1000,
    "external_amount": 1000,
    "external_currency": "USD"
  }'
```

If the first request succeeded but the client timed out, retrying with the same `external_transaction_id` returns:

```json theme={null}
{
  "error": "An operation with this external_transaction_id already exists",
  "external_transaction_id": "payout-2026-04-09-001",
  "operation_id": 42,
  "status": "pending"
}
```

## Understand statuses

The wiki defines three transaction lifecycle states that also drive the approval endpoints:

* `pending`: created, but not yet applied as a finalized balance movement
* `completed`: approved and applied
* `adjusted`: cancelled or rolled back

## Approve or cancel

Use these endpoints only when the operation is still pending:

* `POST /api/operations/{id}/approve`
* `DELETE /api/operations/{id}`

Approval marks the operation transactions as `completed`. Cancellation marks them as `adjusted`.

Both endpoints require the operation's transactions to still be pending.

## Suggested integration pattern

1. Fetch `operation-types` and `transaction-types` so you can build payloads from company-specific IDs instead of hardcoding assumptions.
2. Create the operation with `POST /api/operations`, using a stable `external_transaction_id` when you need safe retries.
3. Persist the returned `operation_id` and created transaction IDs (on **409**, use the `operation_id` from the error body).
4. List operations with `GET /api/operations` to confirm the new operation, inspect its transaction set, and validate `pending` vs `completed` state.
5. Approve with `POST /api/operations/{id}/approve` or cancel with `DELETE /api/operations/{id}` only after your business checks pass.