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

Cards: ações

Duplica um card, cria um card a partir de modelo, salva um card como modelo pessoal e carimba a aprovação de um card de SQL.

Ações que partem de um card ou de um modelo, sem precisar escrever uma especificação. Todas exigem manage_dashboards e acesso de escrita à aba. Para a lista de modelos disponíveis, veja Catálogo e modelos.

Duplicar card

POST/api/v1/admin/dashboards/{id}/cards/{cardId}/duplicateAdmin

Duplicar um card

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).
cardIduuidobrigatório
Id do card (UUID).

Exemplo de requisição (duplicar)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/8da0f9c1-b05b-4809-b07d-0b36573489e7/cards/dd3470e6-dc16-4b41-9393-23797b50d7ba/duplicate" \
  -H "Authorization: Bearer $TOKEN"

Resposta (duplicar)

201Card copiado
json
{
  "id": "1fe54f18-d4cb-453f-9db5-965f6fc9db01",
  "dashboard_id": "8da0f9c1-b05b-4809-b07d-0b36573489e7",
  "spec": {
    "spec_version": 1,
    "kind": "query",
    "title": "Receita",
    "viz": { "type": "kpi", "snippet_id": "receita-semana", "number_format": { "style": "currency_cents" } },
    "query": {
      "entity": "orders",
      "period": { "mode": "inherit" },
      "metrics": [ { "id": "receita", "kind": "catalog", "ref": "orders.revenue", "status_scope": { "mode": "store_default", "include": ["Paid", "shipped", "delivered"] } } ]
    }
  },
  "spec_version": 1,
  "kind": "Q",
  "title": "Receita",
  "grid_row": 0,
  "grid_col": 0,
  "width": 1,
  "height": 1,
  "order": 0,
  "status": "A",
  "source": "M",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:10:41.552Z",
  "updated_at": "2026-10-11T21:10:41.552Z"
}

Campos da resposta

(objeto)object
O novo card, na mesma aba, com a mesma especificação.

Erros (duplicar)

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"}
404O card não existe ou a aba dele não é sua.{"error":"card not found"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Criar a partir de modelo

POST/api/v1/admin/dashboards/{id}/cards/from-templateAdmin

Criar um card a partir de um modelo

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).

Corpo da requisição

template_slugstringobrigatório
slug de um modelo de Catálogo e modelos.
grid_rowintegerpadrão: 0
Linha da grade.
grid_colintegerpadrão: 0
Coluna, 0 a 2.
orderintegerpadrão: 0
Ordem de exibição. Sem isso, todo card novo fica na ordem 0.

Exemplo de requisição (modelo)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/8da0f9c1-b05b-4809-b07d-0b36573489e7/cards/from-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_slug": "ven-receita-diaria", "grid_row": 1, "grid_col": 0, "order": 2}'

Resposta (modelo)

201Card criado
json
{
  "id": "dd3470e6-dc16-4b41-9393-23797b50d7ba",
  "dashboard_id": "8da0f9c1-b05b-4809-b07d-0b36573489e7",
  "spec": {
    "spec_version": 1,
    "kind": "query",
    "title": "Receita",
    "viz": { "type": "kpi", "snippet_id": "receita-semana", "number_format": { "style": "currency_cents" } },
    "query": {
      "entity": "orders",
      "period": { "mode": "inherit" },
      "metrics": [ { "id": "receita", "kind": "catalog", "ref": "orders.revenue", "status_scope": { "mode": "store_default", "include": ["Paid", "shipped", "delivered"] } } ]
    }
  },
  "spec_version": 1,
  "kind": "Q",
  "title": "Receita",
  "grid_row": 0,
  "grid_col": 0,
  "width": 1,
  "height": 1,
  "order": 0,
  "status": "A",
  "source": "M",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:10:41.552Z",
  "updated_at": "2026-10-11T21:10:41.552Z"
}

Campos da resposta

(objeto)object
O card criado. Largura e altura vêm do modelo (default_width, default_height); source é T e template_slug guarda o modelo.

Erros (modelo)

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"}
422Modelo inexistente, ou que não passa mais na validação desta versão.{"error":"failed to create card from template","detail":"dashboards: not found"}

Salvar como modelo

POST/api/v1/admin/dashboards/{id}/cards/{cardId}/save-as-templateAdmin

Salvar um card como modelo pessoal

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).
cardIduuidobrigatório
Id do card (UUID).

Corpo da requisição

