O Item Insights entrega KPIs agregados e pré-computados por Item, prontos para alimentar modelos de crédito, underwriting e segmentação. Em vez de você varrer todas as transações, a Malvo já calcula fluxo de caixa, distribuições e razões em janelas temporais fixas.
O Item Insights fica no host único da Malvo: POST https://api.malvo.io/book?itemIds={itemId}. Não existe um subdomínio insights-api — todos os produtos de Inteligência & Enriquecimento são servidos em https://api.malvo.io e autenticados pelo header X-API-KEY.

​
O que é computado

Para cada Item, a resposta é agrupada por classe de conta (bankAccount e creditCard) e, dentro de cada classe, por janela temporal. Cada janela contém:

​
Janelas temporais

Os KPIs são entregues nas janelas M1 (último mês), M3 (3 meses), M12 (12 meses) e allTime (todo o histórico disponível do Item).
Lembre que um Item cobre até 12 meses de histórico de transações. Em Items recém-conectados, janelas mais longas (M12, allTime) podem conter menos dados do que sugerem.

​
Chamar o endpoint

O parâmetro itemIds aceita um ou mais ids de Item, separados por vírgula. A resposta agrupa os insights por Item.
Para vários Items de uma vez, passe-os separados por vírgula:

​
O response

​
Como interpretar

1

Fluxo de caixa

Compare byType.CREDIT (entradas) com byType.DEBIT (saídas) e olhe o creditDebitRatio. Acima de 1 indica que entra mais do que sai na janela.
2

Regularidade de gasto

byDate mostra em quais dias do mês a pessoa transaciona. Concentração no início pode indicar contas e aluguel; no fim, salário e fatura.
3

Perfil de ticket

byAmount revela o tamanho típico das transações. Muitas na faixa 0-50 sugere consumo do dia a dia; presença em 1000-50000 sugere movimentações relevantes.
4

Composição

categories e bySubtype ajudam a entender para onde vai o dinheiro e quanto fica em CHECKING_ACCOUNT vs. SAVINGS_ACCOUNT.
5

Tendência

Compare M1, M3 e M12 para ver se o comportamento é estável, crescente ou em queda — sinal útil para underwriting e segmentação.
Os KPIs são pré-computados: refletem o que a última execução do Item coletou. Eles não disparam uma nova sincronização. Para insights atualizados, garanta que o Item foi re-sincronizado antes de chamar.

​
Quando re-chamar

O Item Insights é recomputado quando o Item é re-sincronizado. Chame o endpoint novamente após uma sincronização — por exemplo, ao receber o webhook item/updated que sinaliza fim da coleta. Não faz sentido re-chamar sem um novo sync: o resultado será idêntico. Veja Sincronizar transações e Webhooks para o ciclo de atualização do Item.

​
Casos de uso

  • Crédito / underwriting — creditDebitRatio, byType, avg/max e composição por categoria alimentam modelos de risco.
  • Segmentação — byAmount e byDate separam perfis de consumo e cadência.
  • Monitoramento — comparar M1 contra M3/M12 detecta mudanças de comportamento.

​
Próximos passos

Enriquecer transações

Categorize e identifique merchants em transações próprias.

Pagamentos recorrentes

Detecte assinaturas, salários e contas recorrentes de um Item.

Sincronizar transações

Re-sincronize o Item antes de recomputar os insights.

Referência da API

O grupo Inteligência & Enriquecimento no playground.