Ler predições

Busca selos compactos de uma característica para vários ids de uma vez, ou o registro completo da previsão de uma entidade.

São duas leituras da mesma informação. A lista devolve um selo compacto por entidade para vários ids numa só chamada: ideal para preencher uma coluna de uma tabela de produtos. A leitura individual devolve o registro completo de uma entidade, com confiança, validade, suposições e todos os campos: ideal para a tela de detalhe.

GET/api/v1/admin/predictions/{feature}Admin

Lista selos de predição de várias entidades

Devolve, para cada id pedido que tenha previsão vigente, a mais recente. Ids sem previsão simplesmente não aparecem na resposta. Qualquer administrador pode chamar; não há privilégio específico.

Parâmetros de caminho

featurestringobrigatório

Característica, por exemplo a1_stock_runway ou stock_runway. Veja o catálogo.

Parâmetros de consulta

idsstring

Ids (UUID) das entidades, separados por vírgula: ids=uuid1,uuid2. Espaços são ignorados. Sem ids a rota devolve todas as entidades da loja, sem limite e sem ordem garantida.

allbooleanpadrão: false

1trueyeson

Com valor verdadeiro, devolve todas as linhas vigentes de cada id (não só uma por entidade), no máximo 200 no total. Serve para características que guardam várias linhas por entidade, como produtos complementares ou degraus de preço. Com um único id, só entram as linhas do cálculo mais recente.

Cabeçalhos

X-Tenant-IDstringobrigatório

Slug ou id da loja.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/admin/predictions/a1_stock_runway?ids=e7a1757e-3f19-421c-836a-684737295885" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: minhaloja"

Resposta (listar)

200Selos retornados

json

{
  "feature": "a1_stock_runway",
  "predictions": [
    {
      "entity_id": "e7a1757e-3f19-421c-836a-684737295885",
      "confidence": 0.764,
      "fields": {
        "daily_velocity": 0.2238,
        "low_confidence": false,
        "revenue_at_risk_cents": 38008,
        "runway_days_p10": 8,
        "runway_days_p50": 13,
        "runway_days_p90": 21,
        "variation_id": null
      }
    }
  ]
}

Campos da resposta

featurestring

A característica pedida, exatamente como você a escreveu na URL.

predictionsarray

Selos. Vazio se nenhum id tem previsão vigente.

predictions[].entity_iduuid

Id da entidade (produto, cliente, pedido...).

predictions[].confidencenumber

Confiança de 0 a 1. Omitido quando a característica não informa.

predictions[].valueany

Valor principal, quando a característica define um. Omitido nas demais.

predictions[].bandany

Faixa ou classe, quando a característica define uma. Omitido nas demais.

predictions[].severitystring

Gravidade (texto), quando a característica define uma. Omitido nas demais.

predictions[].fieldsobject

Colunas específicas da característica. As chaves e os tipos mudam de uma característica para outra. Valores em dinheiro vêm em centavos (revenue_at_risk_cents: 38008 = R$ 380,08).

Erros (listar)

