Consultar o saldo
Devolve o saldo da conta que a chave autentica, em centavos inteiros: o que já liberou e o que ainda vai liberar.
Autenticação
Chave de API no cabeçalho Authorization: Bearer naut_live_….
O escopo exigido é balance:read. Uma credencial sem esse escopo recusa com 401, o mesmo código de uma credencial inválida: a recusa não diz se ela existe.
Exige chave de API no cabeçalho. A família da chave decide contra qual ambiente ela escreve, e a chave não fabrica sessão: ela não alcança nenhuma rota fora de /v1.
Parâmetros
Consulta
| Nome | Tipo | Descrição |
|---|---|---|
currency | um de: `BRL`, `USD`, `EUR` | A moeda do saldo. |
Respostas
200 · sucesso
{
"availableCents": 129900,
"currency": "BRL",
"pendingCents": 129900,
"reserveCents": 129900
}São TRÊS números, e não a decomposição inteira: availableCents é o que já liberou, pendingCents é o que ainda vai liberar e reserveCents é a reserva de segurança, a fatia retida de cada venda que volta ao saldo quando o prazo dela vence. Retido, disputa e dívida não saem por aqui; quem os publica é GET /seller/balance, no painel do vendedor. Os três são iguais, ao centavo, aos mesmos baldes do painel.
401 · não autenticado
A chave não foi apresentada, ou não vale.
429 · excesso de chamadas
Excesso de chamadas para esta chave.
503 · indisponível
A sua chave é de sandbox e o ambiente de teste desta instalação não está provisionado. Chaves de produção seguem funcionando; repetir a chamada não resolve.
Erros desta rota
| Status | Código | Quando | O que fazer |
|---|---|---|---|
| 401 | UNAUTHORIZED | A chave de API não veio no cabeçalho, veio malformada, foi revogada, ou não pertence a esta instalação. | Confira o cabeçalho e o prefixo da chave. Repetir com a mesma chave devolve sempre 401, e nenhuma chamada desta superfície funciona sem uma chave válida. |
| 429 | API_KEY_RATE_LIMITED | Esta chave passou do teto de chamadas da janela corrente. É limite de FREQUÊNCIA, não de valor. | Espere a janela virar e reenvie, espaçando as chamadas. O saldo não muda por ser consultado mais vezes. |
| 503 | SANDBOX_UNAVAILABLE | A sua chave é da família de teste e esta instalação não tem o ambiente de teste provisionado. Chaves de produção seguem funcionando normalmente. | Use uma chave de produção, ou peça o provisionamento do ambiente de teste. Repetir com a chave de teste não resolve, e nenhum saldo de teste existe para devolver. |
Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.