Visão geral

A avaliação da loja é a reputação que o marketplace calcula a partir das notas dadas pelos compradores nos pedidos entregues. É 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 critério cai, ou montar um painel interno de qualidade.

Ambas as rotas exigem o escopo store_rating_read no token.

Conceitos

Critérios (subjects): cinco notas independentes, cada uma de 0 a 10.

Nota geral (overall): média ponderada dos critérios, de 0 a 10. É a nota que resume a reputação da loja.

Janela de apuração (period_start / period_end): a nota olha só para os registros dos últimos 90 dias. A janela é móvel e recalculada a cada consulta — period_end é o instante da chamada. Leia sempre os dois campos em vez de fixar o período na sua aplicação.

Histórico: cada registro é uma variação pontual em um critério, com direction (up ou down) e value (o tamanho da variação). Serve para entender o que puxou a nota para cima ou para baixo, e quando.

O objeto que o resumo devolve:

{
  "store": { … },              // dados da loja (mesmo shape da sessão)
  "rating": {
    "subjects": {              // ← notas por critério, 0-10
      "shipping": 8.5,
      "support": 9.2,
      "selling": 7.8,
      "shipping_time": 8,
      "cancel_counts": 9.5
    },
    "overall": 8.6,            // ← nota geral, 0-10
    "period_start": "2026-01-13T00:00:00-03:00", // início da janela
    "period_end": "2026-04-13T23:59:59-03:00"    // fim da janela
  }
}

Como ler um critério em 0

Um critério sem nenhum registro na janela vem como 0. Isso significa "sem dados", não "nota ruim" — e esse critério fica de fora do cálculo da nota geral, que é reponderada entre os critérios que têm registro. Por isso uma loja pode ter shipping: 0 e ainda assim um overall alto.

Se a loja não tiver registro nenhum na janela, tudo volta em 0: os cinco critérios e o overall. É o caso de uma loja recém-criada.

Na prática, para exibir a reputação:

• não trate 0 como nota; trate como "ainda não avaliado";
• confira o histórico antes de alertar sobre uma queda — sem registro na janela não há queda, há ausência;
• o overall não vem arredondado. Arredonde na sua exibição.

Resumo

Devolve a nota atual em cada critério, a nota geral e a janela de apuração, junto com os dados da loja. Não recebe parâmetros. O cálculo acontece na hora da consulta, então duas chamadas seguidas podem trazer janelas com segundos de diferença.

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 não é filtrado pela janela do resumo: ele guarda os registros como aconteceram. Se quiser explicar a nota atual, filtre por from usando o period_start que veio no resumo.

O que pode dar errado

Para onde ir agora