Status	Quando	Corpo de exemplo
400	Falta o cabeçalho `X-Tenant-ID`.	`{"error":"missing tenant"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
404	Característica desconhecida.	`{"error":"unknown prediction feature"}`
500	Falha ao consultar.	`{"error":"failed to load predictions"}`

GET/api/v1/admin/predictions/{feature}/{entityID}Admin

Lê a predição completa de uma entidade

Devolve o registro completo da previsão mais recente da entidade, ou status: calculating se ainda não há previsão vigente. Qualquer administrador pode chamar.

Parâmetros de caminho

featurestringobrigatório

Característica (as mesmas duas formas da lista).

entityIDuuidobrigatório

Id da entidade prevista.

Cabeçalhos

X-Tenant-IDstringobrigatório

Slug ou id da loja.

Exemplo de requisição (uma entidade)

bash

curl "$BASE_URL/api/v1/admin/predictions/a1_stock_runway/e7a1757e-3f19-421c-836a-684737295885" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: minhaloja"

Resposta (uma entidade)

200Predição encontrada

json

{
  "id": 188809,
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "entity_id": "e7a1757e-3f19-421c-836a-684737295885",
  "confidence": 0.764,
  "assumptions": { "horizon_days": 120, "season_m": 7, "seasonality": "weekly_dow" },
  "model_version": "a1_stock_runway@2026.09.1",
  "horizon_days": 120,
  "computed_at": "2026-09-08T06:11:46.308617Z",
  "valid_until": "2027-03-07T06:11:46.308617Z",
  "fields": {
    "daily_velocity": 0.2238,
    "low_confidence": false,
    "revenue_at_risk_cents": 38008,
    "runway_days_p10": 8,
    "runway_days_p50": 13,
    "runway_days_p90": 21,
    "variation_id": null
  }
}

200Ainda sem predição vigente

json

{ "entity_id": "e7a1757e-3f19-421c-836a-684737295885", "status": "calculating" }

Campos da resposta

idinteger

Id interno da linha de previsão.

tenant_iduuid

Id da loja.

entity_iduuid

Id da entidade.

confidencenumber

Confiança de 0 a 1. Omitido quando não informada.

assumptionsobject

Premissas do cálculo, livres e variáveis por característica. Não é um contrato estável.

model_versionstring

Versão do cálculo que gerou a linha (<característica>@<versão>).

horizon_daysinteger

Horizonte da previsão, em dias. Omitido se não se aplica.

computed_atstring

Quando foi calculada (RFC 3339, UTC).

valid_untilstring

Até quando vale (RFC 3339, UTC). Omitido se não expira.

fieldsobject

Colunas específicas da característica, como na lista.

statusstring

calculating

Só aparece (junto com entity_id) quando não há previsão vigente.

Erros (uma entidade)

Status	Quando	Corpo de exemplo
400	Falta o cabeçalho `X-Tenant-ID`.	`{"error":"missing tenant"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
404	Característica desconhecida.	`{"error":"unknown prediction feature"}`
500	Falha ao consultar. Um `entityID` que não corresponde a nada não é erro: responde `200` com `status: calculating`.	`{"error":"failed to load prediction"}`

Veja também

Ler predições

Busca selos compactos de uma característica para vários ids de uma vez, ou o registro completo da previsão de uma entidade.

GET/api/v1/admin/predictions/{feature}Admin

Lista selos de predição de várias entidades

Parâmetros de caminho

featurestringobrigatório

Característica, por exemplo a1_stock_runway ou stock_runway. Veja o catálogo.

Parâmetros de consulta

idsstring

Ids (UUID) das entidades, separados por vírgula: ids=uuid1,uuid2. Espaços são ignorados. Sem ids a rota devolve todas as entidades da loja, sem limite e sem ordem garantida.

allbooleanpadrão: false

1trueyeson

Cabeçalhos

X-Tenant-IDstringobrigatório

Slug ou id da loja.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/admin/predictions/a1_stock_runway?ids=e7a1757e-3f19-421c-836a-684737295885" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: minhaloja"

Resposta (listar)

200Selos retornados

json

{
  "feature": "a1_stock_runway",
  "predictions": [
    {
      "entity_id": "e7a1757e-3f19-421c-836a-684737295885",
      "confidence": 0.764,
      "fields": {
        "daily_velocity": 0.2238,
        "low_confidence": false,
        "revenue_at_risk_cents": 38008,
        "runway_days_p10": 8,
        "runway_days_p50": 13,
        "runway_days_p90": 21,
        "variation_id": null
      }
    }
  ]
}

Campos da resposta

featurestring

A característica pedida, exatamente como você a escreveu na URL.

predictionsarray

Selos. Vazio se nenhum id tem previsão vigente.

predictions[].entity_iduuid

Id da entidade (produto, cliente, pedido...).

predictions[].confidencenumber

Confiança de 0 a 1. Omitido quando a característica não informa.

predictions[].valueany

Valor principal, quando a característica define um. Omitido nas demais.

predictions[].bandany

Faixa ou classe, quando a característica define uma. Omitido nas demais.

predictions[].severitystring

Gravidade (texto), quando a característica define uma. Omitido nas demais.

predictions[].fieldsobject

Colunas específicas da característica. As chaves e os tipos mudam de uma característica para outra. Valores em dinheiro vêm em centavos (revenue_at_risk_cents: 38008 = R$ 380,08).

Erros (listar)

Status	Quando	Corpo de exemplo
400	Falta o cabeçalho `X-Tenant-ID`.	`{"error":"missing tenant"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
404	Característica desconhecida.	`{"error":"unknown prediction feature"}`
500	Falha ao consultar.	`{"error":"failed to load predictions"}`

GET/api/v1/admin/predictions/{feature}/{entityID}Admin

Lê a predição completa de uma entidade

Devolve o registro completo da previsão mais recente da entidade, ou status: calculating se ainda não há previsão vigente. Qualquer administrador pode chamar.

Parâmetros de caminho

featurestringobrigatório

Característica (as mesmas duas formas da lista).

entityIDuuidobrigatório

Id da entidade prevista.

Cabeçalhos

X-Tenant-IDstringobrigatório

Slug ou id da loja.

Exemplo de requisição (uma entidade)

bash

curl "$BASE_URL/api/v1/admin/predictions/a1_stock_runway/e7a1757e-3f19-421c-836a-684737295885" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: minhaloja"

Resposta (uma entidade)

200Predição encontrada

json

{
  "id": 188809,
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "entity_id": "e7a1757e-3f19-421c-836a-684737295885",
  "confidence": 0.764,
  "assumptions": { "horizon_days": 120, "season_m": 7, "seasonality": "weekly_dow" },
  "model_version": "a1_stock_runway@2026.09.1",
  "horizon_days": 120,
  "computed_at": "2026-09-08T06:11:46.308617Z",
  "valid_until": "2027-03-07T06:11:46.308617Z",
  "fields": {
    "daily_velocity": 0.2238,
    "low_confidence": false,
    "revenue_at_risk_cents": 38008,
    "runway_days_p10": 8,
    "runway_days_p50": 13,
    "runway_days_p90": 21,
    "variation_id": null
  }
}

200Ainda sem predição vigente

json

{ "entity_id": "e7a1757e-3f19-421c-836a-684737295885", "status": "calculating" }

Campos da resposta

idinteger

Id interno da linha de previsão.

tenant_iduuid

Id da loja.

entity_iduuid

Id da entidade.

confidencenumber

Confiança de 0 a 1. Omitido quando não informada.

assumptionsobject

Premissas do cálculo, livres e variáveis por característica. Não é um contrato estável.

model_versionstring

Versão do cálculo que gerou a linha (<característica>@<versão>).

horizon_daysinteger

Horizonte da previsão, em dias. Omitido se não se aplica.

computed_atstring

Quando foi calculada (RFC 3339, UTC).

valid_untilstring

Até quando vale (RFC 3339, UTC). Omitido se não expira.

fieldsobject

Colunas específicas da característica, como na lista.

statusstring

calculating

Só aparece (junto com entity_id) quando não há previsão vigente.

Erros (uma entidade)

Status	Quando	Corpo de exemplo
400	Falta o cabeçalho `X-Tenant-ID`.	`{"error":"missing tenant"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
404	Característica desconhecida.	`{"error":"unknown prediction feature"}`
500	Falha ao consultar. Um `entityID` que não corresponde a nada não é erro: responde `200` com `status: calculating`.	`{"error":"failed to load prediction"}`