API atual/Referência completa/Dashboards do seller

GETCatálogo de consulta

Lista as entidades, campos, métricas, operadores, limites e tipos de gráfico que o seller pode usar ao montar um card.

O catálogo é o vocabulário do construtor de cards: tudo o que uma spec pode referenciar. Chame-o uma vez ao abrir o construtor. Para o seller, o catálogo já vem filtrado: só aparecem as entidades seguras para sellers (vendor_safe: true), como pedidos, itens, produtos, categorias, devoluções, avaliações, promoções e comissões. Dados de clientes e de outros sellers não estão nele.

GET/api/v1/vendor/dashboards/catalogSeller

Consultar o catálogo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

bash

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

Resposta

200Catálogo (resumido a uma entidade)

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": [
            "sum",
            "avg",
            "min",
            "max"
          ],
          "unit": "cents"
        }
      ],
      "metrics": [
        {
          "ref": "orders.revenue",
          "label": "admin.dashboards.metric.orders.revenue",
          "type": "money_cents",
          "unit": "cents",
          "status_scoped": true
        }
      ]
    }
  ],
  "grains": [
    {
      "label": "admin.dashboards.grain.day",
      "value": "day"
    }
  ],
  "operators": [
    {
      "label": "admin.dashboards.op.eq",
      "value": "eq"
    }
  ],
  "viz_types": [
    "kpi",
    "line",
    "bar"
  ],
  "icons": [
    "TrendingUp"
  ],
  "palettes": [
    {
      "name": "brand",
      "colors": [
        "#0044FF",
        "#eb6834"
      ]
    }
  ],
  "limits": {
    "filter_depth": 3,
    "filter_nodes": 40,
    "max_dimensions": 3,
    "max_limit": 1000,
    "max_metrics": 8,
    "max_sets": 2,
    "timeout_ms": 5000
  }
}

Campos da resposta

catalog_versionstring

Versão do catálogo; muda quando entidades ou campos mudam.

entitiesobject[]

Entidades consultáveis.

entities[].namestring

Nome da entidade, usado em query.entity.

entities[].labelstring

Chave de tradução, não texto pronto (por exemplo admin.dashboards.entity.orders).

entities[].vendor_safeboolean

Sempre true para o seller.

entities[].time_fieldsstring[]

Campos de data que podem ser o eixo do período (period.field).

entities[].fieldsobject[]

Campos: ref (entidade.campo), label, type, groupable, filterable, aggs (agregações permitidas), unit e, para status, values com value, label e color.

entities[].metricsobject[]

Métricas prontas: ref, label, type, unit e status_scoped (depende de quais status contam como venda).

grainsobject[]

Granularidades de data: value (hour, day, week, month, quarter, year) e label.

operatorsobject[]

Operadores de filtro (value e label); os de conjunto trazem arity: set.

viz_typesstring[]

Tipos de gráfico aceitos em viz.type.

iconsstring[]

Ícones sugeridos.

palettesobject[]

Paletas com name e colors.

limitsobject

max_metrics, max_dimensions, filter_depth, filter_nodes, max_sets, max_limit e timeout_ms (tempo máximo de uma consulta interativa).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`
500	Falha ao montar o catálogo.	`{"error":"failed to build catalog","detail":"..."}`

Veja também