# Datas e valores monetários

Fonte: https://docs.ruralzap.com.br/guias/dados-financeiros

Preserve a precisão e o significado financeiro das respostas.





## Dinheiro [#dinheiro]

Valores monetários são strings com quatro casas decimais: `"1234.5678"`. Preserve esse formato no transporte e armazenamento. Use biblioteca decimal ou inteiros escalados para calcular; não use float, `parseFloat` ou `Number` para somar dinheiro.

Moedas diferentes não são somadas. Saldos vêm agrupados por moeda; relatórios desta versão suportam BRL.

## Datas financeiras [#datas-financeiras]

`startDate`, `endDate` e datas de negócio usam `YYYY-MM-DD`, sem horário. O intervalo inclui os dois extremos e tem no máximo 366 dias. Não converta essas datas para UTC ou para o fuso do navegador.

`createdAt`, `updatedAt` e `generatedAt` são instantes com horário. Não os confunda com competência ou data financeira. Relatórios informam o contexto de negócio `America/Sao_Paulo`.

## Saldo não é projeção [#saldo-não-é-projeção]

Saldos incluem abertura, ajustes e liquidações e excluem pendências e compras de cartão não pagas. Fluxo de caixa e resumo são realizados, não projeções de valores futuros.

## Lançamentos não são um relatório somável [#lançamentos-não-são-um-relatório-somável]

A listagem inclui pendentes, cancelados, ajustes, transferências e pagamentos de fatura, com indicadores explícitos. Use `id` como identificador estável. Observe `ignored`, `isAdjustment`, `isInvoicePayment` e os campos de liquidação.

Para indicadores, use os [relatórios oficiais](/receitas/relatorios). Somar todos os lançamentos pode duplicar transferências ou pagamentos de fatura e produzir indicadores incorretos.

## Composição e recortes gerenciais [#composição-e-recortes-gerenciais]

Uma compra continua sendo um lançamento, mesmo quando dividida em categorias, centros e equipamentos. `amount` é o principal original integral; `reportAmount` é o principal considerado pelas partes que atendem aos filtros. Ambos são strings com quatro casas. Os campos de liquidação do lançamento continuam descrevendo o original integral.

`compositionVersion` igual a zero identifica a classificação legada. Uma versão positiva usa exclusivamente `compositionLines`, com valores exatos e referências legíveis. A resposta contém a composição completa para auditoria, inclusive as partes que não entraram no recorte. Categoria ausente no cabeçalho pode significar categorias diferentes entre as partes; não escolha a primeira como categoria da compra.

`categoryId`, `costCenterId` e `assetId` precisam corresponder à mesma parte. `costCenterId` aceita UUIDs separados por vírgula ou `UNCLASSIFIED`: nas composições, este último considera somente partes sem centro; no legado, lançamentos sem rateio. Equipamentos arquivados continuam identificáveis no histórico autorizado.

Nos relatórios, `meta.mode` informa `cash` para a visão completa ou `slice` para um recorte gerencial. O caixa usa a data e os componentes da baixa: principal, acréscimos e desconto são distribuídos separadamente, com precisão de quatro casas. Abertura e fechamento de um recorte não representam o saldo bancário integral da carteira. Estornos retiram a atribuição da baixa original; reclassificações atualizam a leitura gerencial corrente preservando a auditoria.

A API permanece somente leitura. Esses campos não habilitam criação, reclassificação ou baixa por API pública.