Saldos da conta, por ativo

GET 
/integration/v1/balances

Quatro números por ativo, e não um. O saldo "da conta" é uma simplificação que quebra assim que existe cartão e saque com aprovação:

campo	o que é	pode gastar?
available	disponível	sim
held	retido em saque aguardando	não
receivable	capturado no cartão, chega em D+N	não
reserve	retido contra contestação	não

Mostrar só o disponível faria o cliente concluir que sumiu dinheiro; mostrar só o total faria ele tentar sacar o que não pode.

Faça cache por alguns segundos. Em fluxo normal o saldo não muda mais rápido que isso, e consultar em laço só consome o seu teto de requisições.

Respostas

200

OK

401

error.code = invalid_signature. Cobre chave desconhecida, assinatura incorreta, cabeçalho ausente, instante fora da tolerância de 300s e nonce repetido — deliberadamente indistinguíveis, para não transformar o endpoint num verificador de quais chaves existem.

403

A credencial vale, mas a conta não pode fazer isto agora: suspensa, encerrada, ou com o valor acima do limite do nível de verificação (error.code = forbidden ou kyc_limit_exceeded).

Chave válida numa conta desligada não opera — a credencial afirma, o banco confirma. Sem isso o bloqueio seria decorativo.

429

Teto de consumo atingido. error.details.retryAfter traz os segundos a esperar — sem isso, a reação natural é tentar de novo na hora, o que piora a saturação que o limite existe para conter.