API atual/Referência completa/Dashboards

Catálogo e modelos

O catálogo de entidades, campos e métricas que um card pode usar, e a biblioteca de modelos de card prontos.

Um dashboard é feito de abas (cada aba é uma tela) e cada aba tem cards (cada card é um número ou gráfico). Para montar um card você precisa saber que entidades, campos e métricas existem. Essas duas rotas respondem isso: o catálogo lista o que pode ser consultado, e a biblioteca de modelos traz cards prontos para copiar numa aba.

Catálogo

GET/api/v1/admin/dashboards/catalogAdmin

Catálogo de entidades, campos e métricas

Exemplo de requisição (catálogo)

bash

curl "$BASE_URL/api/v1/admin/dashboards/catalog" \
  -H "Authorization: Bearer $TOKEN"

Resposta (catálogo)

200Catálogo retornado (cortado)

json

{
  "catalog_version": "2026-07-25.1",
  "entities": [
    {
      "name": "orders",
      "label": "admin.dashboards.entity.orders",
      "vendor_safe": true,
      "time_fields": ["created_at", "delivered_at", "shipped_at"],
      "fields": [
        { "ref": "orders.created_at", "label": "admin.dashboards.field.orders.created_at", "type": "timestamp", "groupable": true, "filterable": true, "aggs": ["max", "min"] },
        { "ref": "orders.total", "label": "admin.dashboards.field.orders.total", "type": "money_cents", "groupable": false, "filterable": true, "aggs": ["avg", "max", "min", "sum"], "unit": "cents" }
      ],
      "metrics": [
        { "ref": "orders.revenue", "label": "admin.dashboards.metric.orders.revenue", "type": "money_cents", "unit": "cents", "status_scoped": true }
      ],
      "cohort_keys": [ { "key": "customer", "label": "admin.dashboards.cohort.customer" } ]
    }
  ],
  "grains": [ { "value": "day", "label": "admin.dashboards.grain.day" } ],
  "operators": [ { "value": "eq", "label": "admin.dashboards.op.eq" } ],
  "viz_types": ["kpi", "line", "bar", "pie", "table"],
  "icons": ["TrendingUp", "DollarSign"],
  "palettes": [ { "name": "brand", "colors": ["#0044FF", "#eb6834"] } ],
  "limits": { "max_metrics": 8, "max_dimensions": 3, "filter_depth": 3, "filter_nodes": 40, "max_sets": 2, "max_limit": 1000, "timeout_ms": 5000 }
}

Campos da resposta

catalog_versionstring

Versão do catálogo.

entitiesarray

Cerca de 150 entidades (pedidos, produtos, clientes, estoque, CRM, fiscal, previsões...), em ordem alfabética.

entities[].namestring

Nome da entidade, usado em query.entity.

entities[].labelstring

Chave de tradução do nome. A API devolve a chave, não o texto traduzido.

entities[].vendor_safeboolean

true se a entidade pode ser usada no painel do seller (lojista).

entities[].time_fieldsarray

Campos de data que servem de referência de período.

entities[].fieldsarray

Campos da entidade: ref (entidade.campo), label, type, groupable (pode ser dimensão), filterable, aggs (agregações permitidas), unit e, em campos de status, values.

entities[].metricsarray

Métricas prontas: ref, label, type, unit e status_scoped (true se dependem da classificação de status).

entities[].cohort_keysarray

Chaves aceitas em filtros in_set/not_in_set.

grainsarray

Granularidades de tempo: hour, day, week, month, quarter, year.

operatorsarray

Operadores de filtro.

viz_typesarray

Tipos de visual aceitos em viz.type.

iconsarray

Ícones sugeridos.

palettesarray

Paletas com as cores.

limitsobject

Limites do construtor de cards (veja Especificação do card). timeout_ms é o tempo máximo de uma consulta interativa.

Erros (catálogo)

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"}`
500	Falha inesperada no servidor.	`{"error":"failed to ..."}`

Modelos

GET/api/v1/admin/dashboards/templatesAdmin

Biblioteca de modelos de card

Parâmetros de consulta

categorystring

Filtra por categoria: sales, customers, predictive, products, marketing, inventory, finance, overview, site, support, b2b, integrations, logistics, sellers, fiscal, wms, pos ou uma categoria própria. Vazio devolve todas.

