# Saldo

> Las operaciones de Saldo de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Fuente: https://platform.trevol.si/docs/api/balance

El saldo prepago de la cuenta (lo comparten sus empresas), sus movimientos y las recargas con Wompi.

Los ejemplos son peticiones con cURL. La llave va en `TREVOL_API_KEY`; los cuerpos de ejemplo son los de la especificación. Los errores comunes están en [Errores](/docs/errores).

## Preparar una recarga del saldo (para el widget de Wompi)

`POST /v1/balance/top_ups` · `createBalanceTopUp`

Prepara una recarga del saldo de la cuenta y devuelve lo que necesita el widget de Wompi (`WidgetCheckout`: `publicKey`, `currency`, `amountInCents`, `reference`, `signature: {integrity}` y `expirationTime`). El pago se hace en el widget; cuando Wompi lo aprueba, Trevol abona el saldo (y la factura de la recarga sale a nombre de `buyer`). Preparar no mueve saldo y la firma vence en una hora: si el widget venció, prepara otra. Solo llaves de escritura; exige `Idempotency-Key` (repetir con la misma clave devuelve la MISMA recarga). Sin `buyer`, la factura va a nombre de la empresa de la llave con sus datos (NIT, DV, razón social, correo, teléfono, dirección y municipio); si no alcanzan, 422 en `buyer.*`. El monto va entre la recarga mínima y la máxima (422 `top_up_below_minimum` / `top_up_above_maximum` con `minimum_cop` / `maximum_cop`). Es dinero real con cualquier llave (también `test`): el saldo es uno solo. Hasta 20 por llave cada 10 minutos (429).

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | cabecera | texto | sí | Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días). |

