Predições

A plataforma calcula, em segundo plano e de tempos em tempos, dezenas de previsões sobre a sua loja: quantos dias o estoque de um produto dura, qual cliente está prestes a parar de comprar, se um boleto vai ser pago, qual transportadora entrega mais rápido. Cada previsão é guardada com uma confiança e uma validade. As rotas desta seção apenas leem essas previsões já calculadas; elas não disparam cálculo nenhum.

Use-as para mostrar um selo ao lado de um produto numa tela ("estoque acaba em 13 dias"), alimentar um painel de BI ou decidir uma reposição. A tela do administrador usa as mesmas rotas.

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 ids de uma vez, ou o registro completo de uma entidade.

Conceitos-chave

Característica (feature)

O tipo de previsão. O id tem a forma <código>_<nome>, como a1_stock_runway (a letra agrupa a área: A estoque e catálogo, B vendas, C clientes, D preço, E marketing, F sellers, G risco, H logística, I atendimento, J plataforma, K financeiro, P personalização). Na URL você pode usar a1_stock_runway ou stock_runway: as duas valem.

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 que descreve as premissas do cálculo; as chaves variam por característica e não são um contrato estável.

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.

Catálogo de características

A previsão de transmissão ao vivo é lida na URL como e5_live (ou live); e5_live_forecast não é reconhecido e devolve 404.

j1_tenant_churn e j2_upsell são visões da plataforma sobre as lojas: ficam guardadas fora do banco da sua loja e só fazem sentido para a equipe da plataforma. Lê-las por esta rota responde 500.

Endpoints

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 a loja inteira, sem ordem garantida. Em lojas grandes são milhares de linhas.
• Tratar calculating como falha. Significa só que ainda não há previsão vigente.
• Usar um nome de característica inexistente. Dá 404 unknown prediction feature.
• 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 entidade; sem all=1 você recebe só uma.

Próximos passos