# 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](https://docs.zynko.org/bots/comandos.md)) |
| `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`](https://docs.zynko.org/api/eventos.md#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](https://docs.zynko.org/bots/convite.md)).