name_ptstringobrigatório
Nome do modelo. Obrigatório.
categorystringpadrão: geral
Categoria. Vazio vira geral.

Exemplo de requisição (salvar modelo)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/8da0f9c1-b05b-4809-b07d-0b36573489e7/cards/dd3470e6-dc16-4b41-9393-23797b50d7ba/save-as-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name_pt": "Receita da semana", "category": "geral"}'

Resposta (salvar modelo)

201Modelo salvo
json
{
  "slug": "personal-6b1c0d6e-4e5a-4a2f-9a55-3f0f2f5c9a10",
  "category": "geral",
  "name_pt": "Receita da semana",
  "name_en": "Receita da semana",
  "description_pt": "",
  "spec": { "spec_version": 1, "kind": "query", "title": "Receita" },
  "icon": "",
  "panel": "A",
  "default_width": 1,
  "default_height": 1,
  "is_builtin": false,
  "has_real_data": true,
  "position": 0,
  "is_mine": true
}

Campos da resposta

(objeto)object
O modelo criado, com os campos de Catálogo e modelos. O slug começa com personal-; name_en repete name_pt. Só quem salvou o vê na biblioteca. Não há rota para apagá-lo.

Erros (salvar modelo)

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\""}
404O card não existe ou a aba dele não é sua.{"error":"card not found"}
422name_pt vazio ou falha ao salvar.{"error":"failed to save card as template","detail":"name_pt is required"}

Aprovar card de SQL

POST/api/v1/admin/dashboards/{id}/cards/{cardId}/approveAdmin

Carimbar a aprovação de um card de SQL

Parâmetros de caminho

iduuidobrigatório
Id da aba (UUID).
cardIduuidobrigatório
Id do card (UUID).

Exemplo de requisição (aprovar)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/8da0f9c1-b05b-4809-b07d-0b36573489e7/cards/dd3470e6-dc16-4b41-9393-23797b50d7ba/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta (aprovar)

200Card aprovado
json
{
  "id": "dd3470e6-dc16-4b41-9393-23797b50d7ba",
  "dashboard_id": "8da0f9c1-b05b-4809-b07d-0b36573489e7",
  "spec": {
    "spec_version": 1,
    "kind": "query",
    "title": "Receita",
    "viz": { "type": "kpi", "snippet_id": "receita-semana", "number_format": { "style": "currency_cents" } },
    "query": {
      "entity": "orders",
      "period": { "mode": "inherit" },
      "metrics": [ { "id": "receita", "kind": "catalog", "ref": "orders.revenue", "status_scope": { "mode": "store_default", "include": ["Paid", "shipped", "delivered"] } } ]
    }
  },
  "spec_version": 1,
  "kind": "S",
  "title": "Receita",
  "grid_row": 0,
  "grid_col": 0,
  "width": 1,
  "height": 1,
  "order": 0,
  "status": "A",
  "source": "M",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:10:41.552Z",
  "updated_at": "2026-10-11T21:10:41.552Z"
}

Campos da resposta

(objeto)object
O card, com approved_by_user_id e approved_at preenchidos.

Erros (aprovar)

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"}
403Falta o privilégio manage_reports.{"error":"manage_reports required to approve a sql card"}
404O card não existe ou a aba dele não é sua.{"error":"card not found"}
400O card não é de SQL livre.{"error":"card_not_sql","detail":"dashboards: card is not kind=\"sql\""}
500Falha inesperada no servidor.{"error":"failed to ..."}
Aprovar só vale para cards de SQL

Cards kind: sql são escritos à mão, exigem manage_reports e passam por uma verificação automática que recusa qualquer escrita ou comando administrativo. Eles já nascem ativos; approve apenas carimba de novo quem aprovou. Em um card comum a rota responde 400 card_not_sql.

Veja também

  • Criar e alterar cards
  • Catálogo e modelos
  • Especificação do card
Anterior
Cards: criar, alterar, apagar, layout
Próxima
Preview, execução e detalhe
Nesta página
  • Duplicar card
  • Exemplo de requisição (duplicar)
  • Resposta (duplicar)
  • Erros (duplicar)
  • Criar a partir de modelo
  • Exemplo de requisição (modelo)
  • Resposta (modelo)
  • Erros (modelo)
  • Salvar como modelo
  • Exemplo de requisição (salvar modelo)
  • Resposta (salvar modelo)
  • Erros (salvar modelo)
  • Aprovar card de SQL
  • Exemplo de requisição (aprovar)
  • Resposta (aprovar)
  • Erros (aprovar)
  • Veja também