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

Abas

Lista, cria, consulta, edita e apaga as abas de dashboard do seller.

Uma aba agrupa cards. Estas cinco rotas cuidam do ciclo de vida da aba em si; os cards têm as próprias rotas.

Listar abas

Devolve as abas que o seller pode ver: as próprias e as abas do administrador publicadas para sellers (somente leitura, panel: A). Na primeira chamada de um seller sem abas, cria e devolve a aba de fábrica.

GET/api/v1/vendor/dashboardsSeller

Listar abas

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" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Abas
json
{
  "dashboards": [
    {
      "id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8",
      "slug": "fabrica",
      "name": "Dashboard",
      "panel": "V",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "visibility": "P",
      "is_system": true,
      "is_default": true,
      "position": 0,
      "icon": "atividade",
      "color": "#0044FF",
      "default_period": {
        "mode": "preset",
        "preset": "last30"
      },
      "created_at": "2026-10-11T21:04:17.245533Z",
      "updated_at": "2026-10-11T21:04:17.245533Z",
      "version": 1791752657246,
      "is_owner": true,
      "permission": "W",
      "kind": "normal"
    }
  ]
}

Campos da resposta

dashboardsobject[]

As abas, ordenadas por position e depois por nome.

iduuid
Id da aba (UUID).
slugstring
Identificador textual estável. A aba de fábrica do seller usa fabrica.
namestring
Nome exibido na aba.
panelstring
VA
V para abas do painel do seller, A para uma aba do administrador publicada para sellers.
vendor_iduuid
Seller dono da aba. Ausente em abas do administrador.
owner_user_iduuid
Usuário que criou a aba. Ausente na aba de fábrica, que pertence à conta do seller e não a uma pessoa.
visibilitystring
PSG
Visibilidade registrada na aba. P privada (padrão), S compartilhada, G global da loja.
is_systemboolean
true na aba de fábrica: não pode ser renomeada nem apagada.
is_defaultboolean
true na aba que abre primeiro.
positioninteger
Ordem das abas, do menor para o maior.
iconstring
Nome do ícone.
colorstring
Cor de destaque, por exemplo #0044FF.
default_periodobject
Período usado pelos cards que herdam o da aba (veja Formato do card).
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
versioninteger
Marca de versão do layout (milissegundos Unix de updated_at). Envie-a em Salvar layout para detectar edição concorrente.
is_ownerboolean
Só nas leituras de lista e de detalhe. true se quem chama é dono da aba.
permissionstring
WR
Só nas leituras de lista e de detalhe. W pode editar, R somente leitura (aba publicada por outra pessoa).
kindstring
normalvi_insights
Só na lista. normal ou vi_insights (a aba de insights).

Erros

StatusQuandoCorpo de exemplo
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"}
Sem paginação

A lista vem inteira: um seller tem poucas abas.

Criar aba

Cria uma aba vazia, privada e dona do seller. Ela nasce sem cards: use Cards ou Layout e modelos em seguida.

POST/api/v1/vendor/dashboardsSeller

Criar aba

Cabeçalhos

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

Corpo da requisição

namestringobrigatório
Nome da aba. Obrigatório.
iconstring
Nome do ícone.
colorstring
Cor de destaque.
visibilitystring
PSG
P privada, S compartilhada, G global. Outro valor causa erro 500.
positioninteger
Posição entre as abas. 0 coloca a aba na frente; omitido, não muda.
default_periodobject
Período padrão da aba, no formato de query.period (veja Formato do card).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vendas da semana", "icon": "atividade", "color": "#1baf7a"}'

Resposta

201Aba criada
json
{
  "id": "5d3c2f6a-1b0e-4b6a-9d55-0c7a4c1f2e11",
  "slug": "d8c4a4a0-0f6b-4a11-9a52-3f0f3c0c9a77",
  "name": "Vendas da semana",
  "panel": "V",
  "owner_user_id": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "visibility": "P",
  "is_system": false,
  "is_default": false,
  "position": 0,
  "icon": "atividade",
  "color": "#1baf7a",
  "default_period": {
    "mode": "preset",
    "preset": "last30"
  },
  "created_at": "2026-10-11T21:30:00Z",
  "updated_at": "2026-10-11T21:30:00Z",
  "version": 1791754200000,
  "is_owner": false
}

Campos da resposta

(campos / fields)object
Os mesmos de Listar abas. Nas respostas de escrita is_owner vem sempre false e permission não vem: releia a aba para obter os valores reais.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid request body"}
422name ausente ou vazio.{"error":"name is required"}
500visibility fora de P, S, G, ou falha ao gravar.{"error":"failed to create dashboard","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"}

Consultar aba com seus cards

Devolve a aba e as definições dos cards (spec e layout). Não executa nada: para os números, use Executar dados.

GET/api/v1/vendor/dashboards/{id}Seller

