Visão geral

A avaliação da loja é a reputação que o marketplace calcula a partir de como a loja cumpre o que promete: cancela pouco, despacha no prazo, entrega no prazo e é bem avaliada pelos compradores. É somente leitura pela API: você acompanha a nota atual e o histórico de variações, mas não altera nada.

Opera mais de uma loja sob a mesma empresa? Veja Matriz e sublojas: como funciona o modo espelho e como descobrir as lojas do seu grupo de faturamento.

Use esses dados para espelhar a reputação da loja no seu ERP, disparar alertas quando um índice cai, ou montar um painel interno de qualidade.

Ambas as rotas exigem o escopo store_rating_read no token.

Conceitos

Índices (metrics): quatro notas independentes, cada uma de 0 a 10. Todas são uma taxa sobre o volume da loja na janela, nunca uma contagem absoluta: uma loja grande não é punida por vender mais.

Cada índice traz o número que o gerou: sample (o volume considerado), hits (as ocorrências: cancelados, no prazo), rate (a taxa, de 0 a 1) e weight (o peso na nota geral).

Volume mínimo (min_sample): com sample abaixo do mínimo, o índice vem com score: null e fica fora da nota geral. Uma loja com dois pedidos no mês não ganha nem perde reputação por eles.

Nota geral (overall): média ponderada dos índices que têm nota, de 0 a 10, com os pesos redistribuídos entre eles. Sem nenhum índice com nota, overall vem null.

Estado (status):

Atualização: a nota não é calculada na consulta. Ela é recalculada periodicamente para todas as lojas (refresh_interval_minutes, hoje de hora em hora) e a rota devolve o último cálculo. computed_at diz quando foi, next_update_at quando deve ser o próximo, e period_start / period_end a janela usada (period_days). Leia sempre esses campos em vez de fixar o período na sua aplicação.

Histórico: cada registro é um acontecimento pontual (uma avaliação recebida, um cancelamento, uma entrega concluída), com direction (up ou down) e value (o tamanho do acontecimento). Serve para auditar o que aconteceu com a loja e quando.

O objeto que o resumo devolve:

{
  "store": { … },                    // dados da loja (mesmo shape da sessão)
  "rating": {
    "status": "ok",                  // ok | insufficient | pending
    "overall": 8.63,                 // nota geral, 0-10 (null sem nota)
    "metrics": {
      "cancellations": { "score": 8, "weight": 0.3, "sample": 120, "min_sample": 5, "hits": 3, "rate": 0.025, "max_rate": 0.1 },
      "dispatch":      { "score": 9, "weight": 0.3, "sample": 100, "min_sample": 5, "hits": 90, "rate": 0.9, "avg_hours": 21.4, "sla_hours": 48 },
      "delivery":      { "score": 8.5, "weight": 0.2, "sample": 40, "min_sample": 5, "hits": 34, "rate": 0.85, "failed": 1 },
      "reviews":       { "score": 9.17, "weight": 0.2, "sample": 12, "min_sample": 3, "hits": null, "rate": null, "avg_rating": 4.67 }
    },
    "subjects": { … },               // mesmas notas com os nomes antigos (ver abaixo)
    "period_days": 30,
    "computed_at": "2026-10-01T15:05:00.000000Z",    // quando a nota foi calculada
    "next_update_at": "2026-10-01T16:05:00.000000Z", // próximo cálculo previsto
    "refresh_interval_minutes": 60,
    "period_start": "2026-09-01T15:05:00.000000Z",   // início da janela
    "period_end": "2026-10-01T15:05:00.000000Z"      // fim da janela
  }
}

Como exibir

• trate score: null como "ainda sem volume", nunca como nota zero. Um 0 é nota de verdade;
• mostre o motivo junto da nota: hits de sample diz muito mais que o número sozinho;
• não precisa consultar mais de uma vez por ciclo: entre dois cálculos a resposta é a mesma.

Nomes antigos (subjects)

Integrações antigas liam subjects com cinco critérios. Ele continua vindo, com as notas novas nos nomes antigos: cancel_counts = cancelamentos, shipping_time = despacho, shipping = entrega, selling = avaliações e support sempre null. Para integração nova, use metrics.

Resumo

Devolve a nota geral, o detalhe de cada índice, o estado e quando a nota foi calculada, junto com os dados da loja. Não recebe parâmetros.

Histórico

Lista paginada das variações de nota, da mais recente para a mais antiga. Segue o envelope paginado padrão (data.data + data.meta.pagination).

Cada registro traz subject, direction, value, um meta livre e o occurred_at.

O histórico é um registro de acontecimentos, não a fonte da nota: a nota é calculada a partir dos pedidos e avaliações da janela, e os números que a explicam já vêm em metrics no resumo. Use o histórico para auditar quando cada acontecimento ocorreu; ele não é filtrado pela janela do resumo.

O que pode dar errado

Para onde ir agora