Solde

Consulte le solde du compte bancaire associé à l'API Key.

Endpoint

GET /api/external/balance

Headers

Header	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Non	Définissez à camelCase pour recevoir les champs de la réponse en camelCase (par défaut snake_case)

Exemple

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

Réponse de succès (200)

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

Champ	Type	Description
worked	Boolean	true indique le succès de l'opération
balance	Integer	Solde sécurisé en unités de base (÷ 10 000 pour reais). 3000000 = R$ 300,00
available	Integer	Solde disponible pour opérations en unités de base. 2700000 = R$ 270,00
pending	Integer	Valeur retenue en transactions pendantes en unités de base. 300000 = R$ 30,00
currency	String	Code de la monnaie (toujours BRL)

Valeurs de réponse en unités de base

Toutes les valeurs de réponse sont des entiers en unités de base. Pour convertir en reais, divisez par 10 000. Exemple : 3000000 ÷ 10 000 = R$ 300,00. N'utilisez jamais de virgule flottante.

Calcul du solde

Champ	Définition
balance	Solde sécurisé = min(saldo_tigerbeetle, saldo_postgres). En cas de divergence TB↔PG, la valeur la plus basse est utilisée
available	balance - pending — solde effectivement disponible pour de nouvelles opérations
pending	Somme des débits en attente dans TigerBeetle (account.debits_pending)

Le champ balance protège contre un solde gonflé dans les scénarios de divergence temporaire entre TigerBeetle et PostgreSQL (ex. : blocage MED, réconciliation post-deploy). Vous ne verrez jamais ici une valeur supérieure à ce qui est réellement disponible dans le système de ledger — toujours le plus petit des deux systèmes.

Ce qui compose pending (débits en attente dans TigerBeetle)

Chaque élément ci-dessous est une pending transfer dans TigerBeetle qui réduit available jusqu'à ce qu'elle soit posted ou voided :

Origine	Quand elle apparaît	Quand elle est libérée
PIX OUT en vol (pending TB de la wallet → COSIF in-transit)	Pendant l'envoi, en attendant la confirmation BACEN (~1,6s typique)	Posted à la réception de pix.payout.confirmed (settled) ; voided à la réception de pix.payout.failed
Blocage conservatoire MED (phantom hold, code 1032)	Quand une infraction ACKNOWLEDGED >R$1k est détectée via ComplianceSyncWorker	Voided avec analysis_result=DISAGREED (défense acceptée) ; posted avec AGREED (remboursement PACS.004 exécuté). Voir Infractions.
Quarantaine (stage=5)	PIX OUT sans réponse BACEN >30min — le solde reste en suspens	Posted/voided seulement après décision manuelle de la réserve Owem (peut prendre des heures ou D+1). Voir pix-lifecycle.
Autres holds internes	Rares — normalement liés à des fees ou ajustements spécifiques	Dépend du type

Situations où balance < solde brut TB

• Divergence TB↔PG : dans des cas rares (ex. : fenêtre de remédiation post-deploy, incident session 142 TB-PG equalization), balance reflète le plus petit des deux systèmes jusqu'à la convergence. Nous ne voyons jamais de solde gonflé ; au maximum, sous-dimensionné pendant quelques minutes.

available peut rester « figé » même avec un PIX IN croissant

Si vous voyez balance augmenter (réceptions) mais que available ne croît pas dans la même proportion, il y a très probablement un blocage MED actif. Consultez GET /api/external/med pour lister les blocages conservatoires. Tout blocage a pour origine une infraction — voir Infractions pour le flux complet.

Cache et cohérence

Le solde est calculé en temps réel (latence typique <10ms) — il n'y a pas de cache. Cependant, dans les fenêtres post-liquidation (<200ms après le webhook pix.charge.paid), PostgreSQL peut ne pas encore avoir été mis à jour. Pour une conciliation critique, attendez le webhook avant de consulter le solde.

Réponse d'erreur (401)

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