Публічний API: ключі, права та сценарії
Публічний API дозволяє керувати просуванням зі своєї системи: створювати проекти, додавати сторінки, запускати каскади, отримувати звіти, а також працювати з перевіркою позицій, аудитами та сканами безпеки.
Документація
Повний справочник з параметрами та прикладами запитів живе на окремій сторінці і завжди відповідає поточній версії. Тут — тільки загальна картина.
Ключі та права
- Ключ випускається в кабінеті, в розділі «API для розробників», і передається в заголовку авторизації.
- У ключа є скоупи — набори прав. Їх чотири: просування (promotion), позиції (rank), аудити (audit), безпека (shield). Видавайте тільки те, що дійсно потрібно.
- Ключ можна відкликати в будь-який момент, старі запити з ним відразу перестануть працювати.
- Діє обмеження на частоту запитів; в кабінеті видна статистика викликів та витрат по ключу.
Що доступно через API
| Група | Можливості | Скоуп |
|---|---|---|
| Аккаунт | Профіль, баланс, персональна знижка, відомості про ключ | не потрібно |
| Проекти та посилання | Створення проектів, додавання та видалення сторінок | promotion |
| Просування | Тарифи, попередній розрахунок, запуск каскаду, статус і список розміщень | promotion |
| Звіти та бренд | Звіт у JSON або PDF, налаштування white-label (тільки Pro) | promotion |
| Rank Tracker | Проекти, ключові слова, постановка перевірки позицій | rank |
| SEO Audit | Оцінка розміру сайту, експрес та повний обхід, підсумки з Health Score | audit |
| Shield | Підтвердження домену, запуск сканів, вердикт | shield |
Брендування звітів — не окремий скоуп: воно входить у promotion і вимагає активної підписки Pro.
Типовий сценарій
- Створити проект і додати в нього сторінки.
- Запросити розрахунок вартості для потрібної конфігурації каскаду.
- Запустити просування і зберегти ідентифікатор запуску.
- Періодично запитувати статус, а по завершенні — звіт з публікаціями.
Попередній розрахунок повертає суму зі знижкою та поточний баланс, тому ціну можна показати до списання; як вона влаштована — в статті тарифи та ціна. Звіт віддає тільки підтверджені розміщення, як у кабінеті: значення статусів розібрані в статті звіт і статуси.
Ліміти та коди відповідей
| Ситуація | Відповідь | Що робити |
|---|---|---|
| Ключ не передано, не знайдено або відкликано | 401 | Перевірити заголовок авторизації та сам ключ |
| У ключа немає потрібного скоупа | 403 | Випустити ключ з потрібними правами |
| Не вистачає грошей на запуск | 402 | В відповіді прийдуть потрібна сума, баланс, нестача та посилання на поповнення |
| Помилка в параметрах або чужий домен посилання | 422 | Поле з помилкою вказано в відповіді |
| Занадто багато запитів | 429 | Повторити через число секунд з відповіді; ліміт вважається на ключ |
| Сервіс тимчасово вимкнений | 503 | Повторити пізніше: запуск не відбувся, гроші не списані |
Списки повертаються по сторінках — не більше 100 елементів на сторінку. Повний перелік кодів є в справочнику.
Часті помилки інтеграції
- Повторний запуск тієї ж посилання. Поки по ній йде активний каскад, новий не створюється — в відповіді прийде ознака «вже активен». Це не збій, повторювати запит циклом не потрібно.
- Повний аудит без експреса, скан Shield без підтвердження домену. Обидві дії вимагають підготовчого кроку, інакше повернеться помилка.
- Занадто частий опит статусу. Каскад йде годинами: частіше разу в кілька хвилин запитувати сенсу немає, а в ліміт частоти впертися легко.
- Пустий баланс в момент запуску. Попередній розрахунок міг пройти вчора, а гроші піти на інші запуски — тримайте запас, см. баланс і поповнення.
White-label по API
Підписники Pro можуть задати логотип, назву компанії та колір — тоді звіти, отримані через API, будуть оформлені під ваш бренд. Детальніше в статті про White-label.
Сервер зберігає тільки хеш ключа, показати випущений ключ ще раз неможливо — збережіть його одразу. Втратили або засвітили в репозиторії: відкличте старий і випустіть новий, на вже запущені каскади це не вплине.