VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Recursos e métricas

Métricas dos sellers

Define quais status de pedido contam nas métricas e quais cartões aparecem no painel de métricas de cada seller, e replica a configuração para todos.

O painel de métricas do seller mostra receita, pedidos, ticket médio, recompra e outros cartões. Esta configuração decide quais pedidos entram na conta (pelos status) e quais cartões aparecem. Cada seller pode ter a sua; a loja guarda um padrão que vale para quem não tem. As três rotas exigem o módulo metrics-config ativo e os privilégios de conteúdo: view_content ou manage_content para ler, manage_content para gravar.

Ler configuração

GET/api/v1/admin/metrics-configAdmin

Configuração de métricas de um seller ou da loja

Parâmetros de consulta

vendor_iduuid
Seller a consultar. Sem o parâmetro, devolve a configuração no nível da loja.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/metrics-config?vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "included_statuses": [
    "B",
    "C",
    "G",
    "H",
    "K",
    "P"
  ],
  "cards": {
    "revenue": true,
    "orders": true,
    "customers": true,
    "ticket": true,
    "repurchase": true,
    "ltv": false,
    "avg_days": true,
    "rfm": true,
    "sales_evolution": true,
    "customer_donut": true,
    "weekday": true,
    "growth": true,
    "status_donut": true,
    "heatmap": true,
    "order_search": true,
    "top_customers": true,
    "recent_orders": true
  },
  "has_own_config": true,
  "default_source_vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
}

Campos da resposta

vendor_idstring
O seller da configuração; vazio é a configuração da loja (o padrão).
included_statusesarray
Letras de status de pedido que contam nas métricas (por exemplo só os pagos e concluídos). Padrão: B, C, G, H, K, P. O significado de cada letra é definido por loja.
cardsobject
Um booleano por cartão do painel de métricas. Chaves: revenue, orders, customers, ticket, repurchase, ltv, avg_days, rfm, sales_evolution, customer_donut, weekday, growth, status_donut, heatmap, order_search, top_customers, recent_orders. true mostra o cartão.
has_own_configboolean
true quando o seller (ou a loja) tem configuração própria gravada; false quando está herdando o padrão.
default_source_vendor_idstring
Seller cuja configuração foi salva como padrão da loja. Ausente se ninguém salvou.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}
403O módulo metrics-config não está ativo nesta loja.{"error":"module_disabled","module":"metrics-config"}
500Falha ao ler.{"error":"failed to load metrics config","detail":"..."}
Herança do padrão

Para cada valor, vale o do seller; se ele não tem, o padrão da loja; se a loja não tem, o padrão da plataforma (status B, C, G, H, K, P e todos os cartões ligados). Um vendor_id inexistente não dá erro: volta o padrão.

Gravar configuração

PUT/api/v1/admin/metrics-configAdmin

Grava a configuração de um seller

Corpo da requisição

vendor_iduuid
Seller a configurar. Vazio grava no nível da loja.
included_statusesarray
Letras de status que contam nas métricas. Envie a lista completa: lista vazia, ou omitir o campo, grava "nenhum status" (não o padrão).
cardsobject
Mapa cartão para booleano. Ao enviar o mapa, chave ausente ou false esconde o cartão; só true mostra. Se cards for omitido por inteiro, todos os cartões aparecem. Veja as chaves em Ler configuração.
save_as_defaultbooleanpadrão: false
true grava também como padrão da loja e marca este seller como origem do padrão.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/metrics-config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "included_statuses": ["C", "K"], "cards": {"revenue": true, "orders": true, "ticket": true}, "save_as_default": false}'

Resposta

200Configuração salva
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "included_statuses": [
    "C",
    "K"
  ],
  "cards": {
    "revenue": true,
    "orders": true,
    "customers": true,
    "ticket": true,
    "repurchase": true,
    "ltv": false,
    "avg_days": true,
    "rfm": true,
    "sales_evolution": true,
    "customer_donut": true,
    "weekday": true,
    "growth": true,
    "status_donut": true,
    "heatmap": true,
    "order_search": true,
    "top_customers": true,
    "recent_orders": true
  },
  "has_own_config": true,
  "default_source_vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
}

O corpo é a configuração como ficou depois de gravar, no formato de Ler configuração.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content"]}
403O módulo metrics-config não está ativo nesta loja.{"error":"module_disabled","module":"metrics-config"}
400JSON inválido ou falha ao gravar.{"error":"invalid json","detail":"..."}
Cartão omitido some

A gravação é completa, não parcial: todo cartão que você não enviar como true é gravado como oculto. Envie sempre o mapa inteiro.

Replicar para todos

POST/api/v1/admin/metrics-config/replicateAdmin

Copia a configuração de um seller para a loja e todos os sellers ativos

Corpo da requisição

vendor_iduuidobrigatório
Seller de origem. A configuração dele (ou o padrão, se não tiver) é a que será copiada.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/metrics-config/replicate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"}'

Resposta

200Replicado
json
{
  "ok": true
}

Campos da resposta

okboolean
Sempre true em caso de sucesso.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_content"]}
403O módulo metrics-config não está ativo nesta loja.{"error":"module_disabled","module":"metrics-config"}
400JSON inválido.{"error":"invalid json","detail":"..."}
500Falha ao replicar (a mensagem indica o seller em que parou).{"error":"failed to replicate","detail":"replicate ...: ..."}
Sobrescreve a configuração de todos

A configuração de todos os sellers ativos e a da loja passam a ser iguais à do seller de origem. Não há desfazer; leia as configurações antes se precisar guardá-las.

Veja também

  • Chaves de recursos
  • Painel de indicadores
Anterior
Recursos nativos
Próxima
Indicadores e relatórios
Nesta página
  • Ler configuração
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar configuração
  • Exemplo de requisição
  • Resposta
  • Erros
  • Replicar para todos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também