Consultar saldos correntes
GET /api/v1/integration/balances
Reportar problema nesta página
Copie o relato, descreva a dificuldade e envie pelo suporte disponível no RuralZap. Não inclua chaves ou dados financeiros.
Abrir RuralZap para acessar o suporteRequer 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
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
generatedAt | string | Sim | date-time |
data | array | Sim | Carteiras ativas; não inclui carteiras arquivadas nem limite disponível de cartão. |
data[].id | string | Sim | uuid |
data[].name | string | Sim | |
data[].type | string | Sim | Tipo de carteira do domínio. |
data[].currency | string | Sim | Moeda do recurso; valores de moedas distintas não são somados. |
data[].includeInNetWorth | boolean | Sim | Indica inclusão da carteira no patrimônio do produto. |
data[].balance | string | Sim | Saldo corrente persistido pelo domínio: inclui saldo inicial, ajustes e liquidações; exclui pendentes, canceladas e compras de cartão ainda não pagas. |
totals | array | Sim | Soma dos saldos das carteiras retornadas, por moeda, inclusive carteiras fora do patrimônio. |
totals[].currency | string | Sim | |
totals[].balance | string | Sim | Valor decimal exato com quatro casas; não converter para float. |
Erros
| HTTP | Descrição |
|---|---|
| 400 | Parâmetros inválidos ou moeda não suportada |
| 401 | Credencial inválida, expirada, revogada ou de outro ambiente |
| 403 | Permissão ou acesso ao recurso indisponível |
| 404 | Filtro ou recurso fora do Space |
| 429 | Limite excedido; respeite Retry-After |
| 503 | Indisponibilidade 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