Saldo

Consulta el saldo de la cuenta bancaria asociada a la API Key.

Endpoint

GET /api/external/balance

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
X-Key-Case	String	No	Defina como camelCase para recibir los campos de la respuesta en camelCase (default es snake_case)

Ejemplo

curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Respuesta de Exito (200)

{
  "worked": true,
  "balance": 3000000,
  "available": 2700000,
  "pending": 300000,
  "currency": "BRL"
}

Campo	Tipo	Descripcion
worked	Boolean	true indica exito en la operacion
balance	Integer	Saldo seguro en unidades base (÷ 10.000 para reales). 3000000 = R$ 300,00
available	Integer	Saldo disponible para operaciones en unidades base. 2700000 = R$ 270,00
pending	Integer	Valor retenido en transacciones pendientes en unidades base. 300000 = R$ 30,00
currency	String	Codigo de la moneda (siempre BRL)

Valores de respuesta en unidades base

Todos los valores de respuesta son enteros en unidades base. Para convertir a reales, divida por 10.000. Ejemplo: 3000000 ÷ 10.000 = R$ 300,00. Nunca use punto flotante.

Calculo del saldo

Campo	Definicion
balance	Saldo seguro = min(saldo_tigerbeetle, saldo_postgres). Si hay divergencia TB↔PG, el menor valor es usado
available	balance - pending — saldo efectivamente disponible para nuevas operaciones
pending	Suma de los debitos pendientes en el TigerBeetle (account.debits_pending)

El campo balance protege contra saldo inflado en escenarios de divergencia temporal entre TigerBeetle y PostgreSQL (ej: bloqueo MED, reconciliacion pos-deploy). Usted nunca vera aqui un valor mayor al realmente disponible en el sistema de ledger — siempre el menor de los dos sistemas.

Lo que compone pending (debitos pendientes en el TigerBeetle)

Cada item abajo es un pending transfer en el TigerBeetle que reduce el available hasta ser posted o voided:

Origen	Cuando aparece	Cuando es liberado
PIX OUT en vuelo (pending TB de la wallet → COSIF in-transit)	Durante el envio, mientras aguarda confirmacion BACEN (~1,6s tipico)	Posted al recibir pix.payout.confirmed (settled); voided al recibir pix.payout.failed
Bloqueo cautelar MED (phantom hold, code 1032)	Cuando infraccion ACKNOWLEDGED >R$1k es detectada via ComplianceSyncWorker	Voided al analysis_result=DISAGREED (defensa aceptada); posted al AGREED (devolucion PACS.004 ejecutada). Ver Infracciones.
Cuarentena (stage=5)	PIX OUT sin respuesta BACEN >30min — saldo queda en limbo	Posted/voided solo despues de decision manual de la reserva Owem (puede tardar horas o D+1). Ver pix-lifecycle.
Otros holds internos	Raros — normalmente ligados a fees o ajustes especificos	Depende del tipo

Situaciones donde balance < saldo bruto TB

• Divergencia TB↔PG: en casos raros (ej: ventana de remediacion pos-deploy, incidente session 142 TB-PG equalization), balance refleja el menor entre los dos sistemas hasta la convergencia. Nunca vemos saldo inflado; a lo maximo, subdimensionado por algunos minutos.

available puede quedar "parado" incluso con PIX IN creciente

Si usted ve balance subiendo (recibimientos) pero available no crece en la misma proporcion, muy probablemente hay bloqueo MED activo. Consulte GET /api/external/med para listar los bloqueos cautelares. Todo bloqueo tiene origen en una infraccion — vea Infracciones para el flujo completo.

Cache y consistencia

El saldo es calculado en tiempo real (latencia tipica <10ms) — no hay cache. Sin embargo, en ventanas pos-liquidacion (<200ms despues del webhook pix.charge.paid), el PostgreSQL puede aun no haber sido actualizado. Para conciliacion critica, aguarde el webhook antes de consultar el saldo.

Respuesta de Error (401)

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}