Exemplo de requisição (modelos)

bash

curl "$BASE_URL/api/v1/admin/dashboards/templates?category=sales" \
  -H "Authorization: Bearer $TOKEN"

Resposta (modelos)

200Modelos retornados (cortado)

json

{
  "templates": [
    {
      "slug": "ven-receita-diaria",
      "category": "sales",
      "name_pt": "Receita por dia",
      "name_en": "Daily revenue",
      "description_pt": "Área preenchida da receita diária.",
      "spec": {
        "spec_version": 1,
        "kind": "query",
        "title": "Receita por dia",
        "viz": { "type": "area", "snippet_id": "ven-receita-diaria" },
        "query": {
          "entity": "orders",
          "period": { "mode": "relative", "last_n_days": 30 },
          "metrics": [ { "id": "receita", "ref": "orders.revenue", "kind": "catalog" } ],
          "dimensions": [ { "id": "dia", "field": "orders.created_at", "grain": "day" } ]
        }
      },
      "icon": "CalendarDays",
      "panel": "A",
      "default_width": 2,
      "default_height": 2,
      "is_builtin": true,
      "has_real_data": true,
      "position": 0
    }
  ]
}

Campos da resposta

templatesarray

Modelos, ordenados por categoria e posição. Hoje são mais de 200 modelos prontos.

templates[].slugstring

Identificador do modelo, usado em Criar card a partir de modelo.

templates[].categorystring

Categoria.

templates[].name_ptstring

Nome em português.

templates[].name_enstring

Nome em inglês.

templates[].description_ptstring

Descrição em português.

templates[].specobject

A especificação do card.

templates[].iconstring

Ícone.

templates[].panelstring

AVB

Painel de destino: A administrador, V seller, B ambos. Esta rota só devolve os de A e B.

templates[].default_widthinteger

Largura sugerida, de 1 a 3.

templates[].default_heightinteger

Altura sugerida, de 1 a 3.

templates[].is_builtinboolean

true nos modelos que vêm com a plataforma; false nos que um usuário salvou.

templates[].has_real_databoolean

false quando a loja ainda não tem dados para o modelo mostrar algo útil.

templates[].positioninteger

Ordem dentro da categoria.

templates[].is_mineboolean

true só nos modelos pessoais do usuário que consulta. Ausente nos demais.

Erros (modelos)

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"}`
500	Falha inesperada no servidor.	`{"error":"failed to ..."}`

Veja também

Catálogo e modelos

O catálogo de entidades, campos e métricas que um card pode usar, e a biblioteca de modelos de card prontos.

Catálogo

GET/api/v1/admin/dashboards/catalogAdmin

Catálogo de entidades, campos e métricas

Exemplo de requisição (catálogo)

bash

curl "$BASE_URL/api/v1/admin/dashboards/catalog" \
  -H "Authorization: Bearer $TOKEN"

Resposta (catálogo)

200Catálogo retornado (cortado)

json

{
  "catalog_version": "2026-07-25.1",
  "entities": [
    {
      "name": "orders",
      "label": "admin.dashboards.entity.orders",
      "vendor_safe": true,
      "time_fields": ["created_at", "delivered_at", "shipped_at"],
      "fields": [
        { "ref": "orders.created_at", "label": "admin.dashboards.field.orders.created_at", "type": "timestamp", "groupable": true, "filterable": true, "aggs": ["max", "min"] },
        { "ref": "orders.total", "label": "admin.dashboards.field.orders.total", "type": "money_cents", "groupable": false, "filterable": true, "aggs": ["avg", "max", "min", "sum"], "unit": "cents" }
      ],
      "metrics": [
        { "ref": "orders.revenue", "label": "admin.dashboards.metric.orders.revenue", "type": "money_cents", "unit": "cents", "status_scoped": true }
      ],
      "cohort_keys": [ { "key": "customer", "label": "admin.dashboards.cohort.customer" } ]
    }
  ],
  "grains": [ { "value": "day", "label": "admin.dashboards.grain.day" } ],
  "operators": [ { "value": "eq", "label": "admin.dashboards.op.eq" } ],
  "viz_types": ["kpi", "line", "bar", "pie", "table"],
  "icons": ["TrendingUp", "DollarSign"],
  "palettes": [ { "name": "brand", "colors": ["#0044FF", "#eb6834"] } ],
  "limits": { "max_metrics": 8, "max_dimensions": 3, "filter_depth": 3, "filter_nodes": 40, "max_sets": 2, "max_limit": 1000, "timeout_ms": 5000 }
}

