API atual/Referência completa/Dashboards

Abas: listar e consultar

Lista as abas do dashboard que o usuário pode ver e devolve uma aba com os cards dela.

O dashboard do painel é um conjunto de abas, como as abas de um navegador. Cada aba tem um nome, um período padrão e vários cards. A lista devolve as abas que o usuário pode ver: a aba de fábrica (que existe em toda loja), as que ele criou e as que outras pessoas compartilharam com ele. A consulta de uma aba devolve a aba e seus cards sem dados: para obter os números, chame Executar a aba.

Listar abas

GET/api/v1/admin/dashboardsAdmin

Listar abas do dashboard

Exemplo de requisição (listar)

bash

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

Resposta (listar)

200Abas retornadas

json

{
  "dashboards": [
    {
      "id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a",
      "slug": "fabrica",
      "name": "Dashboard",
      "panel": "A",
      "visibility": "G",
      "is_system": true,
      "is_default": true,
      "position": 0,
      "icon": "atividade",
      "color": "#0044FF",
      "default_period": { "mode": "preset", "preset": "last30" },
      "created_at": "2026-07-27T01:51:13.388795Z",
      "updated_at": "2026-09-05T22:48:45.737166Z",
      "version": 1788648525737,
      "is_owner": false,
      "permission": "R",
      "kind": "normal"
    }
  ]
}

Campos da resposta

dashboardsarray

Abas visíveis para o usuário, no painel do administrador. Cada item tem os campos abaixo.

dashboards[].iduuid

Id da aba.

dashboards[].slugstring

Identificador de texto único dentro do painel. Em abas criadas pela API é um UUID; a aba de fábrica tem um nome fixo.

dashboards[].namestring

Nome mostrado na aba.

dashboards[].panelstring

AV

A para o painel do administrador, V para o painel do seller (lojista).

dashboards[].owner_user_iduuid|null

Dono da aba. Ausente na aba de fábrica.

dashboards[].vendor_iduuid|null

Seller dono, só nas abas do painel do seller.

dashboards[].visibilitystring

PSG

P privada (só o dono e quem recebeu compartilhamento), S compartilhada (via compartilhamentos), G global (todos os administradores veem).

dashboards[].is_systemboolean

true na aba de fábrica: não pode ser renomeada nem apagada, só duplicada.

dashboards[].is_defaultboolean

true na aba que abre primeiro.

dashboards[].positioninteger

Ordem da aba na barra de abas.

dashboards[].iconstring

Nome do ícone (texto livre; o painel usa uma lista própria de ícones).

dashboards[].colorstring

Cor da aba, normalmente #RRGGBB. Texto livre, não validado.

dashboards[].default_periodobject

Período padrão da aba, no formato de period (veja Especificação do card). Cards com período inherit usam este.

dashboards[].created_atstring

Criação, RFC 3339 UTC.

dashboards[].updated_atstring

Última alteração, RFC 3339 UTC.

dashboards[].versioninteger

Token de versão do layout (milissegundos Unix de updated_at). Envie-o em Reorganizar o layout.

dashboards[].is_ownerboolean

Se quem consulta é o dono. Só é confiável em listagem e consulta; nas respostas de criação e alteração vem false.

dashboards[].permissionstring

WR

W pode editar, R só leitura. Ausente nas respostas de escrita.

dashboards[].kindstring

normalvi_insights

normal, ou vi_insights para a aba de insights da Venddor Intelligence.

Erros (listar)

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 ..."}`

Consultar uma aba

GET/api/v1/admin/dashboards/{id}Admin

Consultar uma aba com seus cards

Parâmetros de caminho

iduuidobrigatório

Id da aba (UUID).

Exemplo de requisição (consultar)

bash

curl "$BASE_URL/api/v1/admin/dashboards/56a570ca-f6a1-4483-ba89-55bcea0b5c4a" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Aba e cards

json

{
  "dashboard": { "id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a", "name": "Dashboard", "panel": "A", "is_system": true, "version": 1788648525737 },
  "cards": [
    {
      "id": "310f23a9-0000-4000-8000-000000000001",
      "dashboard_id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a",
      "spec": {
        "spec_version": 1,
        "kind": "query",
        "title": "Receita ao Longo do Tempo",
        "viz": { "type": "line", "snippet_id": "revenue-over-time" },
        "query": { "entity": "orders", "period": { "mode": "inherit" }, "metrics": [ { "id": "receita", "ref": "orders.revenue", "kind": "catalog" } ], "dimensions": [ { "id": "dia", "field": "orders.created_at", "grain": "day", "fill_gaps": true } ] }
      },
      "spec_version": 1,
      "kind": "Q",
      "title": "Receita ao Longo do Tempo",
      "grid_row": 0,
      "grid_col": 0,
      "width": 2,
      "height": 2,
      "order": 16,
      "status": "A",
      "source": "T",
      "template_slug": "fab-revenue-over-time"
    }
  ]
}

