Datas e valores monetários

DinheiroCopiar link da seção

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 financeirasCopiar link da seção

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çãoCopiar link da seçã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ávelCopiar link da seção

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. Somar todos os lançamentos pode duplicar transferências ou pagamentos de fatura e produzir indicadores incorretos.

Composição e recortes gerenciaisCopiar link da seção

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.