# Consultar lançamentos por período Fonte: https://docs.ruralzap.com.br/referencia/transactions GET /api/v1/integration/transactions Requer transactions:read. Ordem createdAt,id crescente. Até 100 itens; período obrigatório de até 366 dias. Inclui pendentes/cancelados, ajustes, transferências e pagamentos de fatura, com flags explícitas; exclui apagados. Não somar todos os lançamentos como receita/despesa: use os relatórios. Paginação não é snapshot; alterações/exclusões durante a travessia podem modificar resultados. ## Autenticação [#autenticação] Authorization: Bearer. A chave determina o Space. Confira [permissões](/guias/autenticacao). ## Parâmetros [#parâmetros] | Nome | Obrigatório | Tipo | Detalhes | | -------------- | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `startDate` | Sim | string | Data financeira inicial inclusiva. Período máximo: 366 dias. date | | `endDate` | Sim | string | Data financeira final inclusiva. date | | `walletId` | Não | string | Carteira do Space. Inclui transferências de entrada e saída dessa carteira. uuid | | `categoryId` | Não | string | Categoria do Space ou categoria compartilhada do seu reseller. uuid | | `costCenterId` | Não | string | Centro(s) de custo por UUID separado por vírgula ou UNCLASSIFIED. Em composições, deve corresponder à mesma parte da categoria e equipamento. | | `assetId` | Não | string | Equipamento do Space atribuído à mesma parte da categoria e centro. uuid | | `type` | Não | string | INCOME, EXPENSE, TRANSFER | | `status` | Não | string | PENDING, COMPLETED, CANCELLED | | `limit` | Não | number | Mínimo: 1 Máximo: 100 Padrão: 50 | | `cursor` | Não | string | nextCursor da página anterior, mantendo todos os filtros e limite. Validade: 24 horas. Não representa snapshot nem sincronização incremental. | ## cURL [#curl] ```bash curl --fail-with-body "$RURALZAP_BASE_URL/api/v1/integration/transactions?startDate=2026-01-01&endDate=2026-01-31" \ -H "Authorization: Bearer $RURALZAP_API_KEY" ``` ## TypeScript [#typescript] ```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/transactions?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 [#python] ```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/transactions?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 [#resposta-200] Exemplo sintético, sem dados de clientes. ```json { "data": [ { "id": "019a1000-0000-7000-8000-000000000001", "reference": "#105", "type": "INCOME", "status": "COMPLETED", "amount": "100.0000", "reportAmount": "1234.5678", "compositionVersion": 0, "compositionLines": [], "currency": "BRL", "description": "Venda sintética de grãos", "date": "2026-01-15", "competenceDate": null, "walletId": null, "categoryId": null, "categoryName": null, "cardId": null, "transferSourceWalletId": null, "transferDestinationWalletId": null, "isAdjustment": false, "isInvoicePayment": false, "ignored": false, "settlementManaged": false, "settledPrincipal": "100.0000", "settledCashAmount": "100.0000", "remainingAmount": "0.0000", "settlementStatus": "PAID", "createdAt": "2026-10-03T12:00:00.000Z", "updatedAt": "2026-10-03T12:00:00.000Z" }, { "id": "019a1000-0000-7000-8000-000000000002", "reference": "#105", "type": "EXPENSE", "status": "COMPLETED", "amount": "200.0000", "reportAmount": "1234.5678", "compositionVersion": 0, "compositionLines": [], "currency": "BRL", "description": "Compra sintética de insumos", "date": "2026-01-15", "competenceDate": null, "walletId": null, "categoryId": null, "categoryName": null, "cardId": null, "transferSourceWalletId": null, "transferDestinationWalletId": null, "isAdjustment": false, "isInvoicePayment": false, "ignored": false, "settlementManaged": false, "settledPrincipal": "200.0000", "settledCashAmount": "200.0000", "remainingAmount": "0.0000", "settlementStatus": "PAID", "createdAt": "2026-10-03T12:00:00.000Z", "updatedAt": "2026-10-03T12:00:00.000Z" }, { "id": "019a1000-0000-7000-8000-000000000003", "reference": "#105", "type": "INCOME", "status": "COMPLETED", "amount": "300.0000", "reportAmount": "1234.5678", "compositionVersion": 0, "compositionLines": [], "currency": "BRL", "description": "Serviço sintético", "date": "2026-01-15", "competenceDate": null, "walletId": null, "categoryId": null, "categoryName": null, "cardId": null, "transferSourceWalletId": null, "transferDestinationWalletId": null, "isAdjustment": false, "isInvoicePayment": false, "ignored": false, "settlementManaged": false, "settledPrincipal": "300.0000", "settledCashAmount": "300.0000", "remainingAmount": "0.0000", "settlementStatus": "PAID", "createdAt": "2026-10-03T12:00:00.000Z", "updatedAt": "2026-10-03T12:00:00.000Z" } ], "meta": { "hasMore": false, "nextCursor": null } } ``` ### Campos [#campos] | Campo | Tipo | Obrigatório | Significado | | ------------------------------------------ | -------------- | ----------- | ------------------------------------------------------------------------------------------------------ | | `data` | array | Sim | | | `data[].id` | string | Sim | uuid | | `data[].reference` | string ou null | Sim | Referência humana; use id como identificador estável. Aceita null. | | `data[].type` | string | Sim | Valores: INCOME, EXPENSE, TRANSFER | | `data[].status` | string | Sim | Valores: PENDING, COMPLETED, CANCELLED | | `data[].amount` | string | Sim | Principal original integral do lançamento, preservado mesmo em recortes analíticos. | | `data[].reportAmount` | string | Sim | Principal considerado pelas partes que atendem simultaneamente aos filtros. Não representa caixa pago. | | `data[].compositionVersion` | number | Sim | Zero identifica classificação legada; versão positiva usa exclusivamente compositionLines. | | `data[].compositionLines` | array | Sim | Composição completa do lançamento para auditoria; não somente as partes filtradas. | | `data[].compositionLines[].id` | string | Sim | uuid | | `data[].compositionLines[].position` | number | Sim | | | `data[].compositionLines[].amount` | string | Sim | Valor exato da parte no principal contratado. | | `data[].compositionLines[].categoryId` | string ou null | Sim | uuid Aceita null. | | `data[].compositionLines[].categoryName` | string ou null | Sim | Aceita null. | | `data[].compositionLines[].costCenterId` | string ou null | Sim | uuid Aceita null. | | `data[].compositionLines[].costCenterName` | string ou null | Sim | Aceita null. | | `data[].compositionLines[].equipmentState` | string | Sim | Valores: NONE, PENDING, LINKED | | `data[].compositionLines[].assetId` | string ou null | Sim | uuid Aceita null. | | `data[].compositionLines[].assetCode` | string ou null | Sim | Aceita null. | | `data[].compositionLines[].assetName` | string ou null | Sim | Aceita null. | | `data[].currency` | string | Sim | | | `data[].description` | string ou null | Sim | Aceita null. | | `data[].date` | string | Sim | date | | `data[].competenceDate` | string ou null | Sim | date Aceita null. | | `data[].walletId` | string ou null | Sim | uuid Aceita null. | | `data[].categoryId` | string ou null | Sim | uuid Aceita null. | | `data[].categoryName` | string ou null | Sim | Aceita null. | | `data[].cardId` | string ou null | Sim | uuid Aceita null. | | `data[].transferSourceWalletId` | string ou null | Sim | uuid Aceita null. | | `data[].transferDestinationWalletId` | string ou null | Sim | uuid Aceita null. | | `data[].isAdjustment` | boolean | Sim | | | `data[].isInvoicePayment` | boolean | Sim | | | `data[].ignored` | boolean | Sim | Lançamento desconsiderado dos indicadores, ainda visível e podendo afetar saldo. | | `data[].settlementManaged` | boolean | Sim | Indica liquidações parciais geridas pelo domínio. | | `data[].settledPrincipal` | string | Sim | Valor decimal exato com quatro casas; não converter para float. | | `data[].settledCashAmount` | string | Sim | Valor decimal exato com quatro casas; não converter para float. | | `data[].remainingAmount` | string | Sim | Valor decimal exato com quatro casas; não converter para float. | | `data[].settlementStatus` | string | Sim | Valores: PAID, PARTIAL, UNPAID | | `data[].createdAt` | string | Sim | date-time | | `data[].updatedAt` | string | Sim | Atualização técnica; não equivale a feed de mudanças. date-time | | `meta` | object | Sim | | | `meta.nextCursor` | string ou null | Sim | Aceita null. | | `meta.hasMore` | boolean | Sim | | ## Erros [#erros] | HTTP | Descrição | | ---- | ------------------------------------------------------------ | | 400 | Parâmetros inválidos ou moeda não suportada | | 401 | Credencial inválida, expirada, revogada ou de outro ambiente | | 403 | Permissão ou acesso ao recurso indisponível | | 404 | Filtro ou recurso fora do Space | | 429 | Limite excedido; respeite Retry-After | | 503 | Indisponibilidade temporária | Consulte [causas e soluções](/guias/erros). Erros públicos usam error.code, error.message e error.requestId. Em 429, aguarde Retry-After. ## Downloads [#downloads] [cURL](/examples/transactions.sh) · [TypeScript](/examples/transactions.ts) · [Python](/examples/transactions.py) · [OpenAPI](/openapi.json)