Зовнішній API

Як це працює (в двох словах)

Це API нічого нікому не надсилає само — ти сам питаєш, коли тобі треба. Найпоширеніший сценарій: людина на твоєму Discord-сервері викликає команду (наприклад /claim), твій бот у цей момент і робить один запит сюди, щоб перевірити "чи ця людина сьогодні бампала", і сам вирішує, видавати нагороду чи ні. uacord лише звітує факти — хто й коли бампав або лишив відгук — уся логіка нагород (скільки монет, як не видати двічі) на твоєму боці.

Людині НЕ треба заходити на сайт чи логінитись, щоб її бамп/відгук тут з'явився — досить того, що вона зробила це на Discord-сервері.

Endpoint

GET https://<домен>/api/external/server

Один-єдиний endpoint для всього. Сервер визначається самим ключем — ID чи slug у URL вказувати не треба.

Авторизація

Ключ передається в заголовку кожного запиту:

X-API-Key: ваш_api_ключ

Query-параметри

За замовчуванням повертаються тільки базові поля (назва, рейтинг тощо). Кожен додатковий масив запитується явно, інакше його просто не буде у відповіді — це економить і твій, і наш час на запит:

• votes_today=true — бампи за сьогодні
• votes_month=true — бампи за поточний календарний місяць
• votes_prev_month=true — бампи за попередній місяць
• votes_all=true — усі бампи за весь час
• comments=true — відгуки (без відповідей власника)
• discord_id=<ID> — необов'язково: обмежує ВСІ масиви вище лише одним Discord ID. Зручно для команд типу "отримати нагороду" — один запит, щоб перевірити, чи саме ЦЯ людина голосувала сьогодні, замість вивантаження й пошуку у всьому списку.

Параметри можна комбінувати, наприклад:

?votes_today=true&comments=true&discord_id=123456789012345678

Приклад запиту (curl)

curl "https://<домен>/api/external/server?votes_today=true" \
  -H "X-API-Key: твій_ключ"

Приклад відповіді

{
  "id": "622648180787...",        // Discord Guild ID цього сервера — окремого внутрішнього ID немає
  "slug": "my-server",
  "name": "My Server",
  "rating": 4.8,
  "created_at": "2024-01-15T10:30:00.000Z",

  // з'являється тільки якщо додав ?votes_today=true
  "votes_today": [
    {
      "user_id": "123456789012345678",   // Discord ID того, хто бампнув
      "user_nickname": "PlayerName",
      "created_at": "2025-03-18T09:00:00.000Z"
    }
  ],

  // з'являється тільки якщо додав ?comments=true
  "comments": [
    {
      "user_id": "123456789012345678",
      "user_nickname": "PlayerName",
      "rating": 5,
      "text": "Класний сервер!",
      "created_at": "2025-03-10T14:00:00.000Z"
    }
  ]
}

Приклад: видати нагороду конкретній людині (discord.js)

Найпростіший і найнадійніший спосіб — перевіряти в момент, коли людина сама просить нагороду:

// Discord.js: команда "/claim" — видає монети, якщо людина
// бампнула сьогодні. Discord ID беремо прямо з interaction —
// не треба, щоб людина була залогінена на сайті.
async function handleClaim(interaction) {
  const res = await fetch(
    `https://<домен>/api/external/server?votes_today=true&discord_id=${interaction.user.id}`,
    { headers: { "X-API-Key": process.env.UACORD_API_KEY } }
  );
  const data = await res.json();

  if (data.votes_today && data.votes_today.length > 0) {
    // ця людина бампала сьогодні — видаємо монети
    await giveCoins(interaction.user.id, 100);
    await interaction.reply("Отримано 100 монет за бамп!");
  } else {
    await interaction.reply("Ти ще не бампав сьогодні.");
  }
}

Приклад: нагородити всіх одразу (без discord_id)

Альтернатива — раз на день пройтись по всіх, хто бампав, і видати нагороду масово. У цьому випадку захист від подвійної видачі — повністю твоя відповідальність, uacord не знає, кому вже видано:

// Періодична задача раз на день: видати монети ВСІМ, хто бампав
// сьогодні, за один запит (без discord_id — повертає весь список).
async function rewardAllTodayBumpers() {
  const res = await fetch(
    "https://<домен>/api/external/server?votes_today=true",
    { headers: { "X-API-Key": process.env.UACORD_API_KEY } }
  );
  const { votes_today } = await res.json();

  for (const vote of votes_today) {
    // свій бот сам стежить, кому вже видавав сьогодні, щоб не задвоїти
    if (!alreadyRewardedToday(vote.user_id)) {
      await giveCoins(vote.user_id, 100);
      markRewardedToday(vote.user_id);
    }
  }
}

Обмеження та ліміти

• До 15 запитів на хвилину на один ключ (адмін сайту може змінити цей ліміт).
• Ключ можна перегенерувати чи прибрати в будь-який момент у налаштуваннях сервера — старий одразу перестає працювати.
• Якщо буст, що давав доступ до API, закінчився — ключ не видаляється, просто перестає відповідати (403), і одразу оживає, якщо буст поновити.

Коди помилок

• 403 — ключ відсутній, невірний, або зовнішній API не увімкнений для цього сервера
• 429 — перевищено ліміт запитів за хвилину