Endpoints
Consultar Saldo
Descripción general
El endpoint GET /accounts/balances retorna el saldo de la cuenta autenticada en un formato compatible con la especificacion del Banco Central.
Endpoint
GET /accounts/balancesAutenticación
Token Bearer obtenido via /oauth/token.
Solicitud
curl -X GET https://api.ntxpay.com/accounts/balances \
-H "Authorization: Bearer <token>"const response = await fetch('https://api.ntxpay.com/accounts/balances', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
},
});
const balance = await response.json();import requests
response = requests.get(
'https://api.ntxpay.com/accounts/balances',
headers={
'Authorization': f'Bearer {token}',
}
)
balance = response.json()Respuesta
{
"data": [
{
"eventDate": "2025-01-15T10:30:00.000Z",
"balanceAmount": {
"available": 48734.90,
"blocked": 1500.00,
"overdraft": 0
}
}
]
}Campos de Respuesta
dataarrayLista de saldos. Actualmente retorna solo un elemento.
Tipos de Saldo
| Tipo | Descripción |
|---|---|
| available | Saldo que puede usarse inmediatamente para transferencias |
| blocked | Montos reservados para operaciones en procesamiento |
| overdraft | Limite de crédito adicional (no implementado) |
Calculo del Saldo Total
totalBalance = available + blockedEl saldo available ya descuenta los montos blocked.
Comparacion con la API Estandar
API Estandar (GET /balance) | API BACEN (GET /accounts/balances) |
|---|---|
grossBalance | available + blocked |
blockedBalance | blocked |
netBalance | available |
consultedAt | eventDate |
Ejemplo de Equivalencia
// API Estandar
{
"grossBalance": 50234.90,
"blockedBalance": 1500.00,
"netBalance": 48734.90,
"consultedAt": "2025-01-15T10:30:00.000Z"
}
// API BACEN (equivalente)
{
"data": [{
"eventDate": "2025-01-15T10:30:00.000Z",
"balanceAmount": {
"available": 48734.90,
"blocked": 1500.00,
"overdraft": 0
}
}]
}Flujo del Saldo en Operaciones
PIX Out (Transferencia)
sequenceDiagram
participant App
participant API
participant Bank
Note over App,Bank: Estado inicial: available=1000, blocked=0
App->>API: POST /dict/pix (R$ 100)
API-->>App: { type: "PENDING" }
Note over App,Bank: Estado: available=900, blocked=100
Bank->>API: Confirmacion
API->>App: Webhook TRANSFER (LIQUIDATED)
Note over App,Bank: Estado final: available=900, blocked=0PIX In (Recepción)
sequenceDiagram
participant Payer
participant API
participant App
Note over Payer,App: Estado inicial: available=1000
Payer->>API: Paga QR Code
API->>App: Webhook RECEIVE (LIQUIDATED)
Note over Payer,App: Estado final: available=1100Mejores Prácticas
Errores Comunes
| Código | Error | Solución |
|---|---|---|
| 401 | Token no proporcionado | Incluya el header Authorization: Bearer <token> |
| 401 | Token invalido | Verifique que el token sea correcto |
| 401 | Token expirado | Obtenga un nuevo token via /oauth/token |