Consulte o saldo

Obtenha o saldo da sua conta na Accelerazione, separado entre disponível para saque, bloqueado, em liquidação e reservado, em centavos de BRL ou USD.

GET/api/v1/balanceSaldo da conta, por tipo

O saldo mostra o dinheiro que a Accelerazione registrou na sua conta, separado por situação: o que já pode ser sacado, o que ainda aguarda o prazo de liberação e o que está reservado por saques em andamento. Consulte o saldo antes de pedir um saque: só o valor disponível pode sair.

Requisição

Terminal

curl "$DM_API_BASE/api/v1/balance?accountId=3f6b2c1e-8d4a-4b7f-9e21-5a0c7d9e1b42" \
  -H "Authorization: $DM_API_KEY"

Parâmetro	Onde	Obrigatório	Descrição
`accountId`	Consulta	Sim	UUID da conta de saldo, entregue no credenciamento. É o mesmo do saque.
`balanceType`	Consulta	Não	Devolve só um tipo de saldo, por exemplo `Available`. Maiúsculas e minúsculas são indiferentes.

A chave precisa da permissão balance:read. A conta precisa pertencer à conta da chave: um accountId de outra empresa responde 404, igual a uma conta inexistente.

Resposta

200 OK

{
  "accountId": "3f6b2c1e-8d4a-4b7f-9e21-5a0c7d9e1b42",
  "balances": [
    { "balanceType": "Available", "amount": 10550, "currencyCode": "BRL", "updatedAt": "2026-11-03T12:00:00Z" },
    { "balanceType": "Blocked", "amount": 1200, "currencyCode": "BRL", "updatedAt": "2026-11-03T12:00:00Z" },
    { "balanceType": "PendingWithdrawal", "amount": 150, "currencyCode": "BRL", "updatedAt": "2026-11-03T12:00:00Z" }
  ]
}

Campo	Descrição
`accountId`	A conta consultada.
`balances[].balanceType`	O tipo de saldo (tabela abaixo).
`balances[].amount`	Inteiro na menor unidade da moeda: `10550` é R$ 105,50 numa conta BRL e US$ 105,50 numa conta USD.
`balances[].currencyCode`	`BRL` ou `USD`, a moeda da conta.
`balances[].updatedAt`	Última alteração daquele tipo de saldo, ISO 8601 em UTC. Pode ser `null`.

Um tipo sem movimentação pode não aparecer na lista. Trate a ausência como zero. Com balanceType, a resposta traz só aquele tipo, ou balances: [] se ele não existir na conta.

Tipos de saldo

`balanceType`	Significado
`Available`	Livre para saque. É o valor que o saque confere.
`Blocked`	Vendas confirmadas que ainda aguardam o prazo de liberação do seu plano.
`PendingSettlement`	Valores em liquidação.
`Reserved`	Valores reservados.
`PendingWithdrawal`	Reservado por saques em andamento.

O caminho de um saque pelo saldo: o pedido move o valor de Available para PendingWithdrawal; o saque transferido sai de PendingWithdrawal; um saque rejeitado, cancelado, expirado ou com falha devolve o valor a Available.

Saldo não é o extrato bancário

Esta rota lê a conta interna da Accelerazione, identificada pelo accountId. O extrato bancário lê a conta no provedor, identificada pelo accountNumber. Os dois números não são intercambiáveis e os valores não precisam coincidir. Veja Contas, chaves e identificadores.

Lista de IPs permitidos

O saldo segue a mesma lista de IPs dos saques. Se a sua conta usa essa proteção, a chamada precisa sair de um IP público cadastrado; senão, a resposta é 403 ip_not_allowed. Veja Lista de IPs permitidos.

Erros

As respostas de erro seguem Problem Details, com o código em type:

404 Not Found

{
  "type": "balance.account_not_found",
  "title": "Account was not found.",
  "status": 404
}

HTTP	`type`	Causa	Repetir?
`400`	`balance.invalid_request`	`accountId` ausente ou vazio.	Não.
`400`	URL + `errors`	`accountId` fora do formato UUID.	Não.
`400`	`balance.invalid_type`	`balanceType` diferente dos cinco tipos da tabela.	Não.
`403`	`ip_not_allowed`	IP de origem fora da lista da sua conta.	Não, até cadastrar o IP.
`403`	`{"message":"Forbidden"}`	Chave sem a permissão `balance:read`.	Não. Peça a permissão.
`404`	`balance.account_not_found`	Conta inexistente ou de outra empresa.	Não. Confira o `accountId` e a chave usada.
`422`	`balance.unsupported_currency`	A conta não é BRL nem USD.	Não. Fale com a equipe de integração.
`503`	`balance.unavailable`	Indisponibilidade temporária.	Sim, com espera crescente.
`503`	`ip_allowlist_unavailable`	A lista de IPs não pôde ser conferida.	Sim, em alguns segundos.

Um 404 com o accountId certo quase sempre é a chave da outra operação: a conta offshore só é visível com a chave offshore, e a doméstica, com a doméstica.

Próximo passo

Com saldo disponível, solicite um saque.

RequisiçãoCopiar link da seção

RespostaCopiar link da seção

Tipos de saldoCopiar link da seção

Lista de IPs permitidosCopiar link da seção

ErrosCopiar link da seção