API atual/Referência completa/Dashboards

Especificação do card

O formato JSON que descreve um card do dashboard: tipo, visual, consulta, período, filtros e limites.

Todo card é descrito por uma especificação (spec) em JSON. As rotas de preview, de criação de card e de geração por IA devolvem ou recebem esse mesmo objeto. A especificação não contém SQL: ela diz o que medir, usando nomes do catálogo (Catálogo e modelos), e a plataforma monta e executa a consulta, com o escopo da loja já aplicado.

Estrutura geral

A especificação é estrita: qualquer campo que a API não conhece é recusado com o código unknown_field, em todos os níveis. Campos de layout (linha, coluna, largura, altura) não fazem parte dela; vão ao lado, no corpo da criação do card.

Campos do objeto spec

spec_versionintegerobrigatório

1

Versão do formato. Só existe a 1.

kindstringobrigatório

querysqlcomponentservicetext

Tipo do card. query é o construtor sobre o catálogo (o normal). component é um bloco nativo fixo. service é um relatório pronto da plataforma. text é uma nota livre. sql é SQL escrito à mão e exige o privilégio manage_reports.

titlestringobrigatório

Título, de 1 a 120 caracteres.

subtitlestring

Subtítulo, até 200 caracteres.

vizobjectobrigatório

Como desenhar o resultado (próxima seção).

queryobject

Obrigatório com kind=query; proibido nos outros tipos.

componentobject

Obrigatório com kind=component: { "component_id": "..." }, um de quick_actions, system_status, theme_status, recent_activity, predictive_section, seed_banner.

serviceobject

Obrigatório com kind=service: service_id (da lista fechada abaixo) e args opcional.

textobject

Obrigatório com kind=text: content (até 4000 caracteres), format (markdown ou plain) e align (start ou center).

Os service_id aceitos: order_stats, sales_report, top_products, worst_products, revenue_by_category, orders_by_status, orders_by_status_for_period, orders_by_status_in_range, customer_stats, daily_revenue, repurchase_rate, top_customers, predictive_insights, e, só no painel do administrador, customer_ltv, time_between_orders, rfm_segments, sales_by_day_of_week, monthly_growth, sales_heatmap, sales_by_customer, retention_cohorts, profit_report, channel_report, channel_campaigns, dashboard_data, revenue_by_vendor, shipping_report.

O bloco viz

Campos de viz

typestringobrigatório

kpilineareabarhbarstacked_barpiedonuttableheatmapgaugesparklinefunneltreemapmap_brscattercombopivottextvi_insightnative

Tipo de visual. native é para cards component. Gráficos de barra, linha, área, pizza e rosca exigem pelo menos 1 dimensão; o mapa de calor exige 2.

snippet_idstringobrigatório

Identificador estável do card, minúsculas, números e hífen, de 2 a 63 caracteres (receita-semana). Não mude ao renomear o card.

legendstring

topbottomleftrighthidden

Posição da legenda.

palettestring

brandcategoricalsequentialdivergingcustom

Paleta de cores.

colorsarray

Até 12 cores #RRGGBB.

data_labelsboolean

Mostrar valores sobre o gráfico.

number_formatobject

style (currency_cents, percent, integer, decimal, compact, duration_days, percent_of_total) e decimals (0 a 4).

iconstring

Ícone.

accentstring

Cor de destaque #RRGGBB.

thresholdsarray

Até 5 faixas de cor: op (lt, lte, gt, gte), value, color e label opcional.

compare_displaystring

badgeserieshidden

Como mostrar a comparação com outro período.

O bloco query

Campos de query

entitystringobrigatório

Entidade do catálogo (orders, products, customers...). A lista vem de Catálogo e modelos.

periodobject

Janela de tempo. mode: inherit (usa o período da aba ou do pedido), preset (preset: today, yesterday, last7, last30, last90, thisMonth, lastMonth, thisQuarter, thisYear, lastYear), fixed (from e to, YYYY-MM-DD) ou relative (last_n_days, até 1095). field escolhe o campo de data da entidade.

compareobject

mode: none, previous_period ou previous_year.

metricsarray

Até 8 métricas. Cada uma tem id e kind: catalog (ref, por exemplo orders.revenue), agg (agg: count, count_distinct, sum, avg, min, max, mais field), ratio (num e den com ids de métricas anteriores, scale: raw ou percent) ou constant (value). label é opcional.

dimensionsarray

Até 3 eixos de agrupamento: id, field (entidade.campo), grain opcional (hour, day, week, month, quarter, year) e fill_gaps para preencher períodos sem dado.

filterobject

Árvore de filtros. Um grupo (op: and ou or, com nodes) ou uma comparação (field, cmp, value ou values). Profundidade máxima 3, no máximo 40 nós, no máximo 20 valores em in.

orderarray

Até 2 ordenações: by (id de métrica ou dimensão) e dir (asc ou desc).

limitintegerpadrão: 100

De 1 a 1000 linhas.

other_bucketboolean

Agrupa o que passar do limite numa linha "Outros".

drill_downobject

detail_entity e path (ids de dimensões) para abrir as linhas por trás de um ponto do gráfico.

postarray

Até 6 pós-processamentos de uma métrica: op (cumulative, moving_avg, percent_of_total, rank), metric, window (obrigatório em moving_avg) e output_id.

Operadores de filtro (cmp): eq, ne, gt, gte, lt, lte, between, in, not_in, contains, not_contains, starts_with, ends_with, is_null, is_not_null, last_n_days, next_n_days, overdue, in_set, not_in_set. last_n_days, next_n_days, is_null, is_not_null e overdue não levam value.

Exemplo completo

json

{
  "spec_version": 1,
  "kind": "query",
  "title": "Receita por dia",
  "viz": {
    "type": "line",
    "snippet_id": "receita-por-dia",
    "legend": "bottom",
    "number_format": { "style": "currency_cents" }
  },
  "query": {
    "entity": "orders",
    "period": { "mode": "preset", "preset": "last30" },
    "metrics": [ { "id": "receita", "kind": "catalog", "ref": "orders.revenue" } ],
    "dimensions": [ { "id": "dia", "field": "orders.created_at", "grain": "day", "fill_gaps": true } ],
    "order": [ { "by": "dia", "dir": "asc" } ]
  }
}

Erros de validação

Quando a especificação é inválida, as rotas que a recebem respondem 422 com {"error":"invalid card spec","detail":"<código>: <mensagem>"} (no preview, "error":"invalid spec"). Códigos frequentes: unknown_field (campo desconhecido, ou referência que não existe no catálogo), invalid_spec_version, invalid_kind, invalid_title, invalid_viz_type, missing_snippet_id, invalid_viz_requires_dimension, too_many_metrics, too_many_dimensions, invalid_limit, invalid_period, invalid_operator, filter_too_deep, filter_too_many_nodes, invalid_kind_payload (campos do tipo errado) e invalid_status_scope. A mensagem de detail está em inglês.

Veja também