Esta página completa o contrato da F2 com a previsão de caixa do perfil financeiro. A previsão parte do mesmo caixa próprio e dos mesmos títulos do diagnóstico de liquidez e projeta o saldo dia a dia em dois cenários, cada um com as premissas que usou.
  • Cenários não são intervalo de confiança. O conservador e o base descrevem premissas diferentes, não a probabilidade de um resultado. A resposta não tem probabilidade, percentual de acerto nem faixa estatística.
  • Recebíveis do ERP não são dinheiro garantido. Eles só entram no cenário base, na data prevista informada pelo ERP. O conservador não considera nenhuma entrada.
  • A Malvo não dá baixa no ERP nem altera o saldo bancário. A previsão é leitura dos dados vinculados ao perfil, não a solvência da empresa.
Todos os exemplos usam dados sintéticos.

​
Chaves do módulo

Todas nascem desligadas. Ligada a primeira chave, forecast_version=f1 entra no data_version: o primeiro cálculo depois de ligar gera resultado e previsão novos. A previsão roda no cálculo versionado do perfil e não faz chamada nova à instituição.

​
Liberação por horizonte

Os horizontes de 7, 15 e 30 dias são liberados separadamente, conforme a qualidade medida na avaliação. Todo horizonte é calculado e guardado; o não liberado sai na rota com state: not_released, reasons vazio e scenarios vazio, sem nenhum valor. Liberar um horizonte depois não recalcula nada: a rota passa a mostrar a previsão já guardada.

​
Regras do cálculo (f1)

  • Saldo inicial (starting_balance): o own_cash_available da F1, o mesmo do diagnóstico. position_at é a posição bancária mais antiga entre as contas (updateDateTime da API Contas), o instante em que todas as posições já valiam. Sem caixa próprio elegível, amount sai null; sem posição conhecida, position_at sai null.
  • Pontos diários: um por dia civil em America/Sao_Paulo, do dia de referência até o fim exclusivo do horizonte. 7 dias são 7 pontos. Referência 25/02/2026 e 7 dias: pontos de 25/02 a 03/03, fim em 04/03/2026 00h00. É a mesma janela do diagnóstico.
  • Fechamento do dia: closing = opening + inflows − outflows; o opening do dia seguinte é o closing do anterior.
  • min_closing: o menor fechamento do cenário (em empate, o primeiro dia). first_negative_date: o primeiro dia com fechamento abaixo de zero, ou null.
  • Valores: strings decimais, como no resto do perfil, com a escala preservada e no mínimo 2 casas: "1000.0400" − "0.2000" = "999.8400". Some com tipo decimal, nunca com float64.

​
Cenários e premissas

Cada cenário traz em premises os códigos que usou, com uma descrição em pt-BR.
  • Conservador: só saídas conhecidas. A reserva efetiva dos títulos vencidos e das liquidações não observadas sai no dia de referência; cada título a pagar sai na data de vencimento pela reserva efetiva; cada fatura de cartão elegível sai no vencimento, já sem a parte coberta por título vinculado. Nenhuma entrada.
  • Base: tudo do conservador, mais os recebíveis do ERP em aberto na data prevista (vencidos a receber ficam fora) e as recorrências publicadas de conta em BRL, na data esperada da próxima janela: entrada pelo menor valor observado, saída pelo maior. Uma recorrência que cobre um título ou uma fatura na mesma janela e no mesmo valor (dentro da tolerância) conta uma vez só, pelo título.
  • Entradas variáveis (vendas no cartão, Pix avulsos) sem padrão publicado não são estimadas. Sem nenhuma recorrência elegível, o base fica limited com reasons: ["no_eligible_patterns"].

​
Componentes (kind)

Cada dia lista em components o que moveu o saldo, agrupado por kind, com as referências ordenadas em refs.

​
Estados

​
Estado do horizonte

​
Estado do cenário

​
Rotas

Todas as regras comuns do perfil financeiro valem aqui: header X-API-KEY, valores em string decimal, instantes em UTC com Z e nenhuma chamada nova à instituição.

​
GET /financial-profiles/{id}/forecasts

Sem parâmetros, devolve a previsão publicada do resultado atual do perfil.
O exemplo usa o caso de referência: dia de referência 13/10/2026, caixa próprio 18000.00, um título vencido a pagar de 4000.00, um título a pagar de 20000.00 com vencimento em 15/10, um recebível de 8000.00 previsto para 16/10 e nenhuma recorrência publicada. Só o horizonte de 7 dias está liberado (FINANCIAL_PROFILE_FORECAST_RELEASED_HORIZONS=7).
200 Previsão atual
Leitura do exemplo:
  • Conservador: 13/10 fecha 14000.00 (sai o vencido), 14/10 14000.00, 15/10 -6000.00 (sai o título) e de 16 a 19/10 -6000.00. Primeiro negativo em 15/10, mínimo -6000.00.
  • Base: igual até 15/10; em 16/10 entra o recebível e o saldo fecha 2000.00. Fica limited com no_eligible_patterns, porque não há recorrência publicada.
  • 15 e 30 dias estão calculados e guardados, mas não liberados.