Campos da resposta

dashboardobject

A aba, com os campos descritos em Listar abas.

cardsarray

Cards da aba (a aba de fábrica traz cerca de 27), todos os ativos, no formato abaixo.

cards[].iduuid

Id do card.

cards[].dashboard_iduuid

Aba dona do card.

cards[].specobject

A especificação do card, devolvida como foi gravada (com a classificação de status materializada em métricas de receita). Veja Especificação do card.

cards[].spec_versioninteger

Versão do formato da especificação. Hoje só 1.

cards[].kindstring

QSCVT

Tipo, derivado de spec.kind: Q consulta, S SQL livre, C componente nativo, V serviço de relatório, T texto.

cards[].titlestring

Título do card (cópia de spec.title).

cards[].grid_rowinteger

Linha da grade, a partir de 0.

cards[].grid_colinteger

Coluna da grade, de 0 a 2 (a grade tem 3 colunas).

cards[].widthinteger

Largura em colunas, de 1 a 3.

cards[].heightinteger

Altura em linhas, de 1 a 3.

cards[].orderinteger

Ordem de exibição.

cards[].statusstring

ADX

A ativo, D rascunho, X reservado. Só cards ativos entram na execução da aba.

cards[].sourcestring

MIT

Origem: M manual, I inserido por insight, T criado a partir de modelo.

cards[].template_slugstring|null

Modelo de origem, quando source é T.

cards[].approved_by_user_iduuid|null

Quem aprovou, só em cards de SQL livre.

cards[].approved_atstring|null

Quando foi aprovado.

cards[].created_byuuid|null

Quem criou.

cards[].created_atstring

Criação, RFC 3339.

cards[].updated_atstring

Última alteração, RFC 3339.

Erros (consultar)

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"}`
404	A aba não existe, não é sua ou não está visível para você. A API responde 404 em vez de 403 para não revelar que o id existe.	`{"error":"dashboard not found"}`
500	Falha inesperada no servidor.	`{"error":"failed to ..."}`

Veja também

Abas: listar e consultar

Lista as abas do dashboard que o usuário pode ver e devolve uma aba com os cards dela.

Listar abas

GET/api/v1/admin/dashboardsAdmin

Listar abas do dashboard

Exemplo de requisição (listar)

bash

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

Resposta (listar)

200Abas retornadas

json

{
  "dashboards": [
    {
      "id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a",
      "slug": "fabrica",
      "name": "Dashboard",
      "panel": "A",
      "visibility": "G",
      "is_system": true,
      "is_default": true,
      "position": 0,
      "icon": "atividade",
      "color": "#0044FF",
      "default_period": { "mode": "preset", "preset": "last30" },
      "created_at": "2026-07-27T01:51:13.388795Z",
      "updated_at": "2026-09-05T22:48:45.737166Z",
      "version": 1788648525737,
      "is_owner": false,
      "permission": "R",
      "kind": "normal"
    }
  ]
}

Campos da resposta

dashboardsarray

Abas visíveis para o usuário, no painel do administrador. Cada item tem os campos abaixo.

dashboards[].iduuid

Id da aba.

dashboards[].slugstring

Identificador de texto único dentro do painel. Em abas criadas pela API é um UUID; a aba de fábrica tem um nome fixo.

dashboards[].namestring

Nome mostrado na aba.

dashboards[].panelstring

AV

A para o painel do administrador, V para o painel do seller (lojista).

dashboards[].owner_user_iduuid|null

Dono da aba. Ausente na aba de fábrica.

dashboards[].vendor_iduuid|null

Seller dono, só nas abas do painel do seller.

dashboards[].visibilitystring

PSG

P privada (só o dono e quem recebeu compartilhamento), S compartilhada (via compartilhamentos), G global (todos os administradores veem).

dashboards[].is_systemboolean

true na aba de fábrica: não pode ser renomeada nem apagada, só duplicada.

dashboards[].is_defaultboolean

true na aba que abre primeiro.

dashboards[].positioninteger

Ordem da aba na barra de abas.

dashboards[].iconstring

