Verificar saldo atualizado da conta com informações detalhadas sobre saldo total, bloqueado e disponível. Este endpoint fornece dados de saldo em tempo real para sua conta FireBanking.
Tipos de Saldo
Saldo Total totalBalance
Saldo total da conta incluindo fundos disponíveis e bloqueados
Saldo Bloqueado blockedBalance
Valor comprometido em saques e operações pendentes
Saldo Disponível availableBalance
Saldo disponível para novas transações e saques
Exemplo de Requisição
curl --request GET \
--url https://api-gateway.firebanking.com.br/v1/account/balance \
--header 'x-api-key: sua_chave_api'
Exemplo de Resposta
{
"id" : "6642d54caff30523094a6584c" ,
"totalBalance" : 4.02 ,
"blockedBalance" : 1.26 ,
"availableBalance" : 2.76 ,
"consultedAt" : "2024-01-15T10:30:45.123Z"
}
Campos da Resposta
Identificador único da conta
Saldo total da conta (disponível + bloqueado)
Valor comprometido em saques e operações pendentes
Saldo disponível para novas transações
Timestamp ISO 8601 de quando o saldo foi consultado
Cálculo do Saldo
Relação entre Saldos
O relacionamento entre os saldos é:
Total = Disponível + Bloqueado
Saldo Bloqueado
Inclui valores comprometidos em:
Saques PIX em processamento
Transferências aguardando confirmação
Reservas para chargebacks potenciais
Operações pendentes não finalizadas
Saldo Disponível
Valor que pode ser usado para:
Novos saques e transferências
Pagamento de taxas
Operações em tempo real
Cronograma de Liberação
PIX Instantâneo
Disponível imediatamente após recebimento
Cartão D+2
Disponível 2 dias úteis após captura
Boleto D+1
Disponível 1 dia útil após pagamento
Casos de Uso
Gestão de Fluxo de Caixa Monitorar fundos disponíveis para operações
Validação de Saque Verificar se há saldo suficiente antes de sacar
Conciliação Corresponder saldo com registros internos
Relatórios Gerar demonstrativos financeiros
Limitação de Taxa
Este endpoint tem os seguintes limites:
60 requisições por minuto por chave API
Recomendado usar webhooks para atualizações em tempo real
Evite polling excessivo. Use webhooks para ser notificado sobre mudanças de saldo.
Cenários de Erro
Códigos de Resposta
Código Descrição Solução 200 Sucesso Saldo recuperado 401 Não autorizado Verifique header x-api-key 403 Proibido Chave API sem permissões 500 Erro interno Tente novamente
Webhooks Relacionados
Configure webhooks para receber notificações sobre mudanças de saldo:
curl --request POST \
--url https://api-gateway.firebanking.com.br/v1/account/webhook \
--header 'x-api-key: sua_chave_api' \
--header 'Content-Type: application/json' \
--data '{
"pixWebhookUrl": "https://meusite.com/webhooks/pix"
}'
Todos os valores são em reais com decimais:
R$ 4,02 = 4.02
R$ 1,26 = 1.26
R$ 2,76 = 2.76
Para exibição, formate os valores de acordo com as convenções monetárias brasileiras (R$ 4,02).
Timestamp de Consulta
Campo consultedAt
O campo consultedAt fornece o momento exato em que o saldo foi consultado:
{
"consultedAt" : "2024-01-15T10:30:45.123Z"
}
Características:
Formato ISO 8601 com timezone UTC
Precisão de milissegundos para controle granular
Único por requisição - cada consulta tem seu timestamp
Casos de Uso do Timestamp
Cache Inteligente Use o timestamp para decidir quando atualizar cache local
Auditoria Rastreie quando cada consulta de saldo foi realizada
Sincronização Compare timestamps entre sistemas para detectar defasagem
Debugging Identifique exatamente quando problemas de saldo ocorreram
Implementação de Cache
class BalanceCache {
constructor ( maxAge = 30000 ) { // 30 segundos
this . cache = null ;
this . maxAge = maxAge ;
}
async getBalance () {
if ( this . isValid ()) {
return this . cache ;
}
const balance = await this . fetchFromAPI ();
this . cache = balance ;
return balance ;
}
isValid () {
if ( ! this . cache ) return false ;
const consultedAt = new Date ( this . cache . consultedAt );
const now = new Date ();
return ( now - consultedAt ) < this . maxAge ;
}
}
Próximos Passos
Chave de API para autenticação
Saldo da conta recuperado com sucesso
Identificador único da conta
Example: "6642d54caff30523094a6584c"
Valor comprometido em saques
Saldo disponível para transações
consultedAt
string<date-time>
required
Timestamp ISO 8601 de quando o saldo foi consultado
Example: "2024-01-15T10:30:45.123Z"