Painel da empresa (widgets)
Todo servidor Empresa tem um Painel: uma página, ao lado do Escritório, com widgets que quem gerencia o servidor monta e que todo mundo da empresa vê. Ele é programável: um bot com a permissão Gerenciar servidor (MANAGE_GUILD) cria e atualiza widgets pela API, e cada mudança aparece na hora para todos.
Ideias: as vendas do dia vindas do ERP, os chamados abertos do suporte, o status dos sistemas, o cardápio da semana, um dashboard do Grafana.
Os tipos
kind | o que mostra | data |
|---|---|---|
note | Texto com formatação, como numa mensagem. | { "text": "**Reunião** às 10h" } (até 4000 caracteres) |
numbers | Até 12 números com nome. | { "items": [{ "label": "Vendas", "value": "R$ 12.400", "hint": "meta R$ 15 mil" }] } |
card | Um cartão igual aos das mensagens de bot. | { "card": { "title": "…", "fields": [ … ] } } (veja cartões) |
embed | Uma página https dentro do painel. | { "url": "https://…", "height": 360 } (altura de 120 a 900) |
Em numbers, label vai até 60 caracteres, value até 24 (número ou texto) e hint até 80. Uma página (embed) precisa permitir ser exibida em outros sites, e páginas do próprio Zynko não podem entrar. Campos que o tipo não usa são descartados.
As rotas
Todas pedem um token de bot (ou de pessoa) com MANAGE_GUILD no servidor, menos a listagem, que qualquer membro faz.
| rota | corpo | |
|---|---|---|
| listar | GET /api/v1/guilds/{guild_id}/widgets | |
| criar | POST /api/v1/guilds/{guild_id}/widgets | { "kind", "title", "width"?, "data"? } |
| atualizar | PATCH /api/v1/guilds/{guild_id}/widgets/{widget_id} | { "title"?, "width"?, "data"? } |
| reordenar | PATCH /api/v1/guilds/{guild_id}/widgets | { "order": [ids de todos os widgets] } |
| remover | DELETE /api/v1/guilds/{guild_id}/widgets/{widget_id} |
width é 1 ou 2 (colunas da grade). Em PATCH, data substitui o conteúdo inteiro. O painel tem até 30 widgets. Todos os membros recebem o evento GUILD_WIDGETS_UPDATE com a lista inteira a cada mudança.
O widget
json
{
"id": "117070000000000000",
"guild_id": "117060000000000000",
"kind": "numbers",
"title": "Vendas",
"position": 0,
"width": 2,
"data": { "items": [{ "label": "Hoje", "value": "43" }] },
"updated_at": 1795136000000,
"updated_by": "117069000000000000"
}Exemplo: um bot que atualiza as vendas
O ID do widget aparece no app (menu do widget → Copiar ID do widget) ou na listagem.
js
const API = 'https://zynko.org/api/v1';
const headers = { Authorization: `Bot ${process.env.ZYNKO_TOKEN}`, 'Content-Type': 'application/json' };
async function atualizar(guildId, widgetId, vendasHoje, chamados) {
const res = await fetch(`${API}/guilds/${guildId}/widgets/${widgetId}`, {
method: 'PATCH',
headers,
body: JSON.stringify({
data: {
items: [
{ label: 'Vendas hoje', value: vendasHoje.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' }) },
{ label: 'Chamados abertos', value: chamados, hint: 'fila do suporte' },
],
},
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
}
// A cada 5 minutos, com os números do seu sistema.
setInterval(() => atualizar('117060000000000000', '117070000000000000', 12400, 7), 5 * 60_000);O bot precisa estar no servidor com Gerenciar servidor: marque essa permissão no link de convite (permissions com o bit 2, veja Convite e permissões).