Sua privacidade

Usamos métricas agregadas para entender o uso do site. Com sua autorização, também usamos cookies de análise e marketing. Você pode alterar sua escolha a qualquer momento.

Saiba mais na nossa Política de Privacidade.

RuralZap na prática

API do RuralZap: leve saldos, lançamentos e fluxo de caixa para suas integrações

Como liberar a API do RuralZap com segurança: o que as seis consultas entregam, como criar a integração e a chave, como ler saldos e relatórios sem erro e o que a API ainda não faz.

7 Nov 2026Por RuralZap6 min de leitura
Página inicial do RuralZap Docs, a documentação da API, com o título Conecte o RuralZap e um exemplo da primeira consulta
Neste artigo

A API do RuralZap permite que outro sistema consulte os dados financeiros da sua fazenda sem que ninguém precise digitar tudo de novo. Ela entrega seis consultas: o contexto da integração, as carteiras, os saldos, os lançamentos, o resumo do período e o fluxo de caixa realizado. É só leitura. Nada é criado, alterado ou apagado por ela.

Este guia é para o produtor que quer levar esses números para um painel de gestão, para a planilha do escritório ou para o sistema do contador ou do consultor. A parte técnica costuma ficar com quem cuida dos sistemas. A decisão de liberar o acesso, e de quanto acesso dar, é sua.

Quando faz sentido usar a API

Faz sentido quando os dados já estão no RuralZap e você precisa deles em outro lugar com frequência. Alguns exemplos:

  • O consultor monta um painel com a fazenda e outras propriedades que ele atende e quer puxar os saldos toda semana.

  • O escritório de contabilidade quer receber os lançamentos do mês sem pedir exportação por mensagem.

  • Você já usa uma ferramenta de automação, como o n8n, e quer montar um relatório próprio com o fluxo de caixa.

Se a necessidade é só olhar os números, o próprio RuralZap já mostra saldos, relatórios e lançamentos no painel. A API resolve outra coisa: levar os dados para um sistema que você ou sua equipe já usam.

Antes de começar: a API precisa estar liberada

A documentação é pública, mas o acesso aos dados não vem ligado em toda conta. A API depende de estar incluída no plano ou de uma liberação feita pela equipe do RuralZap para aquele Espaço. Os relatórios de resumo e de fluxo de caixa pedem também a permissão de relatórios na chave e o recurso de fluxo de caixa liberado, conforme a documentação de permissões.

O sinal mais simples está nas configurações. Se o card API e integrações aparece em Configurações, o acesso está liberado no seu Espaço. Se não aparece, a API ainda não está disponível no seu Espaço.

Outro ponto: cada integração pertence a um único Espaço. Quem tem duas fazendas em Espaços separados precisa de uma integração para cada uma.

Passo 1: crie a integração

Quem cria a integração é o proprietário do Espaço, no painel web do RuralZap, em Configurações > API e integrações. Clique em Criar integração e preencha três coisas:

  • Nome da integração. Use um nome que diga para quem é o acesso, como "Painel do consultor" ou "Escritório contábil". Isso ajuda a saber o que suspender depois.

  • Validade da chave, em dias. Prefira um prazo curto para um teste e um prazo definido para o uso contínuo. Quando vencer, a chave para de funcionar.

  • Permissões. Marque só o que o sistema vai usar. Para ver saldos e carteiras, a permissão de saldos basta. Lançamentos e relatórios têm permissões próprias.

Clique em Criar e mostrar chave. O RuralZap mostra a chave uma única vez. Guarde-a em um gerenciador de segredos e conceda acesso apenas ao responsável pela configuração.

Passo 2: entregue a chave com cuidado

A chave dá acesso aos números da fazenda. Trate como trataria a senha do banco.

  • Não mande a chave em grupo de WhatsApp, e-mail aberto ou print.

  • Não cole a chave em ferramentas de inteligência artificial, chamados de suporte ou planilhas compartilhadas.

  • A chave fica no servidor ou na ferramenta de automação, guardada como segredo. Não a inclua em URLs, logs ou repositórios, nem em relatórios ou arquivos que circulam pela equipe.

Se desconfiar que a chave vazou, revogue. Depois disso, novas chamadas com ela são recusadas.

Passo 3: a primeira consulta

Quem cuida da parte técnica segue o roteiro de primeira consulta da documentação. O primeiro teste é a consulta de contexto. Ela mostra a qual Espaço a chave pertence e quais permissões ela tem. Serve para confirmar que o acesso é da fazenda certa antes de puxar qualquer número.

Depois vem a consulta de saldos, que traz o saldo por carteira e o total. A documentação também traz um passo a passo para o n8n, além de exemplos prontos em cURL, Python e TypeScript, e uma demonstração local com dados fictícios para entender as respostas sem usar dado real.

O guia técnico completo fica no RuralZap Docs.

O que os números da API significam

Antes de montar o painel, confira com o responsável pela integração como interpretar os valores.

  • Saldo não é projeção. O saldo inclui saldo inicial, ajustes e o que já foi pago ou recebido. Contas pendentes e compras no cartão ainda não pagas ficam de fora. Também não é o saldo do banco em tempo real.

  • Os relatórios são do realizado. O resumo e o fluxo de caixa da API mostram o que já aconteceu. O fluxo de caixa projetado continua no painel do RuralZap.

  • Somar lançamentos não é fazer relatório. A lista de lançamentos traz também pendentes, cancelados, ajustes, transferências entre contas e pagamentos de fatura. Quem soma tudo sem filtrar pode contar o mesmo dinheiro duas vezes. Para entradas, saídas e saldo do período, o caminho é usar os relatórios da própria API, que seguem o mesmo cálculo do relatório do produto.

Os relatórios e os lançamentos aceitam filtro por categoria, centro de custo e equipamento. Assim o painel pode mostrar, por exemplo, só o que foi gasto com uma máquina. Nesse caso, o relatório informa que se trata de um recorte, que não representa o saldo inteiro da carteira. A documentação dos dados financeiros explica como ler esses valores.

Depois de ligada: renovar, suspender e revogar

A integração fica listada em Suas integrações, na mesma tela. Ali você pode:

  • Renovar a chave antes de vencer. Você define por quantas horas a chave antiga continua valendo junto com a nova, para dar tempo de trocar no sistema conectado.

  • Suspender a integração quando o trabalho com aquele consultor ou sistema parar por um tempo.

  • Revogar a chave quando o acesso não for mais necessário ou houver suspeita de vazamento.

Vale revisar essa lista de tempos em tempos. Acesso que ninguém usa mais deve ser fechado.

O que a API ainda não faz

A API é de consulta. Ela não registra despesa, não lança receita, não dá baixa em conta e não reclassifica nada. O registro continua pelo WhatsApp ou pelo painel. Ela também não avisa sozinha quando algo muda: o sistema conectado precisa consultar de novo para ter o dado atualizado.

Se você tem um painel, um contador ou um consultor que hoje recebe os números por planilha, confira com o suporte se a API pode ser liberada para o seu Espaço. Para os outros recursos do dia a dia, a Central de Ajuda do RuralZap reúne guias e vídeos.

#api#integrações#n8n#segurança de dados

Compartilhe este artigo

Ajude outros produtores rurais com este conteúdo

RuralZap

RuralZap

Equipe RuralZap

Especialistas em inovação, gestão rural e tecnologia para o agronegócio. Construindo o futuro do campo com inteligência.