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

Layout e modelos

Salva a posição dos cards com controle de versão e usa a biblioteca de modelos de card.

O layout (posição e tamanho dos cards) é salvo em lote, com um número de versão que protege contra duas pessoas editando a mesma aba. A biblioteca de modelos oferece cards prontos e guarda os que o próprio seller salvar.

Salvar layout

Atualiza posição e tamanho de vários cards em uma transação. Se a aba mudou desde a sua última leitura, a operação é recusada com 409 e você recebe o layout atual.

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

Salvar layout

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

versioninteger
version da aba na sua última leitura. Se não bater com o atual, a resposta é 409. 0 ou omitido pula a verificação.
itemsobject[]obrigatório

Um item por card.

items[].card_iduuidobrigatório
Card (UUID). Precisa pertencer à aba.
items[].grid_rowinteger
Linha.
items[].grid_colinteger
Coluna.
items[].widthinteger
Largura de 1 a 3.
items[].heightinteger
Altura de 1 a 3.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/layout" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1791752657246, "items": [{"card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57", "grid_row": 0, "grid_col": 0, "width": 2, "height": 1}]}'

Resposta

200Layout salvo
json
{
  "version": 1791752700123,
  "message": "layout updated"
}
409Conflito de versão
json
{
  "version": 1791752690000,
  "items": [
    {
      "card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
      "grid_row": 0,
      "grid_col": 0,
      "width": 1,
      "height": 1,
      "order": 0
    }
  ]
}

Campos da resposta

versioninteger
No 200, a nova versão; guarde-a para o próximo salvamento. No 409, a versão atual do servidor.
itemsobject[]
Só no 409: o layout atual (card_id, grid_row, grid_col, width, height, order).
messagestring
Só no 200.

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"}
409version diferente da atual. Adote o items devolvido ou reenvie com a nova version.{"version":1791752690000,"items":[...]}
500Algum card_id não pertence à aba, ou falha ao gravar. Nenhuma mudança é aplicada.{"error":"failed to update layout","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"}
Fluxo recomendado

Leia a aba, guarde version, deixe o usuário arrastar os cards e salve. A cada 200, troque a versão guardada pela nova. No 409, pergunte se mantém a edição local ou recarrega.

Listar modelos

Devolve a biblioteca de modelos de card visíveis ao seller: os da plataforma e os que ele mesmo salvou. Os cards de fábrica não entram aqui.

GET/api/v1/vendor/dashboards/templatesSeller

Listar modelos

Cabeçalhos

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

Parâmetros de consulta

categorystring
Filtra por categoria. Omitido: todas.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/dashboards/templates?category=sales" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Modelos
json
{
  "templates": [
    {
      "slug": "meu-top-produtos",
      "category": "geral",
      "name_pt": "Top produtos",
      "name_en": "",
      "description_pt": "",
      "spec": {
        "spec_version": 1,
        "kind": "query",
        "title": "Top produtos",
        "viz": {
          "type": "bar",
          "snippet_id": "top-produtos"
        },
        "query": {
          "entity": "order_items"
        }
      },
      "icon": "",
      "panel": "V",
      "default_width": 1,
      "default_height": 1,
      "is_builtin": false,
      "has_real_data": true,
      "position": 0,
      "is_mine": true
    }
  ]
}

Campos da resposta

templatesobject[]|null

Os modelos. Pode vir null (e não []) quando não há nenhum.

templates[].slugstring
Identificador do modelo, usado em from-template.
templates[].categorystring
Categoria.
templates[].name_ptstring
Nome em português.
templates[].name_enstring
Nome em inglês.
templates[].description_ptstring
Descrição em português.
templates[].specobject
A spec do card.
templates[].iconstring
Ícone.
templates[].panelstring
Painel de destino: V seller, A administrador, B ambos.
templates[].default_widthinteger
Largura sugerida.
templates[].default_heightinteger
Altura sugerida.
templates[].is_builtinboolean
true se é da plataforma.
templates[].has_real_databoolean
false quando a loja ainda não tem dados para o modelo mostrar algo útil.
templates[].positioninteger
Ordem dentro da categoria.
templates[].is_mineboolean
true se foi salvo pelo próprio seller.

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"}
500Falha ao listar.{"error":"failed to list templates"}
Lista vazia é normal

Uma conta sem modelos recebe null. Trate a ausência de modelos como normal.

Criar card de um modelo

Instancia um modelo como card da aba, usando o tamanho sugerido pelo modelo. A spec do modelo é validada como qualquer outra.

POST/api/v1/vendor/dashboards/{id}/cards/from-templateSeller

Criar card de um modelo

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

template_slugstringobrigatório
slug do modelo.
grid_rowinteger
Linha. Omitido vale 0.
grid_colinteger
Coluna. Omitido vale 0.
orderinteger
Ordem de exibição. Sem ela, todos os cards adicionados ficam com a mesma ordem 0.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards/from-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_slug": "meu-top-produtos", "grid_row": 1, "grid_col": 0, "order": 10}'

Resposta

201Card criado
json
{
  "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": "Top produtos",
  "grid_row": 1,
  "grid_col": 0,
  "width": 1,
  "height": 1,
  "order": 10,
  "status": "A",
  "source": "T",
  "template_slug": "meu-top-produtos",
  "created_at": "2026-10-11T21:04:20.327443Z",
  "updated_at": "2026-10-11T21:04:20.327443Z"
}

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"}
422Modelo inexistente ou que não compila.{"error":"failed to create card from template","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"}

Salvar card como modelo

Guarda a spec do card como modelo pessoal do seller, para reaproveitar em outras abas.

POST/api/v1/vendor/dashboards/{id}/cards/{cardId}/save-as-templateSeller

Salvar card como modelo

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).
cardIduuidobrigatório
Id do card (UUID).

Corpo da requisição

name_ptstringobrigatório
Nome do modelo em português.
categorystringpadrão: geral
Categoria do modelo.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57/save-as-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name_pt": "Receita do mês", "category": "vendas"}'

Resposta

201Modelo criado
json
{
  "slug": "receita-do-mes-1f3a",
  "category": "vendas",
  "name_pt": "Receita do mês",
  "name_en": "",
  "description_pt": "",
  "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"
        }
      ]
    }
  },
  "icon": "cifrao",
  "panel": "V",
  "default_width": 1,
  "default_height": 1,
  "is_builtin": false,
  "has_real_data": true,
  "position": 0,
  "is_mine": true
}

Erros

StatusQuandoCorpo de exemplo
404A aba ou o card não existe ou não é do seller. Os dois casos dão 404.{"error":"card not found"}
400Corpo que não é JSON.{"error":"invalid request body"}
422name_pt vazio ou falha ao salvar.{"error":"failed to save card as template","detail":"name_pt is required"}
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

  • Cards
  • Abas
Anterior
Cards
Próxima
Executar dados
Nesta página
  • Salvar layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar modelos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar card de um modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Salvar card como modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também