VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dashboards do seller

Executar dados

Executa todos os cards de uma aba, testa uma spec sem salvar e abre as linhas por trás de um ponto do gráfico.

Estas rotas devolvem dados, no formato de dataset descrito na home da seção. Todas aplicam o escopo do seller sozinhas: você não envia nem pode trocar o seller.

Executar a aba

Executa todos os cards ativos da aba em uma chamada (no máximo 4 ao mesmo tempo no servidor) e devolve um resultado por card. Sempre responde 200 quando a aba é visível: a falha de um card aparece no resultado dele e não derruba os demais. Cards component voltam com status: native e sem dados, e cards em rascunho são ignorados.

POST/api/v1/vendor/dashboards/{id}/runSeller

Executar a aba

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Corpo da requisição

periodobject
Período que substitui o da aba. Omitido, vale o período padrão da aba. Campos: mode (inherit, preset, fixed, relative), preset, from, to, last_n_days.
card_idsuuid[]
Executa só estes cards. Omitido: todos.
refreshbooleanpadrão: false
true ignora o cache de resultados.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"period": {"mode": "preset", "preset": "last7"}, "refresh": false}'

Resposta

200Resultado por card
json
{
  "results": [
    {
      "card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
      "status": "ok",
      "dataset": {
        "columns": [
          {
            "key": "receita",
            "label": "receita",
            "type": "money_cents",
            "role": "metric",
            "unit": "cents"
          }
        ],
        "rows": [
          [
            "22500"
          ]
        ],
        "meta": {
          "row_count": 1,
          "truncated": false,
          "limit": 100,
          "elapsed_ms": 4,
          "cached": false,
          "spec_hash": "312585e798d265cb65d345c4d71a3b89fe7b2858565202c0a164d1381b3547fd"
        }
      }
    }
  ],
  "meta": {
    "elapsed_ms": 69,
    "concurrency": 4
  }
}

Campos da resposta

resultsobject[]

Um item por card executado, sem ordem garantida: case por card_id.

results[].card_iduuid
Card (UUID).
results[].statusstring
okerrornative
Resultado do card.
results[].datasetobject
Presente quando status é ok. Veja os campos abaixo.
results[].errorobject
Presente quando status é error: code e message_key.
metaobject
elapsed_ms total e concurrency.
dataset.columnsobject[]
Colunas: key, label, type (money_cents, integer, timestamp, text, order_status...), role (dimension ou metric), unit (cents, bps ou vazio) e, em datas agrupadas, grain.
dataset.rowsarray[]
Linhas, cada uma uma lista de valores na ordem de columns. Dinheiro em centavos vem como texto ("45000"); contagens vêm como número.
dataset.metaobject
row_count, truncated (houve corte pelo limit), limit, elapsed_ms, cached, spec_hash, warnings e error (code e message_key) quando a execução falhou.

Erros

StatusQuandoCorpo de exemplo
404A aba não existe, é de outro seller ou você não pode vê-la. A API responde 404 nos três casos para não revelar que ela existe.{"error":"dashboard not found"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
Período

Cards com period.mode igual a inherit usam o período enviado aqui; sem ele, o período padrão da aba. Cards com período próprio ignoram o valor enviado.

Cache

Os resultados ficam em cache por pouco tempo. meta.cached diz se aquele veio do cache; use refresh: true quando o usuário clicar em atualizar.

Pré-visualizar uma spec

Executa uma spec que ainda não foi salva e devolve o dataset. É a rota do construtor de cards: chame a cada ajuste do usuário.

POST/api/v1/vendor/dashboards/previewSeller

Pré-visualizar uma spec

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

specobjectobrigatório
A spec do card (veja Formato do card).
periodobject
Período que substitui o da aba. Omitido, vale o período padrão da aba. Campos: mode (inherit, preset, fixed, relative), preset, from, to, last_n_days.
limitinteger
Reduz o número máximo de linhas (teto: 1000).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"spec_version": 1, "kind": "query", "title": "Receita por dia", "viz": {"type": "line", "snippet_id": "receita-por-dia", "number_format": {"style": "currency_cents"}}, "query": {"entity": "orders", "period": {"mode": "relative", "last_n_days": 7}, "metrics": [{"id": "receita", "kind": "catalog", "ref": "orders.revenue"}], "dimensions": [{"id": "dia", "field": "orders.created_at", "grain": "day"}], "order": [{"by": "dia", "dir": "asc"}], "limit": 100}}}'

Resposta

