# Saldo y recargas

> Consultar el saldo prepago de Trevol, ver sus movimientos y preparar una recarga con Wompi por la API.

Fuente: https://platform.trevol.si/docs/saldo

El saldo prepago es de la **cuenta**, no de la empresa: todas las empresas de la cuenta lo comparten (`shared: true`). Solo lo que se emite en **producción** (llaves `tvl_live_…`) lo consume; la habilitación no cobra. Con `available` por debajo del precio de un documento, emitir en producción responde [`insufficient_balance`](/docs/errores#insufficient_balance) (402).

## El saldo

Cualquier llave lo lee, de lectura o de escritura, de Pruebas o de Producción: es uno solo.

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

| Campo           | Qué es                                                                              |
| --------------- | ----------------------------------------------------------------------------------- |
| `available`     | Lo que se puede gastar, en pesos (puede ser negativo por un cobro tardío).          |
| `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 (20 % de la última recarga); `null` sin recargas. |
| `level`         | `empty` (`available` ≤ 0), `low` (por debajo del umbral) u `ok`.                    |

El evento `balance.low` avisa por webhook cuando el saldo baja del umbral (solo en producción).

## Los movimientos

Lo mismo que «Saldo y recargas» en la app: un documento es **una** fila; lo demás, una fila por movimiento. Filtra con `type` (`all`, `documents`, `funding` o `top_ups`) y pagina con `limit` y `starting_after` ([Paginación](/docs/paginacion)).

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

## Recargar

`POST /v1/balance/top_ups` **prepara** una recarga y devuelve lo que necesita el widget de Wompi (`WidgetCheckout`): la referencia, el monto, la firma de integridad y su vencimiento. El pago se hace en el widget; cuando Wompi lo aprueba, Trevol abona el saldo.

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

- **Es dinero real con cualquier llave**, también `tvl_test_`: no hay un saldo de pruebas.
- Solo llaves de escritura; exige `Idempotency-Key` (repetir con la misma clave devuelve la **misma** recarga). La firma vence en una hora: si el widget venció, prepara otra.
- El monto va entre la recarga mínima y la máxima ([`top_up_below_minimum`](/docs/errores#top_up_below_minimum) y [`top_up_above_maximum`](/docs/errores#top_up_above_maximum), con `minimum_cop` y `maximum_cop`). Si Wompi no está disponible: [`top_ups_unavailable`](/docs/errores#top_ups_unavailable).
- La factura de la recarga sale a nombre de `buyer`; sin él, a nombre de la empresa de la llave con sus datos. Si no alcanzan, `422` en `buyer.*`.
- Hasta 20 por llave cada 10 minutos.

Referencia: [Saldo](/docs/api/balance).