Docs

Consultar fluxo de caixa realizado

GET /api/v1/integration/reports/cashflow

Ver Markdown

Requer reports:read e CASHFLOW_REPORT. Período máximo 366 dias. Mesmo cálculo do relatório do produto, com valores decimais exatos. groupBy: day, week ou month. Não inclui projeções de pendentes.

Autenticação

Authorization: Bearer. A chave determina o Space. Confira permissões.

Parâmetros

NomeObrigatórioTipoDetalhes
startDateSimstringData financeira inicial inclusiva. Período máximo: 366 dias. date
endDateSimstringData financeira final inclusiva. date
walletIdNãostringCarteira do Space. Inclui transferências de entrada e saída dessa carteira. uuid
categoryIdNãostringCategoria do Space ou categoria compartilhada do seu reseller. uuid
costCenterIdNãostringCentro(s) de custo por UUID separado por vírgula ou UNCLASSIFIED. Em composições, deve corresponder à mesma parte da categoria e equipamento.
assetIdNãostringEquipamento do Space atribuído à mesma parte da categoria e centro. uuid
groupByNãostringday, week, month Padrão: month

cURL

curl --fail-with-body "$RURALZAP_BASE_URL/api/v1/integration/reports/cashflow?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer $RURALZAP_API_KEY"

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/reports/cashflow?startDate=2026-01-01&endDate=2026-01-31', 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

"""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/reports/cashflow?startDate=2026-01-01&endDate=2026-01-31', 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

Exemplo sintético, sem dados de clientes.

{
  "meta": {
    "generatedAt": "2026-10-03T12:00:00.000Z",
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "timezone": "America/Sao_Paulo",
    "walletId": null,
    "categoryId": null,
    "costCenterId": null,
    "assetId": null,
    "mode": "cash",
    "groupBy": "month"
  },
  "currency": "BRL",
  "summary": {
    "openingBalance": "1000.0000",
    "totalInflows": "600.0000",
    "totalOutflows": "400.0000",
    "netCashflow": "200.0000",
    "totalAdjustments": "0.0000",
    "closingBalance": "1200.0000"
  },
  "data": [
    {
      "period": "2026-01",
      "inflows": "600.0000",
      "outflows": "400.0000",
      "netFlow": "200.0000",
      "adjustments": "0.0000",
      "runningBalance": "1200.0000"
    }
  ]
}

Campos

CampoTipoObrigatórioSignificado
metaobjectSim
meta.generatedAtstringSimdate-time
meta.startDatestringSimdate
meta.endDatestringSimdate
meta.timezonestringSimReferência de negócio. Datas financeiras são date-only e não sofrem conversão de fuso.
meta.walletIdstring ou nullSimuuid Aceita null.
meta.categoryIdstring ou nullSimuuid Aceita null.
meta.costCenterIdstring ou nullSimAceita null.
meta.assetIdstring ou nullSimuuid Aceita null.
meta.modestringSimcash é a visão completa das carteiras; slice é recorte gerencial e não equivale ao saldo bancário integral. Valores: cash, slice
meta.groupBystringSimValores: day, week, month
currencystringSimRelatórios suportam BRL; uma combinação de moedas não é convertida nem somada.
summarystringSimResumo do fluxo de caixa realizado. Requer o recurso CASHFLOW_REPORT.
dataarraySim
data[].periodstringSimChave canônica do período; períodos sem movimentos podem estar ausentes.
data[].inflowsstringSimValor decimal exato com quatro casas; não converter para float.
data[].outflowsstringSimValor decimal exato com quatro casas; não converter para float.
data[].netFlowstringSimValor decimal exato com quatro casas; não converter para float.
data[].adjustmentsstringSimValor decimal exato com quatro casas; não converter para float.
data[].runningBalancestringSimValor decimal exato com quatro casas; não converter para float.

Erros

HTTPDescrição
400Parâmetros inválidos ou moeda não suportada
401Credencial inválida, expirada, revogada ou de outro ambiente
403Permissão ou acesso ao recurso indisponível
404Filtro ou recurso fora do Space
429Limite excedido; respeite Retry-After
503Indisponibilidade temporária

Consulte causas e soluções. Erros públicos usam error.code, error.message e error.requestId. Em 429, aguarde Retry-After.

Downloads

cURL · TypeScript · Python · OpenAPI

Nesta página