**Cuerpo** ([TopUpInput](/docs/api/objetos#TopUpInput), obligatorio)

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount_cop` | entero | sí | En pesos, entre la recarga mínima y la máxima. |
| `buyer` | [TopUpBuyer](/docs/api/objetos#TopUpBuyer) |  |  |

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 201 | La recarga preparada ([TopUp](/docs/api/objetos#TopUp)) |
| 422 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| 429 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| 503 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`POST /v1/balance/top_ups` (`createBalanceTopUp`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/balance/top_ups" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cop": 50000
}'
```

#### Respuesta 201

```json
{
  "object": "top_up",
  "reference": "TRV-REC-20261031-4C1D2E3F4A5B",
  "amount_cop": 50000,
  "status": "prepared",
  "wompi": {
    "public_key": "pub_prod_Ejemplo0000000000000000000000",
    "reference": "TRV-REC-20261031-4C1D2E3F4A5B",
    "amount_in_cents": 5000000,
    "currency": "COP",
    "signature": "5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d",
    "expiration_time": "2026-10-31T15:20:05.000Z"
  }
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=createBalanceTopUp&ejemplo=empresa)

## El saldo de la cuenta (lo comparten sus empresas)

`GET /v1/balance` · `retrieveBalance`

El saldo prepago de Trevol. Es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (`shared: true`) y cualquier llave de cualquiera de ellas, de lectura o de escritura, `test` o `live`, ve el mismo. Solo lo que se emite en producción (llaves `live`) lo consume; la habilitación (`test`) no cobra. `available` es lo que se puede gastar (en pesos); `held`, lo apartado por documentos que la DIAN todavía valida; `overdraft`, cuánto puede bajar `available` de cero al apartar un documento; `low_threshold`, el umbral del aviso de saldo bajo (el 20 % de la última recarga; `null` sin recargas). `level`: `empty` con `available` ≤ 0, `low` por debajo de `low_threshold`, si no `ok`. Con `available` por debajo del precio de un documento, emitir en producción responde 402 `insufficient_balance`. El evento `balance.low` avisa por webhook.

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | El saldo ([Balance](/docs/api/objetos#Balance)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/balance` (`retrieveBalance`)

#### cURL

```bash
curl "https://api.trevol.si/v1/balance" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

#### Respuesta 200

```json
{
  "object": "balance",
  "currency": "COP",
  "available": 48600,
  "held": 400,
  "overdraft": 0,
  "low_threshold": 10000,
  "level": "ok",
  "updated_at": "2026-10-31T09:20:05-05:00",
  "shared": true
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=retrieveBalance)

## Los movimientos del saldo de la cuenta

`GET /v1/balance/transactions` · `listBalanceTransactions`

Los movimientos del saldo de la cuenta (de todas sus empresas), del más nuevo al más viejo: lo mismo que «Saldo y recargas» en la app. Un documento es UNA fila (`type: document`) con su `status`: `pending` (apartado mientras la DIAN lo valida), `charged` (validado y cobrado) o `released` (la DIAN lo rechazó: no se cobró y `amount` es 0); `company` dice qué empresa lo emitió. Lo demás es una fila por movimiento: `top_up` (recarga, con su `reference`), `top_up_reversal`, `bonus`, `adjustment`, `license_fee`, `expiration` u `other`. `amount` es lo que el movimiento hizo con el disponible, con signo; `available_after`, el disponible justo después. Filtro `type`: `all` (por defecto), `documents`, `funding` (todo lo que no es un documento) o `top_ups`. Paginación por cursor: `limit` (1 a 100, 25 por defecto) y `starting_after` (el `id` de la última fila que tienes).

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `limit` | consulta | entero |  |  |
| `starting_after` | consulta | texto |  |  |
| `type` | consulta | `all` \| `documents` \| `funding` \| `top_ups` |  |  |

**Respuestas**

| Estado | Qué pasó |
| --- | --- |
| 200 | {object: list, data, has_more, next_cursor} (objeto) |
| 422 | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |
| Error | Error (application/problem+json) ([Problem](/docs/api/objetos#Problem)) |

`GET /v1/balance/transactions` (`listBalanceTransactions`)

#### cURL

```bash
curl "https://api.trevol.si/v1/balance/transactions?limit=100" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

#### Respuesta 200

```json
{
  "object": "list",
  "has_more": true,
  "next_cursor": "btx_9300",
  "data": [
    {
      "id": "btx_9341",
      "object": "balance_transaction",
      "type": "document",
      "status": "pending",
      "amount": -400,
      "available_after": 48600,
      "description": "Factura FE1290 · apartado mientras la DIAN lo valida",
      "document": {
        "type": "invoice",
        "number": "FE1290"
      },
      "company": {
        "nit": "900373115",
        "name": "TOSTADORA MONTEVERDE SAS"
      },
      "reference": null,
      "created_at": "2026-10-31T09:20:05-05:00"
    },
    {
      "id": "btx_9338",
      "object": "balance_transaction",
      "type": "document",
      "status": "charged",
      "amount": -400,
      "available_after": 49000,
      "description": "Nómina NE15",
      "document": {
        "type": "payroll",
        "number": "NE15"
      },
      "company": {
        "nit": "900373591",
        "name": "CAFÉ DEL VALLE SAS"
      },
      "reference": null,
      "created_at": "2026-10-31T08:02:41-05:00"
    },
    {
      "id": "btx_9301",
      "object": "balance_transaction",
      "type": "document",
      "status": "released",
      "amount": 0,
      "available_after": 49000,
      "description": "Factura FE1289 · rechazado por la DIAN: no se cobró",
      "document": {
        "type": "invoice",
        "number": "FE1289"
      },
      "company": {
        "nit": "900373115",
        "name": "TOSTADORA MONTEVERDE SAS"
      },
      "reference": null,
      "created_at": "2026-10-30T17:10:00-05:00"
    },
    {
      "id": "btx_9300",
      "object": "balance_transaction",
      "type": "top_up",
      "status": "completed",
      "amount": 50000,
      "available_after": 49400,
      "description": "Recarga TRV-REC-20261030-8F2A61C0D9B3",
      "document": null,
      "company": null,
      "reference": "TRV-REC-20261030-8F2A61C0D9B3",
      "created_at": "2026-10-30T16:58:12-05:00"
    }
  ]
}
```

[Probar en el Playground](https://platform.trevol.si/playground?op=listBalanceTransactions)