Docs

Consultar saldos correntes

GET /api/v1/integration/balances

Ver Markdown

Requer balances:read. Inclui saldo inicial, ajustes e liquidações; exclui pendentes, compras de cartão não pagas e carteiras arquivadas. Não é projeção nem saldo bancário em tempo real.

Autenticação

Authorization: Bearer. A chave determina o Space. Confira permissões.

Parâmetros

Esta consulta não recebe parâmetros de query.

cURL

curl --fail-with-body "$RURALZAP_BASE_URL/api/v1/integration/balances" \
  -H "Authorization: Bearer $RURALZAP_API_KEY"

TypeScript

// Execute no servidor com Node.js 22+ e tsx. Não registre o payload financeiro.
const base = process.env.RURALZAP_BASE_URL;
const key = process.env.RURALZAP_API_KEY;
if (!base || !key) throw new Error('Configure RURALZAP_BASE_URL e RURALZAP_API_KEY.');
const origin = new URL(base);
if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw new Error('Informe uma origem HTTPS sem caminho ou credenciais.');
const response = await fetch(new URL('/api/v1/integration/balances', origin), {
  headers: { Authorization: `Bearer ${key}` },
  signal: AbortSignal.timeout(30000),
  redirect: 'error',
});
if (!response.ok) throw new Error(`HTTP ${response.status}; consulte /guias/erros.`);
const data: unknown = await response.json();
// Valide data com /openapi.json antes de persistir. Preserve decimais como strings.
export { data };

Python

"""Chamada única, Python 3, servidor. Não registra respostas financeiras."""
import json
import os
import urllib.request
from urllib.parse import urlsplit

base = os.environ['RURALZAP_BASE_URL']
key = os.environ['RURALZAP_API_KEY']
origin = urlsplit(base)
if origin.scheme != 'https' or not origin.netloc or origin.username or origin.password or origin.path not in ('', '/') or origin.query or origin.fragment:
    raise ValueError('Informe uma origem HTTPS sem caminho ou credenciais.')

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(base.rstrip('/') + '/api/v1/integration/balances', headers={'Authorization': 'Bearer ' + key})
with urllib.request.build_opener(NoRedirect).open(request, timeout=30) as response:
    data = json.load(response)
# Valide data com /openapi.json. Preserve dinheiro como string ou Decimal.

Resposta 200

Exemplo sintético, sem dados de clientes.

{
  "generatedAt": "2026-10-03T12:00:00.000Z",
  "data": [
    {
      "id": "019a1000-0000-7000-8000-000000000001",
      "name": "Carteira sintética A",
      "type": "CHECKING",
      "currency": "BRL",
      "includeInNetWorth": true,
      "balance": "1234.5678"
    },
    {
      "id": "019a1000-0000-7000-8000-000000000002",
      "name": "Carteira sintética B",
      "type": "CHECKING",
      "currency": "BRL",
      "includeInNetWorth": false,
      "balance": "-34.5678"
    },
    {
      "id": "019a1000-0000-7000-8000-000000000003",
      "name": "Carteira sintética C",
      "type": "CHECKING",
      "currency": "USD",
      "includeInNetWorth": true,
      "balance": "5.0001"
    }
  ],
  "totals": [
    {
      "currency": "BRL",
      "balance": "1200.0000"
    },
    {
      "currency": "USD",
      "balance": "5.0001"
    }
  ]
}

Campos

CampoTipoObrigatórioSignificado
generatedAtstringSimdate-time
dataarraySimCarteiras ativas; não inclui carteiras arquivadas nem limite disponível de cartão.
data[].idstringSimuuid
data[].namestringSim
data[].typestringSimTipo de carteira do domínio.
data[].currencystringSimMoeda do recurso; valores de moedas distintas não são somados.
data[].includeInNetWorthbooleanSimIndica inclusão da carteira no patrimônio do produto.
data[].balancestringSimSaldo corrente persistido pelo domínio: inclui saldo inicial, ajustes e liquidações; exclui pendentes, canceladas e compras de cartão ainda não pagas.
totalsarraySimSoma dos saldos das carteiras retornadas, por moeda, inclusive carteiras fora do patrimônio.
totals[].currencystringSim
totals[].balancestringSimValor decimal exato com quatro casas; não converter para float.

Erros

HTTPDescrição
400Parâmetros inválidos ou moeda não suportada
401Credencial inválida, expirada, revogada ou de outro ambiente
403Permissão ou acesso ao recurso indisponível
404Filtro ou recurso fora do Space
429Limite excedido; respeite Retry-After
503Indisponibilidade temporária

Consulte causas e soluções. Erros públicos usam error.code, error.message e error.requestId. Em 429, aguarde Retry-After.

Downloads

cURL · TypeScript · Python · OpenAPI

Nesta página