API Echo

API REST pública e webhooks: conecte a economia, os níveis e o monitoramento do seu servidor aos seus próprios serviços — servidor de jogo, site, bot ou automações.

https://api.echo-assistants.tech

Autorização Segurança das chaves Serviço Economia Níveis Monitoramento Integrações Catálogo Webhooks Notificações de integrações Escopos Limites e erros

Autorização

Toda requisição precisa de uma chave no cabeçalho Authorization. A chave é emitida para um servidor, não para uma conta. Só o dono do servidor pode criá-la no painel → “Desenvolvedores”: até 3 (10 com Premium) chaves. Os endpoints /catalog/* são públicos — não precisam de chave (limite de 60/min por IP, respostas em cache).

curl https://api.echo-assistants.tech/me \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Criar uma chave

Segurança das chaves

A chave começa com echoapi_, seguida de 30 letras latinas e dígitos aleatórios e de uma soma de verificação de 6 caracteres. A API recusa na hora uma string com soma de verificação errada (401). As chaves no formato antigo (echo_…) continuam funcionando; ao ser gerada de novo, a chave recebe o novo formato.

Expressão para encontrar chaves no seu próprio código

\bechoapi_[0-9A-Za-z]{36}\b

Uma chave exposta publicamente é desativada automaticamente. Pelo programa Secret Scanning, o GitHub nos informa sobre chaves encontradas em repositórios públicos, e o bot Echo detecta chaves em mensagens nos servidores e exclui essas mensagens. O dono do servidor e quem criou a chave recebem uma notificação no site, no Telegram e por e-mail, com um link para o lugar onde a chave foi encontrada.

O que fazer: abra as chaves do servidor no Portal do desenvolvedor e clique em Gerar de novo no card da chave. A chave recebe um novo segredo e volta a funcionar; a antiga para de funcionar na hora. Substitua a chave em todos os lugares onde ela está guardada. Uma chave encontrada não pode ser reativada sem ser gerada de novo. Se você não precisa mais da chave, revogue-a.

Guarde a chave no seu próprio servidor — em variáveis de ambiente ou em um cofre de segredos. Não coloque a chave no código de páginas ou aplicativos, em repositórios, mensagens ou capturas de tela.

Serviço

GET/mesem escopo

Verificação da chave: retorna o servidor e seus escopos.

Exemplo

curl "https://api.echo-assistants.tech/me" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "guildId": "1369...", "scopes": ["levels:read"] }

Economia

GET/economy/balance?user=<id>economy:read

Saldo do membro: carteira, banco, fichas.

Exemplo

curl "https://api.echo-assistants.tech/economy/balance?user=123456789012345678" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "user": "123...", "balance": 1500, "bank": 200, "chips": 0 }

POST/economy/balanceeconomy:write

Adicionar ou deduzir moeda. delta pode ser negativo; o saldo fica entre 0…2.000.000.000.

Exemplo

curl -X POST "https://api.echo-assistants.tech/economy/balance" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "user": "123...", "delta": 250 }'

Corpo da requisição

{ "user": "123...", "delta": 250 }

Resposta

{ "ok": true, "user": "123...", "balance": 1750 }

GET/economy/leaderboard?limit=<n>economy:read

Top membros por saldo (limit 1–100, padrão 20).

Exemplo

curl "https://api.echo-assistants.tech/economy/leaderboard?limit=20" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "guildId": "1369...", "leaderboard": [ { "rank": 1, "userId": "627...", "balance": 15000, "bank": 3000 } ] }

Níveis

GET/levels/leaderboard?limit=<n>levels:read

Top membros por experiência (limit 1–100, padrão 20).

Exemplo

curl "https://api.echo-assistants.tech/levels/leaderboard?limit=20" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "guildId": "1369...", "leaderboard": [ { "rank": 1, "userId": "627...", "xp": 3965, "messages": 374, "voiceSeconds": 1273 } ] }

GET/levels/xp?user=<id>levels:read

O XP e o nível de um membro; nextLevelXp é o total de XP necessário para o próximo nível.

Exemplo

curl "https://api.echo-assistants.tech/levels/xp?user=123456789012345678" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "user": "123...", "xp": 1320, "level": 4, "nextLevelXp": 1500 }

POST/levels/xplevels:write

Adicionar ou remover XP: delta é um número inteiro, até ±1.000.000 por requisição; o XP nunca fica abaixo de zero. O nível é recalculado na hora. Se ele subir, o bot dá as recompensas de nível (cargos, moedas, anúncio) como na progressão normal e envia o evento member.level_up marcado com "via": "api". Baixar o nível não tira as recompensas. Só para membros do servidor (senão 404 not_member); se os níveis estiverem desativados no servidor — 409 levels_off.

Exemplo

curl -X POST "https://api.echo-assistants.tech/levels/xp" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "user": "123...", "delta": 250 }'

Corpo da requisição

{ "user": "123...", "delta": 250 }

Resposta

{ "ok": true, "user": "123...", "xp": 1570, "level": 5, "previousXp": 1320, "previousLevel": 4, "levelUp": true }

Monitoramento

GET/monitoring/servermonitoring:read

Card do servidor no catálogo: Chamas no período, total, posição no top e status.

Exemplo

curl "https://api.echo-assistants.tech/monitoring/server" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "guildId": "1369...", "slug": "my-server", "flames": 420, "flamesTotal": 9100, "published": true, "rank": 3, "partner": true, "verified": true }

GET/monitoring/top?limit=<n>monitoring:read

Top servidores do catálogo por Chamas (limit 1–100, padrão 20).

Exemplo

curl "https://api.echo-assistants.tech/monitoring/top?limit=20" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "top": [ { "rank": 1, "guildId": "1369...", "slug": "my-server", "flames": 980, "flamesTotal": 21000 } ] }

Integrações

Conecte seu jogo, site ou CRM: os atributos dos membros viram cargos pelas regras do painel → “Integrações”, os jogadores vinculam contas com um código e os cargos permitidos podem ser atribuídos diretamente. Os corpos de escrita são JSON de até 8 KB.

PUT/members/<discordId>/attributesmembers:write

Enviar os atributos de um membro (substituição completa): até 25 campos, nomes com letras latinas/dígitos/_, valores como string de até 100 caracteres, número ou true/false. O bot recalcula na hora os cargos das regras.

Exemplo

curl -X PUT "https://api.echo-assistants.tech/members/123456789012345678/attributes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "attributes": { "faction": "police", "rank": 3, "vip": true } }'

Corpo da requisição

{ "attributes": { "faction": "police", "rank": 3, "vip": true } }

Resposta

{ "ok": true, "discordId": "123...", "attributes": { "faction": "police", "rank": 3, "vip": true } }

GET/members/<discordId>/attributesmembers:read

O que foi enviado para o membro e qual conta externa ele vinculou.

timedRoles — cargos liberados para a API que foram dados por tempo limitado, e quando o bot vai removê-los.

Exemplo

curl "https://api.echo-assistants.tech/members/123456789012345678/attributes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "discordId": "123...", "externalId": "Ivan_Petrov", "attributes": { "faction": "police", "rank": 3 }, "timedRoles": [ { "roleId": "1369...", "expiresAt": "2026-10-10T12:00:00.000Z" } ] }

DELETE/members/<discordId>/attributesmembers:write

Limpar todos os atributos de um membro. O bot remove os cargos atribuídos pelas regras e não mexe nos cargos dados manualmente.

Exemplo

curl -X DELETE "https://api.echo-assistants.tech/members/123456789012345678/attributes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "ok": true, "removed": true }

PUT/external/<externalId>/attributesmembers:write

O mesmo, pelo ID no seu sistema (apelido, UUID, license:…). Vale para quem vinculou a conta com um código; até lá, fica armazenado e é aplicado no vínculo. Se os nomes coincidirem, prevalecem os atributos enviados por Discord ID.

Exemplo

curl -X PUT "https://api.echo-assistants.tech/external/Ivan_Petrov/attributes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "attributes": { "faction": "army", "rank": 5 } }'

Corpo da requisição

{ "attributes": { "faction": "army", "rank": 5 } }

Resposta

{ "ok": true, "externalId": "Ivan_Petrov", "discordId": "123...", "attributes": { "faction": "army", "rank": 5 } }

GET/external/<externalId>/attributesmembers:read

O que foi enviado para a conta externa e quem a vinculou (discordId: null — ninguém ainda).

Exemplo

curl "https://api.echo-assistants.tech/external/Ivan_Petrov/attributes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "externalId": "Ivan_Petrov", "discordId": "123...", "attributes": { "faction": "army", "rank": 5 } }

DELETE/external/<externalId>/attributesmembers:write

Limpar todos os atributos de uma conta externa.

Exemplo

curl -X DELETE "https://api.echo-assistants.tech/external/Ivan_Petrov/attributes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "ok": true, "removed": true }

POST/link-codeslinks:write

Um código de vínculo para o jogador: 8 caracteres, uso único, válido por ttlMinutes (1–60, padrão 15). O jogador clica em “Vincular conta” no painel do servidor (ou usa /link) e digita o código. Um novo código para a mesma conta anula o anterior.

Exemplo

curl -X POST "https://api.echo-assistants.tech/link-codes" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "Ivan_Petrov", "ttlMinutes": 15 }'

Corpo da requisição

{ "externalId": "Ivan_Petrov", "ttlMinutes": 15 }

Resposta

{ "code": "K7PQ3MZA", "display": "K7PQ-3MZA", "externalId": "Ivan_Petrov", "expiresAt": "2026-09-29T12:15:00.000Z" }

GET/links?externalId=<externalId>links:read

De quem é a conta: por externalId ou por discordId (?discordId=…). Sem vínculo — 404 not_linked.

Exemplo

curl "https://api.echo-assistants.tech/links?externalId=Ivan_Petrov" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "externalId": "Ivan_Petrov", "discordId": "123...", "linkedAt": "2026-09-29T12:03:11.000Z" }

DELETE/links?externalId=<externalId>links:write

Desvincular uma conta (ou ?discordId=…). Os atributos da conta externa deixam de valer para a pessoa.

Exemplo

curl -X DELETE "https://api.echo-assistants.tech/links?externalId=Ivan_Petrov" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "ok": true, "externalId": "Ivan_Petrov", "discordId": "123..." }

POST/members/<discordId>/rolesroles:write

Atribuir e remover cargos diretamente — só os que o dono marcou no portal de desenvolvedores → “Chaves de API” → “Permitido às chaves” (até 10 por lista). remove tira qualquer cargo permitido, mesmo um dado manualmente. Quem executa é o bot: a resposta é 202 com o número da tarefa.

durationMinutes (1–525.600) — dá os cargos de add por tempo limitado: quando o prazo acabar, o bot os remove sozinho. O prazo nunca encurta um prazo já definido, e um cargo que o membro já tinha sem prazo continua permanente. add sem durationMinutes torna o cargo permanente; remove cancela uma remoção agendada.

Exemplo

curl -X POST "https://api.echo-assistants.tech/members/123456789012345678/roles" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "add": ["1369..."], "remove": ["1370..."], "durationMinutes": 1440 }'

Corpo da requisição

{ "add": ["1369..."], "remove": ["1370..."], "durationMinutes": 1440 }

Resposta

{ "ok": true, "opId": 42, "status": "pending" }

GET/role-ops/<opId>roles:write

O resultado de uma tarefa de atribuição: pending, done ou failed, e o que aconteceu com cada cargo.

Numa concessão temporária, result.expiresAt mostra quando o bot vai remover cada cargo dado (null — o membro já tinha o cargo sem prazo, e ele continua permanente).

Exemplo

curl "https://api.echo-assistants.tech/role-ops/42" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "opId": 42, "discordId": "123...", "status": "done", "durationMinutes": 1440, "result": { "added": ["1369..."], "removed": [], "failed": [], "expiresAt": { "1369...": "2026-10-10T12:00:00.000Z" } } }

POST/channels/<channelId>/messagesmessages:write

Mensagem em nome do bot (o bot próprio do servidor, se estiver conectado) — só nos canais que o dono marcou no portal de desenvolvedores → “Chaves de API” → “Permitido às chaves” (até 10). content — até 2000 caracteres, embeds — até 10 embeds simples: title, description, url, color, timestamp, author.name, footer.text, image.url, thumbnail.url, fields; links só com https. Por padrão as menções não notificam ninguém: só podem ser notificados membros do servidor listados em mentionUsers (até 10), e @everyone, @here e cargos nunca. Corpo da requisição — até 32 KB. Quem executa é o bot: a resposta é 202 com o número da tarefa.

Exemplo

curl -X POST "https://api.echo-assistants.tech/channels/137100000000000000/messages" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Сервер перезапустится через 5 минут", "embeds": [ { "title": "Технические работы", "description": "Начало в 03:00 МСК", "color": 9133302 } ], "mentionUsers": ["123..."] }'

Corpo da requisição

{ "content": "Сервер перезапустится через 5 минут", "embeds": [ { "title": "Технические работы", "description": "Начало в 03:00 МСК", "color": 9133302 } ], "mentionUsers": ["123..."] }

Resposta

{ "ok": true, "opId": 77, "status": "pending" }

GET/message-ops/<opId>messages:write

O resultado do envio: pending, done (id da mensagem e link) ou failed com um motivo: channel_not_allowed, channel_missing, missing_permissions, rejected.

Exemplo

curl "https://api.echo-assistants.tech/message-ops/42" \
  -H "Authorization: Bearer echoapi_ВАШ_КЛЮЧ"

Resposta

{ "opId": 77, "channelId": "1371...", "status": "done", "result": { "messageId": "1372...", "channelId": "1371...", "url": "https://discord.com/channels/1369.../1371.../1372..." } }

Catálogo

GET/catalog/servers?search=&tag=&lang=&limit=público · sem chave

Busca e lista de servidores do catálogo de monitoramento. Totalmente público — sem chave.

Exemplo

curl "https://api.echo-assistants.tech/catalog/servers"

Resposta

{ "count": 1, "servers": [ { "slug": "my-server", "name": "My Server", "memberCount": 5200, "flames": 980, "tags": ["Игры"], "language": "ru", "invite": "https://discord.gg/...", "badges": { "verified": true } } ] }

GET/catalog/top?limit=<n>público · sem chave

Top do catálogo por Chamas.

Exemplo

curl "https://api.echo-assistants.tech/catalog/top?limit=20"

Resposta

{ "top": [ { "rank": 1, "slug": "my-server", "name": "My Server", "flames": 980 } ] }

GET/catalog/server/<slug>público · sem chave

Card público do servidor: descrição, Chamas, posição, tags, insígnias, convite, avaliação.

Exemplo

curl "https://api.echo-assistants.tech/catalog/server/my-server"

Resposta

{ "slug": "my-server", "name": "My Server", "flames": 980, "rank": 3, "rating": { "avg": 8.7, "count": 42 }, "invite": "https://discord.gg/..." }

GET/catalog/reviews/<slug>?limit=<n>público · sem chave

Avaliações do servidor com a nota média.

Exemplo

curl "https://api.echo-assistants.tech/catalog/reviews/my-server?limit=20"

Resposta

{ "slug": "my-server", "summary": { "avg": 8.7, "count": 42 }, "reviews": [ { "user": "Ник", "rating": 9, "comment": "Топ", "at": "..." } ] }

GET/catalog/tagspúblico · sem chave

Tags/categorias do catálogo com o número de servidores.

Exemplo

curl "https://api.echo-assistants.tech/catalog/tags"

Resposta

{ "tags": [ { "tag": "Игры", "count": 128 } ] }

Webhooks

O Echo envia eventos para a sua URL em tempo real. Configure um webhook no painel → “Desenvolvedores”. Cada requisição é assinada com o cabeçalho X-Echo-Signature (HMAC-SHA256 do corpo usando o seu segredo); o nome do evento vem em X-Echo-Event.

flame.bump

O servidor recebeu Chama, no catálogo ou com /flame.

{
  "event": "flame.bump",
  "guildId": "1369...",
  "flames": 421,
  "flamesTotal": 9101,
  "amount": 1,
  "source": "web",
  "at": "2026-07-27T20:30:00.000Z"
}

test

Enviado pelo botão “Enviar teste” — para verificar se o receptor funciona.

{ "event": "test", "guildId": "1369...", "message": "Проверка вебхука Echo", "at": "..." }

Verificação da assinatura

import crypto from "node:crypto";

// body é o texto bruto da requisição, secret vem do painel
const expected = "sha256=" +
  crypto.createHmac("sha256", secret).update(body).digest("hex");
const header = req.headers["x-echo-signature"];
const got = Buffer.from(typeof header === "string" ? header : "");
const want = Buffer.from(expected);
const ok = got.length === want.length && crypto.timingSafeEqual(got, want);

Notificações de integrações (Premium)

Configuradas no painel → “Integrações”. O Echo envia um POST JSON {"id", "event", "guildId", "at", "data"}: a assinatura é X-Echo-Signature (sha256= mais HMAC-SHA256 do corpo bruto com o seu segredo), o nome do evento vem em X-Echo-Event e o número da entrega em X-Echo-Delivery.

Responda com 2xx em até 8 segundos. Caso contrário, tentamos de novo após 30 s, 2 min, 10 min e 1 h com o mesmo id; redirecionamentos não são seguidos. A URL deve ser https na porta 443 com IP público. Após 20 falhas seguidas, o envio é desativado — reative-o no painel quando o seu receptor estiver funcionando.

member.join

Um membro entrou no servidor.

{ "id": "evt_…", "event": "member.join", "guildId": "1369...", "at": "2026-09-29T12:00:00.000Z",
  "data": { "discordId": "123...", "username": "ivan", "joinedAt": "2026-09-29T12:00:00.000Z" } }

member.leave

Um membro saiu ou foi removido.

{ "id": "evt_…", "event": "member.leave", "guildId": "1369...", "at": "…", "data": { "discordId": "123...", "username": "ivan" } }

member.level_up

Um membro subiu de nível.

{ "id": "evt_…", "event": "member.level_up", "guildId": "1369...", "at": "…", "data": { "discordId": "123...", "oldLevel": 4, "newLevel": 5, "xp": 1320 } }

store.purchase

Uma compra na vitrine do servidor: cargo atribuído, pacote de moedas creditado (kind "coins", campo coins) ou uma doação ao servidor. Doações anônimas não têm comprador.

{ "id": "evt_…", "event": "store.purchase", "guildId": "1369...", "at": "…",
  "data": { "orderId": 815, "kind": "role", "itemName": "VIP", "roleId": "1369...", "buyerId": "123...", "discordId": "123...", "priceKopecks": 14900, "durationDays": 30 } }

ticket.opened

Um ticket foi aberto.

{ "id": "evt_…", "event": "ticket.opened", "guildId": "1369...", "at": "…", "data": { "ticketId": 311, "number": 57, "discordId": "123...", "channelId": "1371...", "panelId": 4 } }

account.linked

Um jogador vinculou uma conta com um código.

{ "id": "evt_…", "event": "account.linked", "guildId": "1369...", "at": "…",
  "data": { "externalId": "Ivan_Petrov", "discordId": "123...", "username": "ivan", "previousDiscordId": null, "previousExternalId": null } }

test

O botão “Enviar teste” no painel → “Integrações”.

{ "id": "evt_…", "event": "test", "guildId": "1369...", "at": "…", "data": { "message": "…" } }

Verificação da assinatura — Node.js

import crypto from "node:crypto";
import express from "express";
import pg from "pg";

const app = express();
const SECRET = process.env.ECHO_WEBHOOK_SECRET; // whsec_… из панели
const GUILD_ID = process.env.ECHO_GUILD_ID;
if (!SECRET || !GUILD_ID) throw new Error("ECHO_WEBHOOK_SECRET and ECHO_GUILD_ID required");
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

// Выполните миграцию в своей PostgreSQL заранее:
// CREATE TABLE echo_webhook_events (
//   guild_id text NOT NULL, event_id text NOT NULL,
//   PRIMARY KEY (guild_id, event_id)
// );
// Храните ID минимум 2 часа. Несколько процессов используют одну таблицу.

// a assinatura é calculada sobre o corpo bruto, antes de interpretar o JSON
app.post("/echo-webhook", express.raw({ type: "application/json", limit: "64kb" }), async (req, res) => {
  if (!Buffer.isBuffer(req.body)) return res.status(400).end();
  const expected = "sha256=" +
    crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const got = Buffer.from(req.get("X-Echo-Signature") ?? "");
  const want = Buffer.from(expected);
  const ok = got.length === want.length && crypto.timingSafeEqual(got, want);
  if (!ok) return res.status(401).end();

  let event;
  try { event = JSON.parse(req.body.toString("utf8")); }
  catch { return res.status(400).end(); }
  if (!event || typeof event !== "object" || Array.isArray(event) ||
      typeof event.id !== "string" || !/^evt_[0-9a-f-]{36}$/.test(event.id) ||
      event.guildId !== GUILD_ID || typeof event.event !== "string" ||
      typeof event.at !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(event.at)) return res.status(400).end();
  const at = Date.parse(event.at);
  const age = Date.now() - at;
  // Повторы сохраняют at; неверная дата и будущее дальше 5 минут — отказ.
  if (!Number.isFinite(at) || new Date(at).toISOString() !== event.at || age > 2 * 60 * 60_000 || age < -5 * 60_000) return res.status(400).end();

  let db;
  try {
    db = await pool.connect();
    await db.query("BEGIN");
    const claimed = await db.query(
      "INSERT INTO echo_webhook_events (guild_id, event_id) VALUES ($1, $2) ON CONFLICT DO NOTHING RETURNING event_id",
      [event.guildId, event.id],
    );
    if (!claimed.rowCount) {
      await db.query("ROLLBACK");
      return res.status(204).end();
    }
    // Изменение награды/баланса делайте через db В ЭТОЙ транзакции.
    // Для внешнего действия записывайте outbox здесь и обрабатывайте отдельно.
    await db.query("COMMIT");
    return res.status(204).end();
  } catch {
    if (db) await db.query("ROLLBACK").catch(() => {});
    return res.status(500).end();
  } finally {
    db?.release();
  }
});

Verificação da assinatura — PHP

<?php
$secret = getenv('ECHO_WEBHOOK_SECRET'); // whsec_… из панели
$guildId = getenv('ECHO_GUILD_ID');
if (!$secret || !$guildId) { http_response_code(500); exit; }
// a assinatura é calculada sobre o corpo bruto, antes de interpretar o JSON
$body = file_get_contents('php://input');
if ($body === false || strlen($body) > 65536) { http_response_code(413); exit; }
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
$got = $_SERVER['HTTP_X_ECHO_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
if (!is_array($event) || !is_string($event['id'] ?? null) ||
    !preg_match('/^evt_[0-9a-f-]{36}$/D', $event['id']) ||
    ($event['guildId'] ?? null) !== $guildId ||
    !is_string($event['event'] ?? null) || !is_string($event['at'] ?? null) ||
    !preg_match('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/D', $event['at'])) {
    http_response_code(400);
    exit;
}
$date = DateTimeImmutable::createFromFormat('Y-m-d\TH:i:s.v\Z', $event['at'], new DateTimeZone('UTC'));
$at = $date && $date->format('Y-m-d\TH:i:s.v\Z') === $event['at'] ? $date->getTimestamp() : false;
$age = $at === false ? null : time() - $at;
if ($age === null || $age > 7200 || $age < -300) {
    http_response_code(400); exit;
}
// Та же миграция PostgreSQL, что в Node.js-примере.
// ECHO_DATABASE_DSN: pgsql:host=…;dbname=… (PDO_PGSQL).
$db = new PDO(getenv('ECHO_DATABASE_DSN'), getenv('ECHO_DATABASE_USER'), getenv('ECHO_DATABASE_PASSWORD'),
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
try {
    $db->beginTransaction();
    $claim = $db->prepare('INSERT INTO echo_webhook_events (guild_id, event_id) VALUES (?, ?) ON CONFLICT DO NOTHING RETURNING event_id');
    $claim->execute([$event['guildId'], $event['id']]);
    if ($claim->fetchColumn() === false) {
        $db->rollBack(); http_response_code(204); exit;
    }
    // Изменение награды/баланса делайте через $db В ЭТОЙ транзакции.
    // Внешние действия — через outbox, записанный здесь.
    $db->commit();
    http_response_code(204);
} catch (Throwable $e) {
    if ($db->inTransaction()) $db->rollBack();
    http_response_code(500);
}

Escopos

Ao criar uma chave, você escolhe as permissões — cada endpoint exige seu próprio escopo.

guild:read

Dados do servidor

Informações básicas sobre o servidor.

economy:read

Leitura da economia

Saldos: carteira, banco, fichas.

economy:write

Escrita na economia

Adição e dedução de moeda.

levels:read

Leitura de níveis

Experiência e ranking de membros.

monitoring:read

Leitura do monitoramento

Chamas, posição no top, status no catálogo.

members:read

Leitura de atributos

Leitura dos atributos dos membros pelo ID do Discord e pelo ID no sistema externo — sem permissão para alterá-los.

members:write

Atributos de membros

Enviar atributos por Discord ID e por ID do sistema externo.

roles:write

Atribuição de cargos

Atribuir e remover cargos permitidos no portal de desenvolvedores → “Chaves de API” → “Permitido às chaves”.

links:read

Leitura de vínculos

De quem é a conta: o vínculo ID externo ↔ Discord.

links:write

Códigos de vínculo

Emitir códigos de vínculo e desvincular contas.

levels:write

Escrita de XP

Adicionar e remover XP; as recompensas de nível são dadas pelo bot.

messages:write

Mensagens do bot

Mensagens em nome do bot nos canais permitidos no portal de desenvolvedores → “Chaves de API” → “Permitido às chaves”.

Limites e erros

Até 3 (10 com Premium) chaves por servidor, com limite de 40 (120 com Premium) requisições por minuto por chave. Os erros são retornados como JSON { "error": "..." } com o código HTTP correspondente.

Código	error	Quando
400	bad_fields	Parâmetros da requisição inválidos ou ausentes.
401	unauthorized	Chave não enviada, inválida ou revogada.
403	insufficient_scope	A chave não tem o escopo necessário para esta requisição.
403	key_paused_premium	A chave está pausada: o servidor não tem Premium, e sem ele só funcionam as chaves dentro do limite grátis que foram geradas primeiro.
404	not_linked	A conta não está vinculada (métodos de vínculo) ou a tarefa não foi encontrada.
409	levels_off	A ação não combina com as configurações do servidor: por exemplo, os níveis estão desativados.
413	body_too_large	O corpo da requisição é maior que 8 KB.
429	rate_limited	Limite de 40 (120 com Premium) requisições por minuto excedido.
502	discord_unavailable	O Discord não respondeu — repita a requisição mais tarde.

A chave completa só aparece uma vez, na criação — salve-a. A administração do projeto pode desativar uma chave em caso de abuso.