Endpoints
Consultar Saldo
Visão Geral
O endpoint GET /accounts/balances retorna o saldo da conta autenticada no formato compatível com a especificação do Banco Central.
Endpoint
GET /accounts/balancesAutenticação
Token Bearer obtido via /oauth/token.
Request
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()Response
{
"data": [
{
"eventDate": "2025-01-15T10:30:00.000Z",
"balanceAmount": {
"available": 48734.90,
"blocked": 1500.00,
"overdraft": 0
}
}
]
}Campos da Resposta
dataarrayLista de saldos. Atualmente retorna apenas um item.
Tipos de Saldo
| Tipo | Descrição |
|---|---|
| available | Saldo que pode ser usado imediatamente para transferências |
| blocked | Valores reservados para operações em processamento |
| overdraft | Limite de crédito adicional (não implementado) |
Cálculo do Saldo Total
saldoTotal = available + blockedO saldo available já desconta os valores blocked.
Comparação com API Padrão
API Padrão (GET /balance) | API BACEN (GET /accounts/balances) |
|---|---|
grossBalance | available + blocked |
blockedBalance | blocked |
netBalance | available |
consultedAt | eventDate |
Exemplo de Equivalência
// API Padrão
{
"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
}
}]
}Fluxo de Saldo em Operações
PIX Out (Transferência)
sequenceDiagram
participant App
participant API
participant Banco
Note over App,Banco: Estado inicial: available=1000, blocked=0
App->>API: POST /dict/pix (R$ 100)
API-->>App: { type: "PENDING" }
Note over App,Banco: Estado: available=900, blocked=100
Banco->>API: Confirmação
API->>App: Webhook TRANSFER (LIQUIDATED)
Note over App,Banco: Estado final: available=900, blocked=0PIX In (Recebimento)
sequenceDiagram
participant Pagador
participant API
participant App
Note over Pagador,App: Estado inicial: available=1000
Pagador->>API: Paga QR Code
API->>App: Webhook RECEIVE (LIQUIDATED)
Note over Pagador,App: Estado final: available=1100Boas Praticas
Erros Comuns
| Código | Erro | Solução |
|---|---|---|
| 401 | Token não fornecido | Inclua header Authorization: Bearer <token> |
| 401 | Token inválido | Verifique se o token está correto |
| 401 | Token expirado | Obtenha novo token via /oauth/token |