Dashboards

O dashboard do painel de administração é construído com esta API. Ele é um conjunto de abas (cada uma com um nome, um período padrão e uma posição), e cada aba tem cards: um número, um gráfico, uma tabela ou uma nota. Os cards não guardam SQL nem dados: guardam uma especificação que diz o que medir, e a plataforma executa quando você pede. Por isso é possível montar telas novas, copiar abas entre pessoas e publicá-las para sellers (lojistas) sem que cada um veja os números do outro.

Como funciona

O ciclo típico de uma integração:

1. Descobrir o que existe

   Chame Catálogo e modelos para conhecer entidades, campos, métricas e os mais de 200 modelos prontos.

2. Criar a aba

   Crie a aba e adicione cards: escrevendo a especificação, a partir de um modelo ou por texto.

3. Testar antes de salvar

   Use o preview para ver os dados de uma especificação sem gravar.

4. Mostrar os dados

   Execute a aba: uma chamada devolve um resultado por card, com no máximo 4 em paralelo no servidor.

5. Compartilhar e acompanhar

   Publique a aba, crie alertas e envios agendados e leia os insights.

Tipos de card

Conceitos-chave

Aba e card

Uma aba é uma tela do dashboard; um card é um item dentro dela, numa grade de 3 colunas (grid_col 0 a 2) com largura e altura de 1 a 3. O layout fica no card, fora da especificação, por isso a especificação pode ser copiada, publicada e salva como modelo sem carregar posição.

Painel do administrador e do seller

Estas rotas são do painel do administrador (panel: A). O seller (lojista) tem as próprias abas em outro conjunto de rotas, fora desta seção. Uma aba do administrador publicada para sellers aparece para eles em leitura.

Visibilidade

P privada, S compartilhada, G global. Além da visibilidade, o acesso passa por compartilhamentos com permissão R ou W. Quem não pode ver uma aba recebe 404, igual a uma aba que não existe.

Período

Cada aba tem um default_period. Cards com period.mode: inherit usam o período recebido na chamada ou, sem ele, o da aba. Cards com período próprio não mudam.

Controle de versão do layout

Cada aba tem um version (milissegundos Unix da última alteração). Ao reorganizar o layout, devolva o version que você leu: se outra pessoa salvou antes, a API responde 409 com o layout atual em vez de sobrescrever.

Fuso horário

Dias, semanas e meses seguem o fuso da loja (America/Sao_Paulo). As datas dos objetos vêm em RFC 3339, UTC.

Endpoints

Erros comuns

• Esperar dados em GET /dashboards/{id}: ele devolve só a aba e as especificações. Os números vêm de POST .../run.
• Tratar 200 como sucesso de todos os cards: confira status e meta.error de cada resultado.
• Usar PUT de card enviando só o que mudou: ele substitui a especificação e o layout inteiros.
• Tentar renomear ou apagar a aba de fábrica (409 system_dashboard_immutable): duplique.
• Inventar entity e field: use os ref do catálogo. Campos desconhecidos dão 422 unknown_field.
• Chamar .../run em assinatura de produção: o e-mail é enviado de verdade.
• Ler shares como lista sempre: sem compartilhamentos vem null.
• Dividir centavos por 100 duas vezes: veja columns[].unit.

Próximos passos