200Dataset
json
{
  "dataset": {
    "columns": [
      {
        "key": "dia",
        "label": "dia",
        "type": "timestamp",
        "role": "dimension",
        "unit": "",
        "grain": "day"
      },
      {
        "key": "receita",
        "label": "receita",
        "type": "money_cents",
        "role": "metric",
        "unit": "cents"
      }
    ],
    "rows": [
      [
        "2026-10-09T00:00:00Z",
        "13587"
      ],
      [
        "2026-10-10T00:00:00Z",
        "45000"
      ]
    ],
    "meta": {
      "row_count": 2,
      "truncated": false,
      "limit": 100,
      "elapsed_ms": 1,
      "cached": false,
      "spec_hash": "cab740ceeb25ef1607e5db1c076a8dcb28667660b5927805b55da0361d0eae30"
    }
  }
}

Campos da resposta

datasetobject
O resultado. Um erro de consulta vem em dataset.meta.error, ainda com 200.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid request body"}
403Spec sql sem o privilégio manage_reports.{"error":"manage_reports required for kind=\"sql\" cards"}
422Spec inválida.{"error":"invalid spec","detail":"invalid_spec_version: only spec_version 1 is supported, got 0 (at spec_version)"}
500Falha inesperada ao executar.{"error":"preview failed","detail":"..."}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
Spec `sql` no preview

Um preview de SQL executa o SQL de verdade e é registrado em auditoria. No painel do seller ele só roda com sql.vendor_scope.mode igual a guc.

Detalhar um ponto do gráfico

Devolve as linhas de origem (pedidos, itens, devoluções...) por trás de um ponto do gráfico, com paginação. Você informa os valores das dimensões do ponto clicado e a plataforma os transforma em filtros, somados aos filtros que o card já tinha. Só funciona com cards query (kind: Q).

POST/api/v1/vendor/dashboards/cards/{cardId}/drilldownSeller

Detalhar um ponto do gráfico

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

cardIduuidobrigatório
Id do card (UUID).

Corpo da requisição

dimension_valuesobjectobrigatório
Mapa id da dimensão para o valor clicado, por exemplo {"dia": "2026-10-10"}. Para uma dimensão com grain, informe uma data. {} abre todas as linhas do card.
periodobject
Período que substitui o da aba. Omitido, vale o período padrão da aba. Campos: mode (inherit, preset, fixed, relative), preset, from, to, last_n_days.
pageintegerpadrão: 1
Página, a partir de 1. Máximo 200.
per_pageintegerpadrão: 25
Linhas por página, de 1 a 1000.
langstring
pt-BRen
Idioma dos rótulos das colunas.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57/drilldown" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dimension_values": {}, "per_page": 2}'

Resposta

200Linhas de origem
json
{
  "dataset": {
    "columns": [
      {
        "key": "dd_created_at",
        "label": "Criado em",
        "type": "timestamp",
        "role": "dimension",
        "unit": ""
      },
      {
        "key": "dd_total",
        "label": "Total",
        "type": "money_cents",
        "role": "dimension",
        "unit": "cents"
      },
      {
        "key": "dd_order_number",
        "label": "Pedido",
        "type": "text",
        "role": "dimension",
        "unit": ""
      }
    ],
    "rows": [
      [
        "2026-10-11T02:56:25.843882Z",
        "22500",
        "PEDIDO-20261010-0004"
      ]
    ],
    "meta": {
      "row_count": 1,
      "truncated": false,
      "limit": 2
    }
  },
  "entity": "orders",
  "page": 1,
  "per_page": 2,
  "has_more": true,
  "filters": {},
  "period_from": "2026-10-01",
  "period_to": "2026-10-11"
}

Campos da resposta

datasetobject
As linhas de origem, no formato de dataset (até 8 colunas escolhidas pela plataforma).
entitystring
Entidade consultada.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página.
has_moreboolean
true se há uma próxima página.
filtersobject
Filtros aplicados, por campo do catálogo (por exemplo orders.status).
period_fromstring
Início do período resolvido.
period_tostring
Fim do período resolvido.

Erros

StatusQuandoCorpo de exemplo
400Card que não é de consulta, ou corpo que não é JSON.{"error":"drilldown_requires_query_card"}
404Card inexistente ou de aba que o seller não vê.{"error":"card not found"}
422A entidade não tem colunas para detalhar, ou a consulta não compilou.{"error":"drilldown_no_columns"}
500Falha ao executar.{"error":"drilldown failed"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Veja também

  • Formato do card
  • Catálogo
  • Cards
Anterior
Layout e modelos
Próxima
Catálogo de consulta
Nesta página
  • Executar a aba
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pré-visualizar uma spec
  • Exemplo de requisição
  • Resposta
  • Erros
  • Detalhar um ponto do gráfico
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também