API Echo

Публичный REST API и вебхуки: подключайте экономику, уровни и мониторинг сервера к своим сервисам — игровому серверу, сайту, боту или автоматизациям.

https://api.echo-assistants.tech

Авторизация Безопасность ключей Сервис Экономика Уровни Мониторинг Интеграции Каталог Вебхуки Уведомления интеграций Скоупы Лимиты и ошибки

Авторизация

Каждый запрос требует ключ в заголовке Authorization. Ключ выдаётся на сервер, а не на аккаунт. Создать его может только владелец сервера в дашборде → «Разработчикам»: до 3 (с Premium — 10) ключей. Эндпоинты /catalog/* — публичные, ключ не нужен (лимит 60/мин по IP, ответы кешируются).

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

Создать ключ

Безопасность ключей

Ключ начинается с echoapi_, дальше 30 случайных латинских букв и цифр и 6 символов контрольной суммы. Строку с неверной суммой API отклоняет сразу (401). Ключи прежнего вида (echo_…) продолжают работать; при перевыпуске ключ получает новый вид.

Выражение для поиска ключей в своём коде

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

Ключ в открытом доступе отключается автоматически. GitHub по программе Secret Scanning сообщает нам о ключах в публичных репозиториях, а бот Echo замечает ключи в сообщениях на серверах и удаляет такие сообщения. Владелец сервера и создатель ключа получают уведомление на сайте, в Telegram и на почту — со ссылкой на место находки.

Что делать: откройте ключи сервера в кабинете разработчика и нажмите Перевыпустить в карточке ключа. Ключ получит новый секрет и снова заработает, прежний перестанет действовать сразу. Замените ключ везде, где он записан. Включить найденный ключ без перевыпуска нельзя. Если ключ больше не нужен, отзовите его.

Храните ключ на своём сервере — в переменных окружения или хранилище секретов. Не вставляйте его в код страниц и приложений, в репозитории, сообщения и на снимки экрана.

Сервис

GET/meбез скоупа

Проверка ключа: возвращает сервер и его скоупы.

Пример

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

Ответ

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

Экономика

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

Баланс участника: кошелёк, банк, фишки.

Пример

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

Ответ

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

POST/economy/balanceeconomy:write

Начислить или списать валюту. delta может быть отрицательным; баланс остаётся в диапазоне 0…2 000 000 000.

Пример

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

Тело запроса

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

Ответ

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

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

Топ участников по балансу (limit 1–100, по умолчанию 20).

Пример

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

Ответ

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

Уровни

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

Топ участников по опыту (limit 1–100, по умолчанию 20).

Пример

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

Ответ

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

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

Опыт и уровень участника; nextLevelXp — сколько всего опыта нужно для следующего уровня.

Пример

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

Ответ

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

POST/levels/xplevels:write

Начислить или списать опыт: delta — целое число, до ±1 000 000 за запрос; опыт не опускается ниже нуля. Уровень пересчитывается сразу. Если он вырос, бот выдаёт награды за уровень (роли, монеты, объявление), как при обычной прокачке, и отправляет событие member.level_up с пометкой "via": "api". Понижение уровня награды не отбирает. Только для участников сервера (иначе 404 not_member); если уровни на сервере выключены — 409 levels_off.

Пример

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

Тело запроса

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

Ответ

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

Мониторинг

GET/monitoring/servermonitoring:read

Карточка сервера в каталоге: Пламя за период, всего, место в топе и статусы.

Пример

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

Ответ

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

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

Топ серверов каталога по Пламени (limit 1–100, по умолчанию 20).

Пример

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

Ответ

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

Интеграции

Подключение своей игры, сайта или CRM: атрибуты участников превращаются в роли по правилам из дашборда → «Интеграции», игроки привязывают аккаунты кодом, разрешённые роли можно выдавать напрямую. Тело записи — JSON до 8 КБ.

PUT/members/<discordId>/attributesmembers:write

Передать атрибуты участника (замена целиком): до 25 полей, имя — латиница/цифры/_, значение — строка до 100 символов, число или true/false. Роли по правилам бот пересчитает сразу.

Пример

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 } }'

Тело запроса

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

Ответ

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

GET/members/<discordId>/attributesmembers:read

Что прислано по участнику и какой внешний аккаунт он привязал.

timedRoles — роли из разрешённых для API, выданные на срок, и время, когда бот их снимет.

Пример

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

Ответ

{ "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

Снять все атрибуты участника. Роли, которые выдало правило, бот снимет; выданные руками — не трогает.

Пример

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

Ответ

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

PUT/external/<externalId>/attributesmembers:write

То же по ID в вашей системе (ник, UUID, license:…). Действует на того, кто привязал аккаунт кодом; пока не привязан — хранится и применится при привязке. Атрибуты по Discord ID важнее при совпадении имени.

Пример

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 } }'

Тело запроса

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

Ответ

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

GET/external/<externalId>/attributesmembers:read

Что прислано по внешнему аккаунту и кто его привязал (discordId: null — пока никто).

Пример

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

Ответ

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

DELETE/external/<externalId>/attributesmembers:write

Снять все атрибуты внешнего аккаунта.

Пример

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

Ответ

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

POST/link-codeslinks:write

Код привязки для игрока: 8 знаков, одноразовый, живёт ttlMinutes (1–60, по умолчанию 15). Игрок нажимает «Привязать аккаунт» на панели сервера (или /link) и вводит код. Новый код того же аккаунта гасит прежний.

Пример

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 }'

Тело запроса

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

Ответ

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

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

Чей аккаунт: по externalId или по discordId (?discordId=…). Нет связи — 404 not_linked.

Пример

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

Ответ

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

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

Отвязать аккаунт (или ?discordId=…). Атрибуты внешнего аккаунта перестают действовать на человека.

Пример

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

Ответ

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

POST/members/<discordId>/rolesroles:write

Выдать и снять роли напрямую — только те, что владелец отметил в кабинете разработчика → «Ключи API» → «Разрешено ключам» (до 10 в каждом списке). remove снимает любую разрешённую роль, даже выданную руками. Выполняет бот: ответ 202 с номером задания.

durationMinutes (1–525 600) — выдать роли из add на срок: по истечении бот снимет их сам. Срок не сокращает уже назначенный, а роль, которая была у участника без срока, остаётся бессрочной. add без durationMinutes делает роль бессрочной, remove отменяет назначенное снятие.

Пример

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 }'

Тело запроса

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

Ответ

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

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

Итог задания выдачи: pending, done или failed и что вышло по каждой роли.

У выдачи на срок в result.expiresAt указано, когда бот снимет каждую выданную роль (null — роль была у участника без срока и осталась бессрочной).

Пример

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

Ответ

{ "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

Сообщение от имени бота (своего бота сервера, если он подключён) — только в каналы, которые владелец отметил в кабинете разработчика → «Ключи API» → «Разрешено ключам» (до 10). content — до 2000 символов, embeds — до 10 простых эмбедов: title, description, url, color, timestamp, author.name, footer.text, image.url, thumbnail.url, fields; ссылки — только https. Упоминания по умолчанию никого не зовут: позвать можно только участников сервера из mentionUsers (до 10), а @everyone, @here и роли — никогда. Тело запроса — до 32 КБ. Выполняет бот: ответ 202 с номером задания.

Пример

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..."] }'

Тело запроса

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

Ответ

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

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

Итог отправки: pending, done (id сообщения и ссылка) или failed с причиной: channel_not_allowed, channel_missing, missing_permissions, rejected.

Пример

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

Ответ

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

Каталог

GET/catalog/servers?search=&tag=&lang=&limit=публичный · без ключа

Поиск и список серверов в каталоге мониторинга. Всё публично — ключ не нужен.

Пример

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

Ответ

{ "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>публичный · без ключа

Топ каталога по Пламени.

Пример

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

Ответ

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

GET/catalog/server/<slug>публичный · без ключа

Публичная карточка сервера: описание, Пламя, место, теги, бейджи, инвайт, рейтинг.

Пример

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

Ответ

{ "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>публичный · без ключа

Отзывы о сервере со средней оценкой.

Пример

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

Ответ

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

GET/catalog/tagsпубличный · без ключа

Теги/категории каталога с числом серверов.

Пример

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

Ответ

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

Вебхуки

Echo сам присылает события на ваш URL в реальном времени. Настройте вебхук в дашборде → «Разработчикам». Каждый запрос подписан заголовком X-Echo-Signature (HMAC-SHA256 тела по вашему секрету), имя события — в X-Echo-Event.

flame.bump

Серверу добавлено Пламя — в каталоге или командой /flame.

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

test

Отправляется кнопкой «Отправить тест» — проверить, что приёмник работает.

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

Проверка подписи

import crypto from "node:crypto";

// body — сырой текст запроса, secret — из дашборда
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);

Уведомления интеграций (Premium)

Настраиваются в дашборде → «Интеграции». Echo шлёт POST с JSON {"id", "event", "guildId", "at", "data"}: подпись — X-Echo-Signature (sha256= и HMAC-SHA256 сырого тела по вашему секрету), имя события — X-Echo-Event, номер доставки — X-Echo-Delivery.

Ответьте 2xx за 8 секунд. Иначе — повтор через 30 с, 2 мин, 10 мин и 1 ч с тем же id; редиректы не выполняются. Адрес — только https на 443 и публичный IP. После 20 неудач подряд отправка выключается — включите её в дашборде, когда приёмник заработает.

member.join

Участник зашёл на сервер.

{ "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

Участник вышел или его выгнали.

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

member.level_up

Участник поднял уровень.

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

store.purchase

Покупка на витрине сервера: роль выдана, пакет монет начислен (kind "coins", поле coins) или поддержка сервера. У анонимной поддержки покупателя нет.

{ "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

Открыт тикет.

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

account.linked

Игрок привязал аккаунт кодом.

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

test

Кнопка «Отправить тест» в дашборде → «Интеграции».

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

Проверка подписи — 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 часа. Несколько процессов используют одну таблицу.

// подпись считается от сырого тела, до разбора 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();
  }
});

Проверка подписи — PHP

<?php
$secret = getenv('ECHO_WEBHOOK_SECRET'); // whsec_… из панели
$guildId = getenv('ECHO_GUILD_ID');
if (!$secret || !$guildId) { http_response_code(500); exit; }
// подпись считается от сырого тела, до разбора 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);
}

Скоупы

При создании ключа выбираются права — каждый эндпоинт требует свой скоуп.

guild:read

Данные сервера

Базовая информация о сервере.

economy:read

Чтение экономики

Балансы: кошелёк, банк, фишки.

economy:write

Запись экономики

Начисление и списание валюты.

levels:read

Чтение уровней

Опыт и лидерборд участников.

monitoring:read

Чтение мониторинга

Пламя, место в топе, статусы каталога.

members:read

Чтение атрибутов

Чтение атрибутов участников по Discord ID и по ID во внешней системе — без права их менять.

members:write

Атрибуты участников

Передача атрибутов по Discord ID и по ID во внешней системе.

roles:write

Выдача ролей

Выдача и снятие ролей, разрешённых в кабинете разработчика → «Ключи API» → «Разрешено ключам».

links:read

Чтение привязок

Чей аккаунт: связь внешнего ID и Discord.

links:write

Коды привязки

Выпуск кодов привязки и отвязка аккаунтов.

levels:write

Запись опыта

Начисление и списание опыта; награды за уровень выдаёт бот.

messages:write

Сообщения от бота

Сообщения от имени бота в каналы, разрешённые в кабинете разработчика → «Ключи API» → «Разрешено ключам».

Лимиты и ошибки

До 3 (с Premium — 10) ключей на сервер, лимит — 40 (с Premium — 120) запросов в минуту на каждый ключ. Ошибки приходят как JSON { "error": "..." } с соответствующим HTTP-кодом.

Код	error	Когда
400	bad_fields	Неверные или недостающие параметры запроса.
401	unauthorized	Ключ не передан, неверен или отозван.
403	insufficient_scope	У ключа нет нужного скоупа для этого запроса.
403	key_paused_premium	Ключ на паузе: у сервера нет Premium, а без него работают только ключи в пределах бесплатного лимита, выпущенные раньше других.
404	not_linked	Аккаунт не привязан (методы привязок) или задание не найдено.
409	levels_off	Действие не подходит к настройкам сервера: например, уровни выключены.
413	body_too_large	Тело запроса больше 8 КБ.
429	rate_limited	Превышен лимит 40 (с Premium — 120) запросов в минуту.
502	discord_unavailable	Discord не ответил — повторите запрос позже.

Ключ виден целиком только один раз при создании — сохраните его. Администрация проекта может отключить ключ при злоупотреблении.