# Sua primeira consulta

Fonte: https://docs.ruralzap.com.br/comecar

Prepare o acesso, confirme o Space e consulte seus primeiros saldos.





## Antes de começar [#antes-de-começar]

Você precisa de acesso ao RuralZap e do recurso de API habilitado no seu plano ou Space. A documentação é pública; o acesso aos dados depende dessa habilitação. Peça ao responsável pela sua conta a liberação quando o recurso estiver indisponível.

O proprietário do Space cria a integração em **Configurações → API e integrações** no [RuralZap](https://agro.ruralzap.com.br/settings/integrations/api). Escolha um nome reconhecível, prazo de validade e apenas os escopos necessários. Para esta consulta, use `balances:read`.

Se sua conta é oferecida por um parceiro institucional, abra essa mesma seção no painel do parceiro. O domínio do painel pode ser diferente; a documentação é comum em [RuralZap Docs](https://docs.ruralzap.com.br).

A chave é mostrada uma única vez. Guarde-a em um gerenciador de segredos. Não envie a chave a uma IA, ao suporte ou ao repositório.

## 1. Configure seu servidor [#1-configure-seu-servidor]

Use Node.js 22+, Python 3 ou cURL. Configure as variáveis **no ambiente privado do servidor**:

* `RURALZAP_BASE_URL=https://api.finance.meyje.com.br`
* `RURALZAP_API_KEY`: valor da chave recebida, sem aspas extras.

A origem não inclui `/api/v1`. O prefixo das consultas é `/api/v1/integration`.

Essa origem de produção é compartilhada pelos parceiros na mesma instalação. Não troque a URL da API pelo domínio do painel nem por `docs.ruralzap.com.br`: esse é o endereço da documentação. A chave identifica automaticamente a integração, o reseller e o Space autorizados.

Chaves `rzapi_test_…` e `rzapi_live_…` pertencem a ambientes distintos. Um prefixo de teste não cria um sandbox: utilize somente o ambiente fornecido pela equipe. Nossa demonstração é local, sintética e não exige chave.

## 2. Confira o contexto [#2-confira-o-contexto]

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

A resposta informa `integrationId`, `spaceId`, `scopes` e `capabilities`. Confira se é o Space esperado. A chave já determina o Space: não envie `x-space-id`.

## 3. Consulte os saldos [#3-consulte-os-saldos]

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

Leia `data` para o saldo por carteira e `totals` para o total por moeda. `generatedAt` registra quando a resposta foi gerada. Valores como `"12500.0000"` são strings decimais exatas.

## Entenda o resultado [#entenda-o-resultado]

Saldo corrente inclui saldo inicial, ajustes e liquidações. Não representa projeção de contas pendentes nem saldo bancário em tempo real. Carteiras arquivadas não entram na consulta.

Se receber 401, confira a chave e o ambiente. Em 403, confira os escopos e o acesso atual ao recurso. Para 429, respeite o cabeçalho `Retry-After`.

## Próximo passo [#próximo-passo]

Siga a [receita de saldos](/receitas/saldos), consulte a [referência de contexto](/referencia/context) ou use **Preparar prompt de integração** no início desta página.