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

Abas: criar, alterar, apagar

Cria uma aba nova, altera nome, cor, visibilidade e posição, ou apaga uma aba.

Estas rotas exigem o privilégio manage_dashboards (além de view_reports). Quem cria é o dono da aba. Alterar e apagar exigem ser o dono ou ter recebido o compartilhamento com permissão de escrita (W); a aba de fábrica é exceção e pode ser mexida por quem tem manage_dashboards, menos renomear e apagar.

Criar aba

POST/api/v1/admin/dashboardsAdmin

Criar uma aba

Corpo da requisição

namestringobrigatório
Nome da aba. Obrigatório ao criar; ao alterar, vazio mantém o nome atual.
iconstring
Nome do ícone.
colorstring
Cor, normalmente #RRGGBB.
visibilitystring
PSG
P privada (padrão ao criar), S compartilhada, G global. Outro valor é recusado pelo banco e volta como 500.
positioninteger
Posição na barra de abas. 0 é a primeira. Se omitido ao alterar, a posição não muda.
default_periodobject
Período padrão da aba (mode, preset...). Se omitido ao criar, vale {"mode":"preset","preset":"last30"}. Veja o objeto period em Especificação do card.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vendas da semana", "icon": "chart", "color": "#0044FF", "visibility": "P", "default_period": {"mode": "preset", "preset": "last7"}}'

Resposta (criar)

201Aba criada
json
{
  "id": "8da0f9c1-b05b-4809-b07d-0b36573489e7",
  "slug": "94df13c8-4cef-4194-ac6c-ad456986d289",
  "name": "Vendas da semana",
  "panel": "A",
  "owner_user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "visibility": "P",
  "is_system": false,
  "is_default": false,
  "position": 0,
  "icon": "chart",
  "color": "#0044FF",
  "default_period": { "mode": "preset", "preset": "last7" },
  "created_at": "2026-10-11T21:10:37.137115Z",
  "updated_at": "2026-10-11T21:10:37.137115Z",
  "version": 1791753037137,
  "is_owner": false,
  "kind": "normal"
}

Campos da resposta

(objeto)object
A aba criada, com os campos de Listar abas. is_owner vem false e permission ausente nesta resposta.

Erros (criar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
422name vazio.{"error":"name is required"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Alterar aba

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

Alterar uma aba

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Corpo da requisição

namestring
Nome da aba. Obrigatório ao criar; ao alterar, vazio mantém o nome atual.
iconstring
Nome do ícone.
colorstring
Cor, normalmente #RRGGBB.
visibilitystring
PSG
P privada (padrão ao criar), S compartilhada, G global. Outro valor é recusado pelo banco e volta como 500.
positioninteger
Posição na barra de abas. 0 é a primeira. Se omitido ao alterar, a posição não muda.
default_periodobject
Período padrão da aba (mode, preset...). Se omitido ao criar, vale {"mode":"preset","preset":"last30"}. Veja o objeto period em Especificação do card.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/dashboards/8da0f9c1-b05b-4809-b07d-0b36573489e7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vendas da semana (v2)", "position": 1}'

Resposta (alterar)

200Aba alterada
json
{
  "id": "8da0f9c1-b05b-4809-b07d-0b36573489e7",
  "slug": "94df13c8-4cef-4194-ac6c-ad456986d289",
  "name": "Vendas da semana (v2)",
  "panel": "A",
  "owner_user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "visibility": "P",
  "is_system": false,
  "is_default": false,
  "position": 0,
  "icon": "chart",
  "color": "#0044FF",
  "default_period": { "mode": "preset", "preset": "last7" },
  "created_at": "2026-10-11T21:10:37.137115Z",
  "updated_at": "2026-10-11T21:10:37.137115Z",
  "version": 1791753037137,
  "is_owner": false,
  "kind": "normal"
}

Campos da resposta

(objeto)object
A aba alterada. Só os campos enviados mudam.

Erros (alterar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
404A 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"}
409Tentativa de renomear a aba de fábrica.{"error":"system_dashboard_immutable","detail":"dashboards: is_system dashboard cannot be renamed or deleted \u2014 duplicate it instead"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Apagar aba

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

Apagar uma aba

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Exemplo de requisição (apagar)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/dashboards/8da0f9c1-b05b-4809-b07d-0b36573489e7" \
  -H "Authorization: Bearer $TOKEN"

Resposta (apagar)

200Aba apagada
json
{
  "message": "dashboard deleted"
}

Campos da resposta

messagestring
Texto fixo de confirmação, em inglês.

Erros (apagar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
404A 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"}
409Tentativa de apagar a aba de fábrica.{"error":"system_dashboard_immutable","detail":"dashboards: is_system dashboard cannot be renamed or deleted \u2014 duplicate it instead"}
500Falha inesperada no servidor.{"error":"failed to ..."}
Apagar é lógico, mas não há desfazer

A aba some da lista e dos acessos, e a API não oferece rota para recuperá-la. Os cards dela deixam de ser acessíveis. Se há dúvida, duplique antes.

`visibility` não é validada

visibility não é validada pela API: um valor fora de P, S e G chega ao banco e volta como erro 500, não 422. Envie só esses três.

Veja também

  • Listar e consultar abas
  • Ações de aba
  • Compartilhar
Anterior
Abas: listar e consultar
Próxima
Abas: duplicar e restaurar
Nesta página
  • Criar aba
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Alterar aba
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Apagar aba
  • Exemplo de requisição (apagar)
  • Resposta (apagar)
  • Erros (apagar)
  • Veja também