API atual/Referência completa/Dashboards do seller

Cards

Cria, edita, apaga e duplica cards de uma aba e aprova cards SQL.

Um card é a spec mais um lugar na grade. Toda gravação revalida a spec contra o catálogo: um card que não compila não é salvo. Para posicionar vários cards de uma vez, use Salvar layout.

Criar card

Adiciona um card à aba. Métricas de status de pedido sem status_scope recebem o da regra atual da loja.

POST/api/v1/vendor/dashboards/{id}/cardsSeller

Criar card

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

specobjectobrigatório

A definição do card. Veja Formato do card.

grid_rowinteger

Linha na grade. Omitido vale 0.

grid_colinteger

Coluna na grade. Omitido vale 0.

widthinteger

Largura, de 1 a 3. Fora disso é ajustada para 1 ou 3; omitido vale 1.

heightinteger

Altura, de 1 a 3. Mesma regra da largura.

orderinteger

Ordem de exibição. Omitido vale 0.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"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"}]}}, "grid_row": 0, "grid_col": 0, "width": 1, "height": 1, "order": 0}'

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

(campos / fields)object

Os campos do card estão em Consultar aba. A spec guardada pode vir com status_scope preenchido.

Erros

Status	Quando	Corpo de exemplo
404	A 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"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
403	Card `sql` sem o privilégio `manage_reports`.	`{"error":"manage_reports required for kind=\"sql\" cards"}`
422	Spec inválida, ou card `sql` sem `sql.vendor_scope.mode` igual a `guc`.	`{"error":"invalid card spec","detail":"unknown_field: ..."}`
500	A spec era válida mas a gravação falhou.	`{"error":"failed to persist card","detail":"..."}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Editar card

Troca a spec e o layout do card. A spec nova passa pela mesma validação da criação.

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

Editar card

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

specobjectobrigatório

A definição do card. Veja Formato do card.

grid_rowinteger

Linha na grade. Omitido vale 0.

grid_colinteger

Coluna na grade. Omitido vale 0.

widthinteger

Largura, de 1 a 3. Fora disso é ajustada para 1 ou 3; omitido vale 1.

heightinteger

Altura, de 1 a 3. Mesma regra da largura.

orderinteger

Ordem de exibição. Omitido vale 0.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"spec_version": 1, "kind": "query", "title": "Receita deste 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"}]}}, "grid_row": 0, "grid_col": 0, "width": 2, "height": 1, "order": 0}'

Resposta

200Card atualizado

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": "Receita deste mês",
  "grid_row": 0,
  "grid_col": 0,
  "width": 2,
  "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"
}

Erros

Status	Quando	Corpo de exemplo
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
403	Card `sql` sem o privilégio `manage_reports`.	`{"error":"manage_reports required for kind=\"sql\" cards"}`
422	Spec inválida, ou card `sql` sem `sql.vendor_scope.mode` igual a `guc`.	`{"error":"invalid card spec","detail":"unknown_field: ..."}`
500	A spec era válida mas a gravação falhou.	`{"error":"failed to persist card","detail":"..."}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Apagar card

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

Apagar card

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).

cardIduuidobrigatório

Id do card (UUID).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado

json

{
  "message": "card deleted"
}

Erros

Status	Quando	Corpo de exemplo
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
500	Falha ao apagar.	`{"error":"failed to delete card"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Duplicar card

Cria uma cópia do card na mesma aba.

POST/api/v1/vendor/dashboards/{id}/cards/{cardId}/duplicateSeller

Duplicar card

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).

cardIduuidobrigatório

Id do card (UUID).

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

Resposta

201Cópia criada

json

{
  "id": "0c9d7a7e-6f0c-4c0e-92a3-2b6d1b6a9a77",
  "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": 1,
  "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"
}

Erros

Status	Quando	Corpo de exemplo
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
500	Falha ao copiar.	`{"error":"failed to duplicate card"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Aprovar card SQL

Recarimba a aprovação de um card sql, registrando quem aprovou e o hash do SQL. Exige o privilégio manage_reports. Em cards de consulta (query) responde 400.

POST/api/v1/vendor/dashboards/{id}/cards/{cardId}/approveSeller

Aprovar card SQL

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).

cardIduuidobrigatório

Id do card (UUID).

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

Resposta

200Card aprovado

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": "S",
  "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",
  "approved_by_user_id": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "approved_at": "2026-10-11T21:40:00Z"
}

Erros

Status	Quando	Corpo de exemplo
400	O card não é do tipo `sql`.	`{"error":"card_not_sql"}`
403	Sem o privilégio `manage_reports`.	`{"error":"manage_reports required to approve a sql card"}`
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O 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

API atual/Referência completa/Dashboards do seller

Cards

Cria, edita, apaga e duplica cards de uma aba e aprova cards SQL.

