Інструменти програмою: ключ доступу та API

Усі перевірки розділу «Інструменти» доступні не тільки зі сторінки, а й із вашої програми: той самий розрахунок і той самий вигляд відповіді. Тут зібрано все, щоб почати за десять хвилин.

Як отримати ключ

1. Увійдіть у кабінет інструментів за кодом на пошту.
2. Ключ доступу входить у тариф «Профі». На безкоштовному й «Базовому» рівні ключа немає — спроба його випустити відповість TOOL_KEY_NOT_ALLOWED.
3. У розділі «Ключі доступу» натисніть «Створити ключ» і дайте йому ім’я — за ним ви впізнаєте ключ у списку.
4. Відкрите значення ключа показується один раз — у мить створення. Ми зберігаємо лише його відбиток, тому «показати ще раз» не можемо ні вам, ні собі. Скопіюйте ключ одразу. Загубили — відкличте старий і випустіть новий.

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

Ключів на тарифі «Профі» можна тримати п’ять. Відкликаний перестає працювати тієї ж миті.

Як передати ключ

Ключ іде заголовком Authorization зі словом Bearer:

Authorization: Bearer tlk_ВАШ_КЛЮЧ

Інші способи не працюють навмисно: Authorization: Basic …, порожній Bearer без значення або ключ без приставки tlk_ отримають 401 TOOL_KEY_INVALID. Тихо працювати гостем ми не станемо — інакше ви впиралися б у гостьові межі й читали це як випадкові відмови.

Ключ працює тільки на тому сайті, де його видано. Той самий ключ на адресі іншого сайту платформи відповідає 401 TOOL_KEY_INVALID — тим самим кодом, що й вигаданий ключ.

Заголовка немає зовсім — це не помилка: запит проходить як гостьовий, з гостьовими межами.

Перший запит

Одна перевірка — один запит POST. Адреса складається з виду інструмента:

POST https://seo-gen.com.ua/api/public/tools/<kind>/run

Повний приклад, який можна скопіювати й запустити (підставте свій ключ):

curl -X POST https://seo-gen.com.ua/api/public/tools/http-status-checker/run \
  -H "Authorization: Bearer tlk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com/"}'

У тілі запиту два поля: target — адреса, яку перевіряємо, і необов’язковий options — налаштування виду.

З чого складається відповідь

Успішна відповідь — 200 і два поля: data з результатом і limit із залишком обсягу. У прикладі нижче розділ headers прибрано, щоб не розтягувати сторінку — у живій відповіді він є.

{
  "data": {
    "kind": "http-status-checker",
    "target": "https://example.com/",
    "checkedAt": "2026-09-19T08:12:07.078Z",
    "cached": false,
    "verdict": "ok",
    "sections": [
      {
        "id": "summary",
        "rows": [
          { "status": 200, "final": "https://example.com/", "hops": 0, "time_ms": 95, "soft_404": "" }
        ],
        "columns": ["status", "final", "hops", "time_ms", "soft_404"]
      },
      { "id": "chain", "rows": [], "columns": ["step", "from", "to", "status", "scheme"] }
    ],
    "notes": []
  },
  "limit": { "remaining": null }
}

• data.kind — вид інструмента — той самий, що в адресі
• data.target — адреса, яку перевірили; null — у виду її немає
• data.checkedAt — час перевірки, ISO-8601 з часовим поясом
• data.cached — true — відповідь узята з нашого кешу (живе 10 хвилин); час при цьому залишається часом самої перевірки
• data.verdict — одне слово підсумку — перелік нижче
• data.sections — розділи результату: у кожного id, rows і columns — порядок колонок
• data.notes — коди застережень (не готовий текст): чому перевірили не все й що варто знати
• limit.remaining — скільки перевірок лишилось; null означає «межі немає»

Якщо розділ показано не повністю, у нього є capped з двома числами: скільки показано й скільки знайдено.

Слова підсумку

• ok — перевірили, біди не знайшли
• guess — визначили приблизно: відповідь тримається на одній слабкій ознаці
• partial — перевірили частково — частина не відбулася з НАШОЇ причини (наш строк, наша межа розміру, нас притримали за темпом). Числа «перевірено N із M» стоять у підсумку
• warn — є застереження
• unknown — визначити не вдалося: відповідь сайту розібрати не вийшло
• fail — знайшли поломку

Види інструментів і що їм передавати