Consultar aba com seus cards

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aba e cards
json
{
  "dashboard": {
    "id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8",
    "slug": "fabrica",
    "name": "Dashboard",
    "panel": "V",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "visibility": "P",
    "is_system": true,
    "is_default": true,
    "position": 0,
    "icon": "atividade",
    "color": "#0044FF",
    "default_period": {
      "mode": "preset",
      "preset": "last30"
    },
    "created_at": "2026-10-11T21:04:17.245533Z",
    "updated_at": "2026-10-11T21:04:17.245533Z",
    "version": 1791752657246,
    "is_owner": true,
    "permission": "W",
    "kind": "normal"
  },
  "cards": [
    {
      "id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
      "dashboard_id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8",
      "spec": {
        "spec_version": 1,
        "kind": "query",
        "title": "Receita do Mês",
        "viz": {
          "type": "kpi",
          "snippet_id": "seller-kpi-revenue-month",
          "icon": "cifrao",
          "accent": "#0044FF",
          "number_format": {
            "style": "currency_cents"
          }
        },
        "query": {
          "entity": "orders",
          "period": {
            "mode": "preset",
            "preset": "thisMonth"
          },
          "metrics": [
            {
              "id": "receita",
              "kind": "catalog",
              "ref": "orders.revenue"
            }
          ]
        }
      },
      "spec_version": 1,
      "kind": "Q",
      "title": "Receita do Mês",
      "grid_row": 0,
      "grid_col": 0,
      "width": 1,
      "height": 1,
      "order": 0,
      "status": "A",
      "source": "T",
      "template_slug": "fab-v-kpi-revenue-month",
      "created_at": "2026-10-11T21:04:20.327443Z",
      "updated_at": "2026-10-11T21:04:20.327443Z"
    }
  ]
}

Campos da resposta

dashboardobject
A aba, com os campos de Listar abas (sem kind).
cardsobject[]

Os cards da aba.

iduuid
Id do card (UUID).
dashboard_iduuid
Aba a que o card pertence.
specobject
A definição do card (veja Formato do card).
spec_versioninteger
Versão do formato da spec. Hoje só existe 1.
kindstring
QSCVT
Tipo do card: Q consulta, S SQL, C componente, V serviço, T texto.
titlestring
Título (copiado de spec.title).
grid_rowinteger
Linha na grade.
grid_colinteger
Coluna na grade.
widthinteger
Largura em colunas, de 1 a 3.
heightinteger
Altura em linhas, de 1 a 3.
orderinteger
Ordem de exibição.
statusstring
ADX
A ativo, D rascunho, X degradado (card SQL desligado após falhas repetidas). Só cards ativos são executados.
sourcestring
MIT
Origem: M manual, I criado por insight, T criado de um modelo.
template_slugstring
Modelo de origem, quando source é T.
created_byuuid
Usuário que criou.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.

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

Editar aba

Altera nome, ícone, cor, visibilidade, período padrão ou posição. É uma edição parcial: o que você não enviar (ou enviar vazio) continua como está.

PUT/api/v1/vendor/dashboards/{id}Seller

Editar 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

namestring
Nome da aba.
iconstring
Nome do ícone.
colorstring
Cor de destaque.
visibilitystring
PSG
P privada, S compartilhada, G global. Outro valor causa erro 500.
positioninteger
Posição entre as abas. 0 coloca a aba na frente; omitido, não muda.
default_periodobject
Período padrão da aba, no formato de query.period (veja Formato do card).

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"position": 0, "color": "#eb6834"}'

Resposta

200Aba atualizada
json
{
  "id": "931b3fc7-e703-4cac-bcbc-5c79690f02a8",
  "slug": "fabrica",
  "name": "Dashboard",
  "panel": "V",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "visibility": "P",
  "is_system": true,
  "is_default": true,
  "position": 0,
  "icon": "atividade",
  "color": "#eb6834",
  "default_period": {
    "mode": "preset",
    "preset": "last30"
  },
  "created_at": "2026-10-11T21:04:17.245533Z",
  "updated_at": "2026-10-11T21:04:17.245533Z",
  "version": 1791752657246,
  "is_owner": true,
  "permission": "W",
  "kind": "normal"
}

Campos da resposta

(campos / fields)object
A aba atualizada, como em Criar aba.

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"}
400Corpo que não é JSON.{"error":"invalid request body"}
409Tentativa de renomear a aba de fábrica.{"error":"system_dashboard_immutable","detail":"dashboards: is_system dashboard cannot be renamed or deleted"}
500Falha ao gravar.{"error":"failed to update dashboard"}
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"}
A aba de fábrica

Só o nome da aba de fábrica é travado. Ícone, cor, posição e período padrão podem ser alterados. A mensagem de detalhe do 409 vem em inglês.

Apagar aba

Apaga a aba e seus cards da visão do seller (remoção lógica). A aba de fábrica não pode ser apagada.

DELETE/api/v1/vendor/dashboards/{id}Seller

Apagar aba

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/dashboards/5d3c2f6a-1b0e-4b6a-9d55-0c7a4c1f2e11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagada
json
{
  "message": "dashboard deleted"
}

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"}
409A aba é a de fábrica.{"error":"system_dashboard_immutable"}
500Falha ao apagar.{"error":"failed to delete dashboard"}
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"}
Sem desfazer

Não há rota para recuperar uma aba apagada. Se o seller quer manter os cards, duplique antes.

Veja também

  • Ações sobre a aba
  • Cards
  • Executar dados
Anterior
Formato do card
Próxima
Ações sobre a aba
Nesta página
  • Listar abas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar aba
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar aba com seus cards
  • Exemplo de requisição
  • Resposta
  • Erros
  • Editar aba
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar aba
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também