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.
📚 Artigos Relacionados
Como consultar entradas e saídas da fazenda pelo WhatsApp
Veja como perguntar ao RuralZap pelo WhatsApp o saldo das contas, o total de entradas e saídas, os gastos por categoria e os lançamentos do período.
Ler maisConheça a Central de Ajuda do RuralZap: guias e vídeos para o dia a dia
Encontre orientações para usar o RuralZap pelo WhatsApp e pelo painel. Veja como buscar guias, acompanhar vídeos e conferir os recursos do seu espaço.
Ler mais