Полный цикл сбора через API

Все запросы ниже выполняются относительно /api/v1 с Bearer API-ключом, разрешающим запись. В примерах идентификаторы условные: заменяйте их значениями из ответов.

1. Создайте сайт

POST /sites

{"name":"Каталог товаров","base_url":"https://shop.example.invalid","rps":1,"concurrency":1}

name: название, base_url: полный URL с http:// или https://. Домен в примере намеренно нерабочий: укажите свой источник. Код сайт получает автоматически. При работе через API можно передать собственный code: строчные латинские буквы, цифры, _, -, до 64 символов.

Дополнительно можно задать render_mode, respect_robots, timeout_ms, proxy_pool_id, max_run_seconds, execution_target и agent_id. Настройки скорости действуют и при запуске через API. Код сайта после создания менять нельзя.

В запросе multipart/form-data можно передать необязательный файл icon (PNG, JPEG или WebP до 4 МБ). Платформа преобразует его в статичное изображение. Для замены значка созданного сайта используйте POST /sites/{site}/icon с тем же полем icon.

2. Создайте сценарий

POST /scripts

{"site_id":1,"code":"catalog-main","name":"Сбор каталога","entry":"run"}

Код сценария содержит строчные латинские буквы, цифры и дефис. Сохраните возвращённый id.

3. Сохраните и проверьте версию

POST /scripts/2/versions: передайте source с PHP-кодом и необязательный comment. Максимум исходника: 500 000 символов. Сохранение версии само по себе не означает публикацию и успешную проверку.

POST /scripts/2/validate проверяет исходник. GET /sandbox/sdk возвращает доступный контракт SDK. Написание алгоритмов, разрешённые методы и готовые примеры описаны в разделе SDK.

Запустите POST /script-versions/3/trial-run и проверьте журнал и полученные данные. Для публикации отправьте POST /scripts/2/publish с {"version_id":3}. Публикуйте только проверенную версию.

4. Запустите сбор

POST /runs

{"site_id":1,"script_id":2,"params":{}}

Ответ 202 означает постановку в очередь. Это ещё не завершённый сбор. Опросите GET /runs/{id} с интервалом 3–5 секунд. Журнал: GET /runs/{id}/log; запросы: /http-log; ошибки записей: /item-errors. После завершения прочитайте GET /sites/1/records.

Для отмены: POST /runs/{id}/cancel. Возобновление поддерживаемого прогона: /resume. Повтор по сохранённым ответам: /replay; отчёт: /replay-report. Повтор не всегда возможен после очистки снимков.

5. Настройте расписание

POST /schedules

{"script_id":2,"name":"Дважды в день","kind":"cron","timezone":"Europe/Moscow","preset":{"cron":"0 2,12 * * *"},"is_active":true}

Это 02:00 и 12:00 по Москве. Для полуночи используйте 0 0 * * *. Cron передаётся внутри preset, не отдельным полем. Другие виды: interval, daily, weekly, monthly. До сохранения можно проверить настройки через POST /schedules/preview.

Пауза: POST /schedules/{id}/pause; включение: /resume; внеочередной запуск: /run-now; история: GET /schedules/{id}/events. Расписание не гарантирует одновременный старт при занятом исполнителе или исчерпанном бюджете.

Защита от повторов

Универсального заголовка Idempotency-Key пока нет. При тайм-ауте запуска сначала проверьте последние прогоны: слепой повтор POST может создать второй запуск. Для обновления используйте PATCH существующего ресурса.