Predições

A plataforma calcula, em segundo plano e de tempos em tempos, dezenas de previsões: quantos dias o estoque de um produto dura, qual produto corre risco de ruptura, qual preço rende mais. Cada previsão é guardada com uma confiança e uma validade. As rotas desta seção apenas leem previsões já calculadas; elas não disparam cálculo nenhum.

Use-as para mostrar um selo ao lado de um produto na sua lista ("estoque acaba em 13 dias"), alimentar um painel de BI ou decidir uma reposição. O painel do seller usa as mesmas rotas. Para o seller, a leitura é limitada ao que é seu.

Como funciona

1. A plataforma calcula

   Um processo em segundo plano recalcula cada característica e grava uma linha por entidade, com data de cálculo (computed_at) e validade (valid_until).

2. Você confere a saúde

   Saúde das predições mostra, por característica, se o último cálculo funcionou e quando rodou.

3. Você lê

   Ler predições devolve selos compactos para vários produtos de uma vez, ou o registro completo de um.

Conceitos-chave

Característica (feature)

O tipo de previsão. O id tem a forma <código>_<nome>, como a1_stock_runway. Na URL você pode usar a1_stock_runway, stock_runway ou pred_stock_runway: as três valem. Um nome que não existe responde 404 unknown prediction feature.

Confiança, validade e suposições

confidence vai de 0 a 1 e pode faltar. valid_until é a data a partir da qual a previsão não é mais devolvida. assumptions é um objeto livre com as premissas do cálculo; as chaves variam por característica e não são um contrato estável. Valores em dinheiro dentro de fields vêm em centavos.

O que o seller enxerga

A leitura só devolve linhas cuja entidade é um produto seu ou o próprio seller. As características abaixo têm esse tipo de entidade. As demais características da plataforma (clientes, pedidos, indicadores da loja inteira) existem, mas ficam fora do alcance do seller: na listagem não aparecem e na leitura individual respondem status: calculating.

Dados de demonstração

Em lojas de teste, as previsões podem ter sido geradas a partir de dados sintéticos. O campo assumptions costuma indicar isso. Não use previsões de uma loja de teste para decisões reais.

Rotas

Erros comuns

• Esquecer o X-Tenant-ID. Dá 400 missing tenant nas duas rotas de leitura (a de saúde não exige).
• Listar sem ids. Devolve todas as previsões do seu seller, sem ordem garantida. Em catálogos grandes são milhares de linhas.
• Tratar calculating como falha. Significa só que não há previsão vigente, ou que o id não é seu.
• Pedir previsões de clientes ou pedidos. Para o seller elas vêm vazias, não como erro.
• Esperar uma lista pelo ids em características de várias linhas por entidade. Algumas (como a6_cross_sell e d3_b2b_tiers) guardam várias linhas por produto; sem all=1 você recebe só uma.

Próximos passos