Pular para o conteúdo principal
GET
/
v1
/
account
/
balance
Obter Saldo da Conta
curl --request GET \
  --url https://api-gateway.firebanking.dev/v1/account/balance \
  --header 'x-api-key: <api-key>'
{
  "id": "6642d54caff30523094a6584c",
  "totalBalance": 4.02,
  "blockedBalance": 1.26,
  "availableBalance": 2.76,
  "consultedAt": "2024-01-15T10:30:45.123Z"
}
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
curl --request GET \
  --url https://api-gateway.firebanking.com.br/v1/account/balance \
  --header 'x-api-key: sua_chave_api'

Exemplo de Resposta

Resposta de Sucesso
{
  "id": "6642d54caff30523094a6584c",
  "totalBalance": 4.02,
  "blockedBalance": 1.26,
  "availableBalance": 2.76,
  "consultedAt": "2024-01-15T10:30:45.123Z"
}

Campos da Resposta

id
string
required
Identificador único da conta
totalBalance
number
required
Saldo total da conta (disponível + bloqueado)
blockedBalance
number
required
Valor comprometido em saques e operações pendentes
availableBalance
number
required
Saldo disponível para novas transações
consultedAt
string
required
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ódigoDescriçãoSolução
200SucessoSaldo recuperado
401Não autorizadoVerifique header x-api-key
403ProibidoChave API sem permissões
500Erro internoTente novamente

Webhooks Relacionados

Configure webhooks para receber notificações sobre mudanças de saldo:
Configurar Webhook
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"
  }'

Formato de Valores

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

Cache com Timestamp
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

Authorizations

x-api-key
string
header
required

Chave de API para autenticação

Response

Saldo da conta recuperado com sucesso

id
string
required

Identificador único da conta

Example:

"6642d54caff30523094a6584c"

totalBalance
number
required

Saldo total da conta

Example:

4.02

blockedBalance
number
required

Valor comprometido em saques

Example:

1.26

availableBalance
number
required

Saldo disponível para transações

Example:

2.76

consultedAt
string<date-time>
required

Timestamp ISO 8601 de quando o saldo foi consultado

Example:

"2024-01-15T10:30:45.123Z"