Sua primeira consulta

Antes de começarCopiar link da seção

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. 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.

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 servidorCopiar link da seção

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 contextoCopiar link da seção

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 saldosCopiar link da seção

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 resultadoCopiar link da seção

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 passoCopiar link da seção

Siga a receita de saldos, consulte a referência de contexto ou use Preparar prompt de integração no início desta página.