API Ключі для адмінів та модераторів

Це документація старого API. Він лишається робочим для наявних інтеграцій і не змінюється, але нові проєкти мають користуватись новим API — довідник /api/v1/.

Вступ

API ключі дозволяють автоматизувати роботу з перекладами без веб-інтерфейсу. Через один і той самий ключ доступні 3 типи запитів:

• user_translate_text — створення/оновлення пропозиції перекладу
• ai_translated_text — запис у поле ai_translated_text
• show_info — отримання повної інформації по рядку перекладу

Для кого доступні

API ключі доступні тільки для ролей:

• Super Admin
• Admin
• Moderator

Обмеження

• Максимум 1 API ключ на користувача
• Ключі безстрокові (без терміну дії)
• Є окремі ліміти на ключ:
  • для user_translate_text
  • для ai_translated_text
  • для show_info
• Базове значення ліміту для кожного типу: 10 000 (можна змінити в /admin/settings)
• Є загальний історичний лічильник запитів по користувачу (усі ключі, всі типи запитів)

Створення API ключа

1. Увійдіть в особистий кабінет (/admin/profile)
2. Відкрийте секцію "API ключ"
3. Натисніть "Створити новий ключ"
4. (Опціонально) вкажіть назву ключа
5. Збережіть ключ

Формат API ключа

wwm_ + 60 hex-символів (64 символи загалом)

Endpoint

• URL: https://winds4ua.com.ua/api/translations-api.php
• Метод: POST
• Content-Type: application/json
• Авторизація: заголовок X-API-Key

---

Режим 1: Пропозиція перекладу (user_translate_text)

Параметри

• action (опціонально): "propose" (за замовчуванням)
• row_id (обов'язково): ID рядка (16 символів)
• user_translate_text (обов'язково): текст перекладу
• ignore_glossary_warnings (опціонально, тільки moderator/admin/super_admin)
• ignore_validation_errors (опціонально, тільки moderator/admin/super_admin)

Приклад

curl -X POST https://winds4ua.com.ua/api/translations-api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "action": "propose",
    "row_id": "0000000000000001",
    "user_translate_text": "Перекладений текст"
  }'

---

Режим 2: Запис у ai_translated_text

Параметри

• action (опціонально): "update_ai_translated_text"
• update_ai_translated_text (опціонально, boolean): true (дозволяє ввімкнути режим через додатковий параметр)
• row_id (обов'язково): ID рядка (16 символів)
• ai_translated_text (обов'язково): текст для поля ai_translated_text
• overwrite_ai_translated_text (опціонально, boolean):
  • false (за замовчуванням): запис тільки якщо поле в БД порожнє
  • true: примусовий перезапис
• provider (опціонально, рядок до 128 символів): хто зробив переклад — напр. openai, deepseek, opencode. Варто передавати, щоб у ревізії було видно провайдера; без нього працює як раніше
• model (опціонально, рядок до 128 символів): назва моделі, якою зроблено переклад. Так само необов'язкова

Без provider і model запит працює точно як раніше. Якщо передати їх довшими за 128 символів — 400 із текстом provider і model — до 128 символів.

Пишіть їх за єдиним правилом — так само, як у новому API (довідник, підрозділ «Як заповнювати provider і model»):

• provider — хто віддає модель: лише малі латинські літери, цифри й дефіс, без пробілів і версій (openai, anthropic, google, deepseek, mistral, openrouter, opencode, ollama…).
• model — точний ідентифікатор моделі з API провайдера, разом із версією (gpt-4.1-mini, claude-sonnet-4-5, deepseek-chat, gemini-2.5-flash).
• Одна й та сама модель завжди пишеться однаково — інакше статистика рахує різні написання як різні моделі. Сервер лише обрізає пробіли на краях.

Приклад (без перезапису)

curl -X POST https://winds4ua.com.ua/api/translations-api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "action": "update_ai_translated_text",
    "row_id": "0000000000000001",
    "ai_translated_text": "AI переклад"
  }'

Приклад (з перезаписом)

curl -X POST https://winds4ua.com.ua/api/translations-api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "action": "update_ai_translated_text",
    "row_id": "0000000000000001",
    "ai_translated_text": "Оновлений AI переклад",
    "overwrite_ai_translated_text": true
  }'

---

Режим 3: Отримання інформації (show_info)

Параметри

• action (опціонально): "show_info"
• show_info (опціонально, boolean): true
• show-info (опціонально, boolean): true (альтернативний формат)
• row_id (обов'язково): ID рядка (16 символів)

Що повертає

• original_text
• ai_translated_text
• translated_text
• ref_chinese_text
• статуси заповненості/збереження полів
• approved_proposal
• proposals_summary (pending, approved, rejected, total)
• proposals (всі пропозиції по row_id зі статусами)

Для рядка, що є в diff-файлі гри, original_text і ref_chinese_text — текст diff, а file_name/number — рядка diff; форма відповіді не змінилась.

Приклад

curl -X POST https://winds4ua.com.ua/api/translations-api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_api_ключ" \
  -d '{
    "action": "show_info",
    "row_id": "0000000000000001"
  }'

---

Основні коди відповідей

• 200 — успіх
• 400 — невалідні параметри
• 401 — відсутній/невалідний API ключ
• 403 — недостатньо прав
• 404 — рядок не знайдено
• 409 — ai_translated_text вже заповнене (і overwrite_ai_translated_text=false)
• 422 — помилки валідації (для user_translate_text)
• 429 — перевищено ліміт запитів для відповідного типу (user_translate_text, ai_translated_text, show_info)

Валідація

Для user_translate_text виконується повна валідація (структура, теги, глосарій). Для ai_translated_text виконується перевірка обов'язкових параметрів, існування row_id та правила overwrite. Для show_info виконується перевірка ключа, ліміту типу show_info та існування row_id.

Як відстежити використання API ключа?

В особистому кабінеті відображається:

• Дата створення ключа
• Останнє використання

Якщо ключ ніколи не використовувався - відображається "Ніколи не використовувався".

Рекомендації з безпеки

1. Зберігайте ключі в безпечному місці

   • Не зберігайте ключі в публічних репозиторіях
   • Використовуйте змінні середовища або конфігураційні файли з обмеженим доступом

2. Регулярно перевіряйте використання

   • Перевіряйте "Останнє використання" в особистому кабінеті
   • Якщо виявлено підозрілу активність - регенеруйте ключ

3. Використовуйте HTTPS

   • Завжди використовуйте HTTPS для передачі API ключів
   • Не передавайте ключі через незашифровані з'єднання

4. Обмежте доступ до ключів

   • Не діліться ключами з іншими користувачами
   • Якщо ключ скомпрометовано - негайно видаліть або регенеруйте його