Com uma recorrência de saída de 1500.00 com data esperada em 20/10, o horizonte de 7 dias não muda (20/10 está fora); no de 15 dias, só o base recebe recurrence_outflow em 20/10 e fecha 500.00. Se essa recorrência fosse de 20000.00 e ligada ao título de 15/10, contaria uma vez só, pelo título: o base continuaria -6000.00 em 15/10.

​
Histórico

?published_before=<RFC 3339>&limit=<1..100> ativa o modo histórico (basta um dos dois). limit padrão 20. A resposta lista as previsões publicadas, da mais nova para a mais antiga, cada uma no mesmo formato da previsão atual. Para a próxima página, use o published_at da última como published_before.
200 Histórico
No exemplo, a previsão de 12/10 foi publicada antes da primeira carga do ERP: todos os horizontes calculados ficaram unavailable com agenda_missing.

​
Erros

404 FORECAST_NOT_FOUND
Quando a fonte é revogada, a previsão anterior não é apresentada como atual: a rota responde 404 FORECAST_NOT_FOUND até um cálculo novo ser publicado.

​
Publicação e imutabilidade

  • A previsão é publicada junto com o resultado do perfil, na mesma transação, uma por cálculo. Depois de publicada, nunca é editada nem recalculada.
  • Correção de dado (carga nova, conciliação, revisão de classificação) muda o data_version e gera cálculo e previsão novos. A anterior continua no histórico como foi publicada.
  • Fonte revogada durante o cálculo: nenhuma previsão nova é publicada.
  • data_version é o do cálculo do perfil com o prefixo sha256:. No resumo ele continua só em hexadecimal.

​
Como a previsão é avaliada (FR-026)

A qualidade de cada horizonte é medida depois, comparando a previsão com o saldo que de fato aconteceu. A avaliação é um processo interno e offline da Malvo: não tem rota pública, não liga nem desliga horizonte sozinha e não faz chamada à instituição.
  • Previsão como foi publicada. A avaliação lê a previsão guardada e nunca a recalcula. Uma correção posterior de dado não muda o erro de uma previsão antiga.
  • Saldo observado do dia D: a última posição elegível com updateDateTime até o fim do dia D em America/Sao_Paulo, em todas as contas. Dia sem posição observada sai da conta com motivo, sem interpolação.
  • Comparação com baselines. B0: último saldo conhecido menos as obrigações conhecidas nas datas de vencimento. Sazonal: só com pelo menos 3 meses completos de histórico; com menos, sai como not_applicable.
  • Métricas por horizonte e cenário: erro absoluto médio em reais (decimal), erro normalizado pela média do saldo absoluto observado e acerto na antecipação de insuficiência por dia (verdadeiros e falsos positivos e negativos).
  • Ganho sobre o baseline: 1 − erro(previsão) / erro(baseline). Um horizonte só é candidato à liberação com ganho de pelo menos 10% sobre o B0, decidido por horizonte.
  • Separação temporal: a janela usada para ajustar regras e a janela avaliada não se sobrepõem.
  • O resultado sai por horizonte, instituição e segmento, com os perfis excluídos e os motivos.

​
Dados e retenção

  • A previsão é dado derivado. Fica guardada por até 13 meses, limitada à vigência das fontes: quando uma fonte é revogada, as previsões que dependem dela são invalidadas e eliminadas em até 15 dias.
  • Nenhum valor bancário ou de título vai para log.

​
Base normativa

  • API Contas do Open Finance Brasil 2.5.1 (api_accounts_-_open_finance_brasil/2.5.1.yaml, lido em 12/10/2026): AccountBalancesData.updateDateTime como posição do saldo inicial e do saldo observado na avaliação; amount como string ^-?\d{1,15}\.\d{2,4}$.
  • Contrato obligation-import-v1 (Títulos do ERP — contrato v1): decimais textuais em BRL, vencimento e direção dos títulos.
  • IN BCB nº 615, de 6/5/2025, art. 1º e 3º, vigência a partir de 1º/7/2025, e Manual de APIs do Open Finance Brasil v7.0, seção 5.2, item V: a previsão e a avaliação leem só o que já foi sincronizado; nenhuma chamada nova à instituição.
  • Lei nº 13.709/2018 (LGPD), art. 6º, I e III, 15 e 16, e a política de retenção da Malvo aprovada em 10/10/2026 (item 2, dados derivados).
  • PRD v1.3, seções 12 e 17 (FR-024 a FR-026), AC-021, AC-023, AC-025 e AC-029. Cenários, premissas, baseline, ganho mínimo de 10% e liberação por horizonte são regras de produto, sem norma externa.