API Echo

Herkese açık REST API ve webhook’lar: sunucunun ekonomisini, seviyelerini ve sunucu listesi verilerini kendi hizmetlerine bağla — bir oyun sunucusuna, siteye, bota veya otomasyonlara.

https://api.echo-assistants.tech

Yetkilendirme Anahtar güvenliği Hizmet Ekonomi Seviyeler Sunucu listesi Entegrasyonlar Katalog Webhook’lar Entegrasyon bildirimleri Kapsamlar Sınırlar ve hatalar

Yetkilendirme

Her istek, Authorization başlığında bir anahtar gerektirir. Anahtar bir hesaba değil, sunucuya verilir. Anahtarı panelde → “Geliştiriciler” bölümünden yalnızca sunucu sahibi oluşturabilir: en fazla 3 (Premium ile 10) anahtar. /catalog/* uç noktaları herkese açıktır — anahtar gerekmez (IP başına 60/dk sınırı, yanıtlar önbelleğe alınır).

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

Anahtar oluştur

Anahtar güvenliği

Anahtar echoapi_ ile başlar, ardından 30 rastgele Latin harfi ve rakam, en sonda da 6 karakterlik sağlama toplamı gelir. Sağlama toplamı yanlış olan bir dizeyi API hemen reddeder (401). Eski biçimdeki anahtarlar (echo_…) çalışmaya devam eder; yeniden oluşturulan anahtar yeni biçimi alır.

Kendi kodunda anahtarları bulmak için kalıp

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

Herkese açık bir yerde görünen anahtar otomatik olarak devre dışı bırakılır. GitHub, Secret Scanning programı kapsamında herkese açık depolarda bulunan anahtarları bize bildirir; Echo botu da sunuculardaki mesajlarda anahtarları fark edip bu mesajları siler. Sunucu sahibi ve anahtarı oluşturan kişi sitede, Telegram’da ve e-postayla bildirim alır; bildirimde anahtarın bulunduğu yerin bağlantısı olur.

Ne yapmalı: geliştirici portalında sunucunun anahtarlarını aç ve anahtar kartında Yeniden oluştur butonuna bas. Anahtar yeni bir gizli değer alır ve yeniden çalışır; eskisi hemen çalışmaz hale gelir. Anahtarı kayıtlı olduğu her yerde değiştir. Bulunan bir anahtar yeniden oluşturulmadan etkinleştirilemez. Anahtara artık ihtiyacın yoksa iptal et.

Anahtarı kendi sunucunda tut — ortam değişkenlerinde veya bir gizli bilgi deposunda. Sayfa ya da uygulama koduna, depolara, mesajlara veya ekran görüntülerine koyma.

Hizmet

GET/mekapsamsız

Anahtar kontrolü: sunucuyu ve kapsamlarını döndürür.

Örnek

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

Yanıt

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

Ekonomi

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

Üye bakiyesi: cüzdan, banka, fişler.

Örnek

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

Yanıt

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

POST/economy/balanceeconomy:write

Para ekle veya düş. delta negatif olabilir; bakiye 0…2.000.000.000 aralığında kalır.

Örnek

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

İstek gövdesi

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

Yanıt

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

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

Bakiyeye göre en iyi üyeler (limit 1–100, varsayılan 20).

Örnek

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

Yanıt

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

Seviyeler

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

Deneyime göre en iyi üyeler (limit 1–100, varsayılan 20).

Örnek

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

Yanıt

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

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

Üyenin XP’si ve seviyesi; nextLevelXp, bir sonraki seviye için gereken toplam XP’dir.

Örnek

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

Yanıt

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

POST/levels/xplevels:write

XP ekle veya düş: delta bir tam sayıdır, istek başına en fazla ±1.000.000; XP sıfırın altına inmez. Seviye hemen yeniden hesaplanır. Seviye yükselirse bot, normal seviye atlamada olduğu gibi seviye ödüllerini (roller, coin, duyuru) verir ve "via": "api" işaretli member.level_up olayını gönderir. Seviye düşünce ödüller geri alınmaz. Yalnızca sunucu üyeleri için (aksi halde 404 not_member); sunucuda seviyeler kapalıysa — 409 levels_off.

Örnek

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

İstek gövdesi

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

Yanıt

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

Sunucu listesi

GET/monitoring/servermonitoring:read

Katalogdaki sunucu kartı: dönemdeki Alevler, toplam, sıralamadaki yeri ve durumlar.

Örnek

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

Yanıt

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

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

Alevlere göre katalogdaki en iyi sunucular (limit 1–100, varsayılan 20).

Örnek

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

Yanıt

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

Entegrasyonlar

Oyununu, siteni veya CRM’ini bağla: üye öznitelikleri panelde → “Entegrasyonlar” bölümündeki kurallara göre rollere dönüşür, oyuncular hesaplarını kodla bağlar ve izinli roller doğrudan verilebilir. Yazma istek gövdeleri en fazla 8 KB JSON olabilir.

PUT/members/<discordId>/attributesmembers:write

Üyenin özniteliklerini gönder (tamamen değiştirir): en fazla 25 alan, adlar Latin harfleri/rakamlar/_, değerler 100 karaktere kadar metin, sayı veya true/false. Bot, kurallara bağlı rolleri hemen yeniden hesaplar.

Örnek

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

İstek gövdesi

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

Yanıt

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

GET/members/<discordId>/attributesmembers:read

Üye için ne gönderildiği ve hangi harici hesabı bağladığı.

timedRoles — API için izinli rollerden süreli verilenler ve botun bunları ne zaman kaldıracağı.

Örnek

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

Yanıt

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

Üyenin tüm özniteliklerini temizle. Bot, kuralların verdiği rolleri kaldırır; elle verilen rollere dokunmaz.

Örnek

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

Yanıt

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

PUT/external/<externalId>/attributesmembers:write

Aynısı, senin sistemindeki ID ile (takma ad, UUID, license:…). Hesabı kodla bağlayan kişiye uygulanır; bağlanana kadar saklanır ve bağlandığında uygulanır. Ad çakışmalarında Discord ID ile gönderilen öznitelikler önceliklidir.

Örnek

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

İstek gövdesi

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

Yanıt

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

GET/external/<externalId>/attributesmembers:read

Harici hesap için ne gönderildiği ve onu kimin bağladığı (discordId: null — henüz kimse).

Örnek

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

Yanıt

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

DELETE/external/<externalId>/attributesmembers:write

Harici bir hesabın tüm özniteliklerini temizle.

Örnek

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

Yanıt

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

POST/link-codeslinks:write

Oyuncu için bağlantı kodu: 8 karakter, tek kullanımlık, ttlMinutes süresince geçerli (1–60, varsayılan 15). Oyuncu sunucu panelinde “Hesabı bağla” butonuna basar (veya /link kullanır) ve kodu girer. Aynı hesap için yeni kod, öncekini geçersiz kılar.

Örnek

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

İstek gövdesi

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

Yanıt

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

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

Kimin hesabı: externalId veya discordId ile (?discordId=…). Bağlantı yoksa — 404 not_linked.

Örnek

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

Yanıt

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

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

Hesap bağlantısını kaldır (veya ?discordId=…). Harici hesabın öznitelikleri artık o kişiye uygulanmaz.

Örnek

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

Yanıt

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

POST/members/<discordId>/rolesroles:write

Rolleri doğrudan ver ve kaldır — yalnızca sahibin geliştirici portalında → “API anahtarları” → “Anahtarlara izin verilenler” bölümünde işaretlediği roller (her listede en fazla 10). remove, elle verilmiş olsa bile izinli herhangi bir rolü kaldırır. İşlemi bot yapar: yanıt olarak görev numarasıyla 202 döner.

durationMinutes (1–525.600) — add içindeki rolleri belirli bir süre için verir: süre dolunca bot rolleri kendisi kaldırır. Süre, önceden belirlenmiş bir süreyi kısaltmaz; üyede zaten süresiz olan rol kalıcı kalır. durationMinutes olmadan add rolü kalıcı yapar, remove planlanmış kaldırmayı iptal eder.

Örnek

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

İstek gövdesi

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

Yanıt

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

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

Rol verme görevinin sonucu: pending, done veya failed ve her rolde ne olduğu.

Süreli rol vermede result.expiresAt, botun verilen her rolü ne zaman kaldıracağını gösterir (null — rol üyede zaten süresiz vardı ve kalıcı kalır).

Örnek

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

Yanıt

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

Bot adına mesaj (bağlıysa sunucunun kendi botu) — yalnızca sahibin geliştirici portalında → “API anahtarları” → “Anahtarlara izin verilenler” bölümünde işaretlediği kanallara (en fazla 10). content — en fazla 2000 karakter, embeds — en fazla 10 basit embed: title, description, url, color, timestamp, author.name, footer.text, image.url, thumbnail.url, fields; bağlantılar yalnızca https. Bahsetmeler varsayılan olarak kimseyi çağırmaz: yalnızca mentionUsers listesindeki sunucu üyeleri (en fazla 10) çağrılabilir, @everyone, @here ve roller asla. İstek gövdesi — en fazla 32 KB. İşlemi bot yapar: yanıt olarak görev numarasıyla 202 döner.

Örnek

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

İstek gövdesi

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

Yanıt

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

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

Gönderimin sonucu: pending, done (mesaj id’si ve bağlantısı) veya nedeniyle birlikte failed: channel_not_allowed, channel_missing, missing_permissions, rejected.

Örnek

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

Yanıt

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

Katalog

GET/catalog/servers?search=&tag=&lang=&limit=herkese açık · anahtarsız

Sunucu listesi kataloğunda arama ve sunucu listeleme. Tamamen herkese açık — anahtar gerekmez.

Örnek

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

Yanıt

{ "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>herkese açık · anahtarsız

Alevlere göre katalog sıralaması.

Örnek

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

Yanıt

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

GET/catalog/server/<slug>herkese açık · anahtarsız

Herkese açık sunucu kartı: açıklama, Alevler, sıra, etiketler, rozetler, davet, puan.

Örnek

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

Yanıt

{ "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>herkese açık · anahtarsız

Ortalama puanla birlikte sunucu yorumları.

Örnek

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

Yanıt

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

GET/catalog/tagsherkese açık · anahtarsız

Sunucu sayılarıyla birlikte katalog etiketleri/kategorileri.

Örnek

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

Yanıt

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

Webhook’lar

Echo, olayları gerçek zamanlı olarak belirttiğin URL’ye gönderir. Webhook’u panelde → “Geliştiriciler” bölümünden kur. Her istek X-Echo-Signature başlığıyla imzalanır (gövdeden gizli anahtarınla hesaplanan HMAC-SHA256); olay adı X-Echo-Event içinde yer alır.

flame.bump

Sunucuya katalogda ya da /flame ile Alev verildi.

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

test

“Test gönder” butonuyla gönderilir — alıcının çalıştığını kontrol etmek için.

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

İmza doğrulama

import crypto from "node:crypto";

// body ham istek metnidir, secret panelden alınır
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);

Entegrasyon bildirimleri (Premium)

Panelde → “Entegrasyonlar” bölümünden ayarlanır. Echo JSON ile POST gönderir {"id", "event", "guildId", "at", "data"}: imza — X-Echo-Signature (sha256= ve ham gövdeden gizli anahtarınla hesaplanan HMAC-SHA256), olay adı — X-Echo-Event, teslimat numarası — X-Echo-Delivery.

8 saniye içinde 2xx ile yanıt ver. Aksi halde aynı id ile 30 sn, 2 dk, 10 dk ve 1 sa sonra yeniden deneriz; yönlendirmeler izlenmez. Adres yalnızca 443 portunda ve herkese açık IP’de https olmalıdır. Art arda 20 başarısızlıktan sonra gönderim kapanır — alıcın çalışır hale gelince panelden yeniden aç.

member.join

Bir üye sunucuya katıldı.

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

Bir üye ayrıldı veya atıldı.

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

member.level_up

Bir üye seviye atladı.

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

store.purchase

Sunucu vitrininde bir satın alma: rol verildi, coin paketi yüklendi (kind "coins", coins alanı) veya sunucuya destek. Anonim desteklerde alıcı yoktur.

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

Bir destek talebi açıldı.

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

account.linked

Bir oyuncu hesabını kodla bağladı.

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

test

Panelde → “Entegrasyonlar” bölümündeki “Test gönder” butonu.

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

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

// imza, JSON ayrıştırılmadan önce ham gövde üzerinden hesaplanır
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();
  }
});

İmza kontrolü — PHP

<?php
$secret = getenv('ECHO_WEBHOOK_SECRET'); // whsec_… из панели
$guildId = getenv('ECHO_GUILD_ID');
if (!$secret || !$guildId) { http_response_code(500); exit; }
// imza, JSON ayrıştırılmadan önce ham gövde üzerinden hesaplanır
$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);
}

Kapsamlar

Anahtar oluştururken izinleri seçersin — her uç nokta kendi kapsamını gerektirir.

guild:read

Sunucu verileri

Sunucu hakkında temel bilgiler.

economy:read

Ekonomiyi okuma

Bakiyeler: cüzdan, banka, fişler.

economy:write

Ekonomiye yazma

Para ekleme ve düşme.

levels:read

Seviyeleri okuma

Deneyim ve üye sıralaması.

monitoring:read

Sunucu listesini okuma

Alevler, sıralamadaki yer, katalog durumları.

members:read

Öznitelikleri okuma

Üye özniteliklerini Discord ID’ye ve harici sistemdeki ID’ye göre okuma — değiştirme hakkı olmadan.

members:write

Üye öznitelikleri

Discord ID ve harici sistemdeki ID üzerinden öznitelik gönderme.

roles:write

Rol verme

Geliştirici portalında → “API anahtarları” → “Anahtarlara izin verilenler” bölümünde izin verilen rolleri verme ve kaldırma.

links:read

Bağlantıları okuma

Kimin hesabı: harici ID ↔ Discord bağlantısı.

links:write

Bağlantı kodları

Bağlantı kodları oluşturma ve hesap bağlantılarını kaldırma.

levels:write

XP yazma

XP ekleme ve düşme; seviye ödüllerini bot verir.

messages:write

Bot mesajları

Geliştirici portalında → “API anahtarları” → “Anahtarlara izin verilenler” bölümünde izin verilen kanallara bot adına mesajlar.

Sınırlar ve hatalar

Sunucu başına en fazla 3 (Premium ile 10) anahtar; her anahtar için dakikada 40 (Premium ile 120) istek sınırı. Hatalar, ilgili HTTP koduyla birlikte JSON { "error": "..." } olarak döner.

Kod	error	Ne zaman
400	bad_fields	Geçersiz veya eksik istek parametreleri.
401	unauthorized	Anahtar gönderilmedi, geçersiz veya iptal edilmiş.
403	insufficient_scope	Anahtarda bu istek için gereken kapsam yok.
403	key_paused_premium	Anahtar duraklatıldı: sunucuda Premium yok ve Premium olmadan yalnızca ücretsiz sınır içinde ilk oluşturulan anahtarlar çalışır.
404	not_linked	Hesap bağlı değil (bağlantı yöntemleri) veya görev bulunamadı.
409	levels_off	İşlem sunucu ayarlarına uymuyor: örneğin seviyeler kapalı.
413	body_too_large	İstek gövdesi 8 KB sınırını aşıyor.
429	rate_limited	Dakikada 40 (Premium ile 120) istek sınırı aşıldı.
502	discord_unavailable	Discord yanıt vermedi — isteği daha sonra tekrarla.

Anahtar yalnızca oluşturulduğunda bir kez tam olarak gösterilir — onu kaydet. Proje yönetimi, kötüye kullanım durumunda bir anahtarı devre dışı bırakabilir.