Comparação com o mercado

Compara os indicadores da sua loja com loja do mesmo segmento, depois de você aceitar participar.

A comparação com o mercado (benchmark) mostra onde a sua loja está em relação a outras lojas da plataforma do mesmo segmento e porte: ticket médio, receita por cliente, frete médio, aprovação de pagamento, taxa de recompra e pedidos por dia. É opt-in: enquanto a loja não aceitar participar, a leitura devolve só opted_in: false. Ao aceitar, os indicadores da sua loja (janela de 28 dias) passam a compor os percentis de comparação; recusar tem efeito imediato.

Ler a comparação

GET/api/v1/admin/analytics/benchmarksAdmin

Ler a comparação com o mercado

Exemplo de requisição (ler)

bash

curl "$BASE_URL/api/v1/admin/analytics/benchmarks" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler)

200Sem adesão

json

{
  "opted_in": false
}

200Com adesão

json

{
  "opted_in": true,
  "segment": "casa",
  "size_band": "m",
  "window_end": "2026-10-10",
  "kpis": [
    { "kpi": "aov_cents", "mine": 61535, "p25": 42000, "p50": 55000, "p75": 78000, "sample_n": 17, "position": "at_or_above_p50", "delta_bps": 1188 }
  ]
}

Campos da resposta

opted_inboolean

Se a loja aceitou participar.

insufficient_sampleboolean

true quando ainda não há dados da sua loja ou do segmento suficientes. Só aparece nesse caso.

segmentstring

Segmento declarado da loja.

size_bandstring

Porte da loja pelo faturamento mensal médio dos últimos 90 dias: p (abaixo de R$ 50 mil), m (de R$ 50 mil a R$ 500 mil) ou g (acima de R$ 500 mil). Se o grupo do seu porte for pequeno demais, a comparação usa todos os portes do segmento.

window_endstring

Último dia da janela de 28 dias usada, YYYY-MM-DD.

kpisarray

Os indicadores comparados. Um indicador some da lista se o segmento tem menos de 5 lojas nele.

kpis[].kpistring

aov_centsrevenue_per_customer_centsshipping_avg_centspayment_approval_bpsrepurchase_rate_bpsorders_per_day

Nome do indicador.

kpis[].minenumber

Valor da sua loja. Os sufixos _cents estão em centavos, _bps em pontos-base, orders_per_day é um número simples.

kpis[].p25number

Percentil 25 do segmento.

kpis[].p50number

Mediana do segmento.

kpis[].p75number

Percentil 75 do segmento.

kpis[].sample_ninteger

Quantas lojas compõem o grupo.

kpis[].positionstring

below_p25below_p50at_or_above_p50above_p75

Onde a sua loja ficou.

kpis[].delta_bpsinteger

Diferença para a mediana, em pontos-base (1188 = 11,88% acima).

Erros (ler)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Aderir ou sair

PUT/api/v1/admin/analytics/benchmarks/settingsAdmin

Aderir ou sair da comparação

Corpo da requisição

opted_inbooleanobrigatório

true para participar, false para sair (efeito imediato).

segmentstring

modacasaeletroalimentossaude_belezaautoagroconstrucaopetinfantilesporteoutros

Segmento da loja. Valor fora da lista é ignorado em silêncio e o segmento anterior continua valendo.

Exemplo de requisição (configurar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/analytics/benchmarks/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"opted_in": true, "segment": "casa"}'

Resposta (configurar)

204Configuração salva (sem corpo)

text

Erros (configurar)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid body"}`
500	Falha ao salvar.	`{"error":"failed to save benchmark settings"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"manage_settings"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`

Veja também

Comparação com o mercado

Compara os indicadores da sua loja com loja do mesmo segmento, depois de você aceitar participar.

Ler a comparação

GET/api/v1/admin/analytics/benchmarksAdmin

Ler a comparação com o mercado

Exemplo de requisição (ler)

bash

curl "$BASE_URL/api/v1/admin/analytics/benchmarks" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler)

200Sem adesão

json

{
  "opted_in": false
}

200Com adesão

json

{
  "opted_in": true,
  "segment": "casa",
  "size_band": "m",
  "window_end": "2026-10-10",
  "kpis": [
    { "kpi": "aov_cents", "mine": 61535, "p25": 42000, "p50": 55000, "p75": 78000, "sample_n": 17, "position": "at_or_above_p50", "delta_bps": 1188 }
  ]
}

Campos da resposta

opted_inboolean

Se a loja aceitou participar.

insufficient_sampleboolean

true quando ainda não há dados da sua loja ou do segmento suficientes. Só aparece nesse caso.

segmentstring

Segmento declarado da loja.

size_bandstring

window_endstring

Último dia da janela de 28 dias usada, YYYY-MM-DD.

kpisarray

Os indicadores comparados. Um indicador some da lista se o segmento tem menos de 5 lojas nele.

kpis[].kpistring

aov_centsrevenue_per_customer_centsshipping_avg_centspayment_approval_bpsrepurchase_rate_bpsorders_per_day

Nome do indicador.

kpis[].minenumber

Valor da sua loja. Os sufixos _cents estão em centavos, _bps em pontos-base, orders_per_day é um número simples.

kpis[].p25number

Percentil 25 do segmento.

kpis[].p50number

Mediana do segmento.

kpis[].p75number

Percentil 75 do segmento.

kpis[].sample_ninteger

Quantas lojas compõem o grupo.

kpis[].positionstring

below_p25below_p50at_or_above_p50above_p75

Onde a sua loja ficou.

kpis[].delta_bpsinteger

Diferença para a mediana, em pontos-base (1188 = 11,88% acima).

Erros (ler)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Aderir ou sair

PUT/api/v1/admin/analytics/benchmarks/settingsAdmin

Aderir ou sair da comparação

Corpo da requisição

opted_inbooleanobrigatório

true para participar, false para sair (efeito imediato).

segmentstring

modacasaeletroalimentossaude_belezaautoagroconstrucaopetinfantilesporteoutros

Segmento da loja. Valor fora da lista é ignorado em silêncio e o segmento anterior continua valendo.

Exemplo de requisição (configurar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/analytics/benchmarks/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"opted_in": true, "segment": "casa"}'

Resposta (configurar)

204Configuração salva (sem corpo)

text

Erros (configurar)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid body"}`
500	Falha ao salvar.	`{"error":"failed to save benchmark settings"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"manage_settings"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`