Dashboards do seller

Um dashboard do seller é uma coleção de abas, e cada aba é uma grade de cards. Um card responde a uma pergunta de negócio (por exemplo, "quanto vendi neste mês?") e é desenhado como número, gráfico ou tabela. O seller (lojista) monta as próprias abas, o painel guarda a definição de cada card e a plataforma executa essas definições e devolve os dados prontos para desenhar. Esta seção documenta as rotas /api/v1/vendor/dashboards.

O ponto central: o card não é código nem SQL. É um documento JSON, a spec, que diz qual entidade do catálogo consultar (pedidos, produtos, devoluções...), quais métricas somar, como agrupar e filtrar, e como desenhar. A plataforma valida a spec, compila a consulta e sempre a restringe ao seller do token: não existe parâmetro para escolher outro seller.

Como funciona

1. Descubra o que dá para consultar

   GET /vendor/dashboards/catalog lista as entidades, campos e métricas disponíveis para o seller, com limites e tipos de gráfico.

2. Monte e teste a spec

   POST /vendor/dashboards/preview executa uma spec sem salvar. Ajuste até o resultado fazer sentido. Se preferir, POST /vendor/dashboards/ai/spec gera a spec a partir de uma frase.

3. Salve o card na aba

   POST /vendor/dashboards/{id}/cards guarda o card. A spec é revalidada: card que não compila não entra.

4. Execute e desenhe

   POST /vendor/dashboards/{id}/run devolve os dados de todos os cards. POST .../cards/{cardId}/drilldown abre as linhas por trás de um ponto do gráfico.

5. Acompanhe sem abrir o painel

   POST /vendor/dashboards/subscriptions cria um alerta de limite ou um envio periódico por e-mail.

Conceitos-chave

Aba e card

Uma aba (dashboard) tem nome, ícone, cor, um período padrão e posição. Um card pertence a uma aba, guarda a spec e o lugar na grade (grid_row, grid_col, width, height, de 1 a 3 colunas ou linhas). O layout fica fora da spec de propósito, para o mesmo card poder ser copiado ou virar modelo.

Aba de fábrica

Todo seller recebe uma aba fabrica (is_system: true) com cards prontos. Ela não pode ser renomeada nem apagada, mas pode ser restaurada ao estado original e duplicada para virar um ponto de partida seu.

Tipos de card

Dataset

Executar um card devolve um dataset: columns (cada uma com key, label, type, role dimensão ou métrica, unit), rows (lista de listas, na ordem das colunas) e meta (row_count, truncated, limit, elapsed_ms, cached, spec_hash, warnings, error). Um erro de execução não vira status HTTP: vem em meta.error (ou em error no resultado de run) com um code e uma message_key.

Período

O período de cada card pode ser inherit (usa o da aba ou o enviado na chamada), preset (today, yesterday, last7, last30, last90, thisMonth, lastMonth, thisQuarter, thisYear, lastYear), relative (last_n_days de 1 a 1095) ou fixed (from e to). Sem nenhum período, vale last30. Os dias são os de Brasília.

Status contados na receita

Métricas como orders.revenue e orders.orders_count dependem de quais status de pedido contam como venda. Ao salvar o card, a plataforma grava em status_scope a lista de status naquele momento (mode: store_default acompanha a regra da loja; mode: custom congela a lista). O número do card é, portanto, reproduzível.

Endpoints

Erros comuns

• Tratar GET /vendor/dashboards como leitura pura. Na primeira vez ele cria a aba de fábrica. Se a lista vem vazia numa conta nova, não é erro: chame de novo.
• Esperar status HTTP de erro por card. run e preview respondem 200 mesmo quando um card falha. Olhe status (ok, error, native) de cada resultado.
• Formatar dinheiro pelo valor. Em rows, dinheiro vem como texto em centavos. Dividir por 100 só vale quando columns[].unit é cents.
• Mandar campos extras na spec. A spec é estrita: qualquer campo desconhecido é recusado com unknown_field.
• Tentar editar uma aba publicada pelo administrador. Ela é somente leitura. Duplique-a e edite a cópia.
• Salvar o layout sem a versão. Sem version, uma edição concorrente é sobrescrita sem aviso. Envie o version da última leitura e trate o 409.
• Confundir card sem dados com card quebrado. Um card que usa uma entidade que o seller não pode consultar (por exemplo, uma aba do administrador publicada) mostra um erro próprio no resultado, não derruba a aba.

Próximos passos