Nome do ícone (texto livre; o painel usa uma lista própria de ícones).

dashboards[].colorstring

Cor da aba, normalmente #RRGGBB. Texto livre, não validado.

dashboards[].default_periodobject

Período padrão da aba, no formato de period (veja Especificação do card). Cards com período inherit usam este.

dashboards[].created_atstring

Criação, RFC 3339 UTC.

dashboards[].updated_atstring

Última alteração, RFC 3339 UTC.

dashboards[].versioninteger

Token de versão do layout (milissegundos Unix de updated_at). Envie-o em Reorganizar o layout.

dashboards[].is_ownerboolean

Se quem consulta é o dono. Só é confiável em listagem e consulta; nas respostas de criação e alteração vem false.

dashboards[].permissionstring

WR

W pode editar, R só leitura. Ausente nas respostas de escrita.

dashboards[].kindstring

normalvi_insights

normal, ou vi_insights para a aba de insights da Venddor Intelligence.

Erros (listar)

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 ..."}`

Consultar uma aba

GET/api/v1/admin/dashboards/{id}Admin

Consultar uma aba com seus cards

Parâmetros de caminho

iduuidobrigatório

Id da aba (UUID).

Exemplo de requisição (consultar)

bash

curl "$BASE_URL/api/v1/admin/dashboards/56a570ca-f6a1-4483-ba89-55bcea0b5c4a" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Aba e cards

json

{
  "dashboard": { "id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a", "name": "Dashboard", "panel": "A", "is_system": true, "version": 1788648525737 },
  "cards": [
    {
      "id": "310f23a9-0000-4000-8000-000000000001",
      "dashboard_id": "56a570ca-f6a1-4483-ba89-55bcea0b5c4a",
      "spec": {
        "spec_version": 1,
        "kind": "query",
        "title": "Receita ao Longo do Tempo",
        "viz": { "type": "line", "snippet_id": "revenue-over-time" },
        "query": { "entity": "orders", "period": { "mode": "inherit" }, "metrics": [ { "id": "receita", "ref": "orders.revenue", "kind": "catalog" } ], "dimensions": [ { "id": "dia", "field": "orders.created_at", "grain": "day", "fill_gaps": true } ] }
      },
      "spec_version": 1,
      "kind": "Q",
      "title": "Receita ao Longo do Tempo",
      "grid_row": 0,
      "grid_col": 0,
      "width": 2,
      "height": 2,
      "order": 16,
      "status": "A",
      "source": "T",
      "template_slug": "fab-revenue-over-time"
    }
  ]
}

Campos da resposta

dashboardobject

A aba, com os campos descritos em Listar abas.

cardsarray

Cards da aba (a aba de fábrica traz cerca de 27), todos os ativos, no formato abaixo.

cards[].iduuid

Id do card.

cards[].dashboard_iduuid

Aba dona do card.

cards[].specobject

A especificação do card, devolvida como foi gravada (com a classificação de status materializada em métricas de receita). Veja Especificação do card.

cards[].spec_versioninteger

Versão do formato da especificação. Hoje só 1.

cards[].kindstring

QSCVT

Tipo, derivado de spec.kind: Q consulta, S SQL livre, C componente nativo, V serviço de relatório, T texto.

cards[].titlestring

Título do card (cópia de spec.title).

cards[].grid_rowinteger

Linha da grade, a partir de 0.

cards[].grid_colinteger

Coluna da grade, de 0 a 2 (a grade tem 3 colunas).

cards[].widthinteger

Largura em colunas, de 1 a 3.

cards[].heightinteger

Altura em linhas, de 1 a 3.

cards[].orderinteger

Ordem de exibição.

cards[].statusstring

ADX

A ativo, D rascunho, X reservado. Só cards ativos entram na execução da aba.

cards[].sourcestring

MIT

Origem: M manual, I inserido por insight, T criado a partir de modelo.

cards[].template_slugstring|null

Modelo de origem, quando source é T.

cards[].approved_by_user_iduuid|null

Quem aprovou, só em cards de SQL livre.

cards[].approved_atstring|null

Quando foi aprovado.

cards[].created_byuuid|null

Quem criou.

cards[].created_atstring

Criação, RFC 3339.

cards[].updated_atstring

Última alteração, RFC 3339.

Erros (consultar)

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"}`
404	A aba não existe, não é sua ou não está visível para você. A API responde 404 em vez de 403 para não revelar que o id existe.	`{"error":"dashboard not found"}`
500	Falha inesperada no servidor.	`{"error":"failed to ..."}`