Campos da resposta

catalog_versionstring

Versão do catálogo.

entitiesarray

Cerca de 150 entidades (pedidos, produtos, clientes, estoque, CRM, fiscal, previsões...), em ordem alfabética.

entities[].namestring

Nome da entidade, usado em query.entity.

entities[].labelstring

Chave de tradução do nome. A API devolve a chave, não o texto traduzido.

entities[].vendor_safeboolean

true se a entidade pode ser usada no painel do seller (lojista).

entities[].time_fieldsarray

Campos de data que servem de referência de período.

entities[].fieldsarray

Campos da entidade: ref (entidade.campo), label, type, groupable (pode ser dimensão), filterable, aggs (agregações permitidas), unit e, em campos de status, values.

entities[].metricsarray

Métricas prontas: ref, label, type, unit e status_scoped (true se dependem da classificação de status).

entities[].cohort_keysarray

Chaves aceitas em filtros in_set/not_in_set.

grainsarray

Granularidades de tempo: hour, day, week, month, quarter, year.

operatorsarray

Operadores de filtro.

viz_typesarray

Tipos de visual aceitos em viz.type.

iconsarray

Ícones sugeridos.

palettesarray

Paletas com as cores.

limitsobject

Limites do construtor de cards (veja Especificação do card). timeout_ms é o tempo máximo de uma consulta interativa.

Erros (catálogo)

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"}`
500	Falha inesperada no servidor.	`{"error":"failed to ..."}`

Modelos

GET/api/v1/admin/dashboards/templatesAdmin

Biblioteca de modelos de card

Parâmetros de consulta

categorystring

Exemplo de requisição (modelos)

bash

curl "$BASE_URL/api/v1/admin/dashboards/templates?category=sales" \
  -H "Authorization: Bearer $TOKEN"

Resposta (modelos)

200Modelos retornados (cortado)

json

{
  "templates": [
    {
      "slug": "ven-receita-diaria",
      "category": "sales",
      "name_pt": "Receita por dia",
      "name_en": "Daily revenue",
      "description_pt": "Área preenchida da receita diária.",
      "spec": {
        "spec_version": 1,
        "kind": "query",
        "title": "Receita por dia",
        "viz": { "type": "area", "snippet_id": "ven-receita-diaria" },
        "query": {
          "entity": "orders",
          "period": { "mode": "relative", "last_n_days": 30 },
          "metrics": [ { "id": "receita", "ref": "orders.revenue", "kind": "catalog" } ],
          "dimensions": [ { "id": "dia", "field": "orders.created_at", "grain": "day" } ]
        }
      },
      "icon": "CalendarDays",
      "panel": "A",
      "default_width": 2,
      "default_height": 2,
      "is_builtin": true,
      "has_real_data": true,
      "position": 0
    }
  ]
}

Campos da resposta

templatesarray

Modelos, ordenados por categoria e posição. Hoje são mais de 200 modelos prontos.

templates[].slugstring

Identificador do modelo, usado em Criar card a partir de modelo.

templates[].categorystring

Categoria.

templates[].name_ptstring

Nome em português.

templates[].name_enstring

Nome em inglês.

templates[].description_ptstring

Descrição em português.

templates[].specobject

A especificação do card.

templates[].iconstring

Ícone.

templates[].panelstring

AVB

Painel de destino: A administrador, V seller, B ambos. Esta rota só devolve os de A e B.

templates[].default_widthinteger

Largura sugerida, de 1 a 3.

templates[].default_heightinteger

Altura sugerida, de 1 a 3.

templates[].is_builtinboolean

true nos modelos que vêm com a plataforma; false nos que um usuário salvou.

templates[].has_real_databoolean

false quando a loja ainda não tem dados para o modelo mostrar algo útil.

templates[].positioninteger

Ordem dentro da categoria.

templates[].is_mineboolean

true só nos modelos pessoais do usuário que consulta. Ausente nos demais.

Erros (modelos)

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"}`
500	Falha inesperada no servidor.	`{"error":"failed to ..."}`