Усі види нижче працюють за ключем. Стовпчик «Налаштування» — вміст поля options: у круглих дужках тип і значення за умовчанням, у квадратних — перелік допустимих значень.

Списки адрес і файли

Список адрес і обхід сайту йдуть у чергу: запит відповідає одразу, а результат забирається за посиланням.

curl -X POST https://seo-gen.com.ua/api/public/tools/http-status-checker/batch \
  -H "Authorization: Bearer tlk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"list":"https://example.com/\nhttps://example.com/nope\nне адрес"}'

У відповіді 202: номер завдання, посилання на нього, скільки адрес прийнято і перелік відхилених рядків одразу — з номером рядка й причиною.

{
  "data": {
    "id": "537f4024-0537-4abc-b564-56dc55569538",
    "url": "/api/public/tools/jobs/537f4024-0537-4abc-b564-56dc55569538",
    "accepted": 2,
    "rejected": [ { "code": "TARGET_INVALID", "line": 3, "value": "не адрес" } ],
    "status": "queued"
  },
  "limit": { "remaining": 4997 }
}

Список можна надіслати й файлом — multipart/form-data, поле file; підходять CSV, XLSX і TXT до 5 МБ:

curl -X POST https://seo-gen.com.ua/api/public/tools/http-status-checker/batch \
  -H "Authorization: Bearer tlk_ВАШ_КЛЮЧ" \
  -F "file=@spisok.csv"

Хід і результат — тим самим посиланням. Поле job.status проходить queued → running → done, а job.done і job.total показують поступ:

curl https://seo-gen.com.ua/api/public/tools/jobs/537f4024-0537-4abc-b564-56dc55569538 \
  -H "Authorization: Bearer tlk_ВАШ_КЛЮЧ"

Готовий результат вивантажується файлом — таблицею або JSON:

curl -OJ https://seo-gen.com.ua/api/public/tools/jobs/537f4024-0537-4abc-b564-56dc55569538/export.csv \
  -H "Authorization: Bearer tlk_ВАШ_КЛЮЧ"
curl -OJ https://seo-gen.com.ua/api/public/tools/jobs/537f4024-0537-4abc-b564-56dc55569538/export.json \
  -H "Authorization: Bearer tlk_ВАШ_КЛЮЧ"

Обхід сайту — той самий маршрут, але замість списку одна адреса й options.mode = "site". Скільки сторінок обійти, каже тариф.

Що вважається витратою

• Одна перевірка POST …/run — одна одиниця місячного обсягу тарифу й одне звернення за ключем.
• Список із N адрес — N одиниць обсягу: кожна адреса це окремий похід до чужого сайту.
• Обхід сайту — одна одиниця в мить постановки в чергу; скільки сторінок він пройде, обмежує тариф.
• Відповідь із кешу (cached: true) обсяг усе одно витрачає: обсяг рахує звернення, а не походи.
• Відмова через межу (QUOTA_EXCEEDED, API_QUOTA_EXCEEDED) приходить ДО роботи: рахувати чужий сайт і потім казати «не покладено» ми не станемо.
• Перегляд ходу завдання і вивантаження результату обсягу не витрачають.

Відмови

Відмова — це завжди тіло з двома полями: code машинним словом і error підписом мовою запиту (мову беремо із заголовка Accept-Language). Той самий код дублюється заголовком X-CMS-Error-Code.

Межі й увічливість до чужих сайтів

Межі тарифу «Профі»: 30 000 перевірок на місяць, 5 000 звернень за ключем на місяць, 5 000 адрес в одному списку, обхід до 50 000 сторінок, п’ять ключів, історія 365 днів. Скільки лишилось — у полі limit.remaining кожної відповіді.

Межі ввічливості до ЧУЖОГО сайту не знімає жоден тариф — вони не про того, хто платить, а про того, кого перевіряють:

• не більше двох одночасних запитів до одного хоста і пауза 500 мс між ними;
• чужу сторінку чекаємо 10 секунд, читаємо перші 5 МБ, ідемо не більше ніж по п’яти переадресаціях;
• на всю одиночну перевірку відведено 18 секунд: не встигли — відповідь приходить чесно частковою (partial), а не обірваною;
• представляємося іменем SeoGenCMS-Tools — за ним нас можна закрити у своєму robots.txt;
• одночасних завдань на сайт — два.

Перевіряйте чужі сайти з тією ж мірою, з якою хотіли б, щоб перевіряли ваш.