Documentación · Referencia · API v1 · versión 2026-10-22
Saldo
Las operaciones de Saldo de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.
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.
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
Idempotency-KeycabeceratextoobligatorioObligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).
Cuerpo (TopUpInput, obligatorio)
amount_copenteroobligatorioEn pesos, entre la recarga mínima y la máxima.buyerTopUpBuyer
Respuestas
POST /v1/balance/top_ups
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
}'{
"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"
}
}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
GET /v1/balance
curl "https://api.trevol.si/v1/balance" \
-H "Authorization: Bearer $TREVOL_API_KEY"{
"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
}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
limitconsultaenterostarting_afterconsultatextotypeconsultaall|documents|funding|top_ups
Respuestas
GET /v1/balance/transactions
curl "https://api.trevol.si/v1/balance/transactions?limit=100" \
-H "Authorization: Bearer $TREVOL_API_KEY"{
"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"
}
]
}