Um card é a spec mais um lugar na grade. Toda gravação revalida a spec contra o catálogo: um card que não compila não é salvo. Para posicionar vários cards de uma vez, use Salvar layout.

Criar card

Adiciona um card à aba. Métricas de status de pedido sem status_scope recebem o da regra atual da loja.

POST/api/v1/vendor/dashboards/{id}/cardsSeller

Criar card

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

specobjectobrigatório

A definição do card. Veja Formato do card.

grid_rowinteger

Linha na grade. Omitido vale 0.

grid_colinteger

Coluna na grade. Omitido vale 0.

widthinteger

Largura, de 1 a 3. Fora disso é ajustada para 1 ou 3; omitido vale 1.

heightinteger

Altura, de 1 a 3. Mesma regra da largura.

orderinteger

Ordem de exibição. Omitido vale 0.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"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"}]}}, "grid_row": 0, "grid_col": 0, "width": 1, "height": 1, "order": 0}'

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

(campos / fields)object

Os campos do card estão em Consultar aba. A spec guardada pode vir com status_scope preenchido.

Erros

Status	Quando	Corpo de exemplo
404	A 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"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
403	Card `sql` sem o privilégio `manage_reports`.	`{"error":"manage_reports required for kind=\"sql\" cards"}`
422	Spec inválida, ou card `sql` sem `sql.vendor_scope.mode` igual a `guc`.	`{"error":"invalid card spec","detail":"unknown_field: ..."}`
500	A spec era válida mas a gravação falhou.	`{"error":"failed to persist card","detail":"..."}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Editar card

Troca a spec e o layout do card. A spec nova passa pela mesma validação da criação.

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

Editar card

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

specobjectobrigatório

A definição do card. Veja Formato do card.

grid_rowinteger

Linha na grade. Omitido vale 0.

grid_colinteger

Coluna na grade. Omitido vale 0.

widthinteger

Largura, de 1 a 3. Fora disso é ajustada para 1 ou 3; omitido vale 1.

heightinteger

Altura, de 1 a 3. Mesma regra da largura.

orderinteger

Ordem de exibição. Omitido vale 0.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"spec_version": 1, "kind": "query", "title": "Receita deste 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"}]}}, "grid_row": 0, "grid_col": 0, "width": 2, "height": 1, "order": 0}'

Resposta

200Card atualizado

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": "Receita deste mês",
  "grid_row": 0,
  "grid_col": 0,
  "width": 2,
  "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"
}

Erros

Status	Quando	Corpo de exemplo
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
403	Card `sql` sem o privilégio `manage_reports`.	`{"error":"manage_reports required for kind=\"sql\" cards"}`
422	Spec inválida, ou card `sql` sem `sql.vendor_scope.mode` igual a `guc`.	`{"error":"invalid card spec","detail":"unknown_field: ..."}`
500	A spec era válida mas a gravação falhou.	`{"error":"failed to persist card","detail":"..."}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Apagar card

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

Apagar card

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).

cardIduuidobrigatório

Id do card (UUID).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/dashboards/931b3fc7-e703-4cac-bcbc-5c79690f02a8/cards/94c6b3ff-de9c-4552-8a12-e199e8427f57" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado

json

{
  "message": "card deleted"
}

Erros

Status	Quando	Corpo de exemplo
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
500	Falha ao apagar.	`{"error":"failed to delete card"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Duplicar card

Cria uma cópia do card na mesma aba.

POST/api/v1/vendor/dashboards/{id}/cards/{cardId}/duplicateSeller

Duplicar card

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).

cardIduuidobrigatório

Id do card (UUID).

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

Resposta

201Cópia criada

json

{
  "id": "0c9d7a7e-6f0c-4c0e-92a3-2b6d1b6a9a77",
  "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": 1,
  "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"
}

Erros

Status	Quando	Corpo de exemplo
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
500	Falha ao copiar.	`{"error":"failed to duplicate card"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Aprovar card SQL

Recarimba a aprovação de um card sql, registrando quem aprovou e o hash do SQL. Exige o privilégio manage_reports. Em cards de consulta (query) responde 400.

POST/api/v1/vendor/dashboards/{id}/cards/{cardId}/approveSeller

Aprovar card SQL

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).

cardIduuidobrigatório

Id do card (UUID).

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

Resposta

200Card aprovado

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": "S",
  "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",
  "approved_by_user_id": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "approved_at": "2026-10-11T21:40:00Z"
}

Erros

Status	Quando	Corpo de exemplo
400	O card não é do tipo `sql`.	`{"error":"card_not_sql"}`
403	Sem o privilégio `manage_reports`.	`{"error":"manage_reports required to approve a sql card"}`
404	A aba ou o card não existe ou não é do seller. Os dois casos dão `404`.	`{"error":"card not found"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`