# Consultar saldos correntes

Fonte: https://docs.ruralzap.com.br/referencia/balances

GET /api/v1/integration/balances





<!-- Gerado por scripts/generate.mjs. Não editar. -->

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 [#autenticação]

Authorization: Bearer. A chave determina o Space. Confira [permissões](/guias/autenticacao).

## Parâmetros [#parâmetros]

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

## cURL [#curl]

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

## TypeScript [#typescript]

```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 [#python]

```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 [#resposta-200]

Exemplo sintético, sem dados de clientes.

```json
{
  "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 [#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 [#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](/guias/erros). Erros públicos usam error.code, error.message e error.requestId. Em 429, aguarde Retry-After.

## Downloads [#downloads]

[cURL](/examples/balances.sh) · [TypeScript](/examples/balances.ts) · [Python](/examples/balances.py) · [OpenAPI](/openapi.json)