API съёма позиций — полная документация
Версия сервиса: 19.11.2026. Адрес: https://async-xml.com.
Личный кабинет: https://async-xml.com/panel.html. JSON передаётся в UTF-8.
Все методы /v1/* требуют Authorization: Bearer API_KEY.
В примерах API_KEY — ваш ключ нашего сервиса, не ключ Capsola.
Мобильный режим
Новые проверки выполняются как мобильные: Chromium с профилем Pixel 7,
мобильными User-Agent, viewport и touch. Даже если старый клиент передаст
device: "desktop", API заменит его на mobile до создания задания.
Фактическое устройство возвращается в check.device.
Уже сохранённые результаты и ранее созданные задания не переименовываются.
Для нового мобильного съёма используйте новый Idempotency-Key.
Политика доступна в /v1/limits и /v1/status: device_policy: mobile_only.
Администратор может вернуть выбор устройства настройкой
YANDEX_LIVE_FORCE_MOBILE=0 и перезапуском.
Проверки позиций
Объект проверки:
{"domain":"аппгрейд.рф","query":"магазин айфонов белорецк","region":20259,"device":"mobile","pages":10}
domain: домен без протокола, пути и порта. Кириллица принимается; нормализованный домен в ответе — Punycode. Поддомены учитываются.query: непустая фраза, 1–500 символов.region: код региона Яндекса, целое от 1; по умолчанию 213 (Москва). 64 — Кемерово, 20259 — Белорецк.device: mobile по умолчанию; действующая политика принудительно mobile.pages: 1–10, по умолчанию 1.
Все перечисленные POST по умолчанию сразу возвращают HTTP 202 с job_id, прогрессом, status_url, results_url и partial_url. Они не ждут окончания съёма. Готовые строки получайте через partial_url; полный результат — через results_url.
| Метод | Тело | Форма полного результата /results |
|---|---|---|
| POST /v1/check | Объект проверки | Один результат |
| POST /v1/checks | {"checks":[объект,...]} |
Массив, порядок входа |
| POST /v1/checks/domains | Объект ниже | Массив: для каждой фразы все домены |
| POST /v1/jobs | {"checks":[объект,...]} |
Всегда создаёт/возвращает асинхронное задание HTTP 202 |
Пакет: 1–1000 проверок. Для нескольких доменов:
{"domains":["example.org","example.net"],"queries":["первая фраза","вторая фраза"],"region":213,"device":"mobile","pages":10}
До 10 доменов и 100 фраз; создаётся декартово произведение. Повторы доменов и фраз в этом методе удаляются. Промо, реклама, рекламные редиректы и дополнительные ссылки не увеличивают органическую позицию. Рекламное размещение проверяемого домена тоже исключается. Позиция считается среди распознанных органических результатов; страницы могут содержать разное число результатов. 10 страниц не гарантируют 100 мест. Выдача зависит от региона, устройства, времени и персонализации.
Пример структуры результата (числа условные):
{"check":{"domain":"example.org","query":"фраза","region":213,"device":"mobile","pages":10},"status":"found","position":3,"url":"https://example.org/","pages_scanned":1,"results_scanned":10,"detail":null,"diagnostics":[],"attempts":2,"passes":1,"error_code":null,"captcha_task_id":null,"visual_captcha_solved":false,"connection_mode":"proxy","elapsed_ms":12000,"queue_ms":200,"retry_after_seconds":null}
found — домен найден, position и url заполнены.
not_found — домена нет в успешно просмотренной глубине, position/url равны null.
blocked/error — промежуточные сбои; новые задания автоматически доснимают
такие ключи и не выдают их как завершённый полный результат.
pages_scanned, results_scanned — реально разобранные страницы/органические результаты.
attempts, passes — суммарные попытки и проходы восстановления.
elapsed_ms, queue_ms — длительность обработки и очередь в миллисекундах.
error_code, detail, diagnostics — диагностические сведения.
captcha_task_id — номер/UUID задачи распознавания, когда создавалась.
visual_captcha_solved true только после решения визуальной задачи и получения
выдачи; прохождение одного чекбокса не считается визуальным решением.
connection_mode — фактически proxy или direct.
retry_after_seconds — подсказка для повторов при временном сбое.
Автоматический досъём и очередь
На текущем сервере одновременно работают 3 проверки, остальные стоят в очереди. Ограничение снижено с 10 из-за перегрузки одного CPU и 2 ГБ памяти. Пакеты до 10 доменов по-прежнему принимаются; актуальное число работников — /v1/limits. Готовые результаты сохраняются в SQLite и повторно не снимаются. Неудачные ключи перепроверяются автоматически с новым подключением к прокси. При IP-блокировке подключение меняется. Для постоянных сетевых сбоев действует ограниченная пауза до 30 секунд: мгновенное завершение при блокировке не гарантируется. На текущем сервере на активную попытку выделяется до 45 секунд плюс 15 за каждую дополнительную страницу (до 180 секунд); бюджет прохода — 240 секунд. Это предельные тайм-ауты, успешные операции завершаются сразу. Общего конечного лимита восстановления нет. Отключение HTTP-клиента и перезапуск API не отменяют сохранённое задание.
Асинхронный режим включён по умолчанию для всех POST-методов проверки.
Заголовок Prefer: respond-async необязателен.
curl -X POST https://async-xml.com/v1/jobs \
-H 'Authorization: Bearer API_KEY' -H 'Content-Type: application/json' \
-H 'Idempotency-Key: project-1-scan-20261119-mobile' \
-d '{"checks":[{"domain":"example.org","query":"фраза","region":213,"device":"mobile","pages":10}]}'
Ответ HTTP 202 содержит job_id, status, total, completed, pending,
status_url и results_url, а также другие счётчики состояния.
Заголовки: X-Job-ID, Location (адрес результатов), Retry-After (секунды).
Опрос: GET /v1/jobs/JOB_ID/results с тем же Bearer-ключом.
HTTP 202 — продолжать опрос по Retry-After; HTTP 200 — сохранить полный ответ.
Для /v1/jobs ответ — массив; для задания от /v1/check — объект.
POST без Prefer не держит соединение до окончания проверки. Для старой
интеграции можно явно передать Prefer: respond-sync на /v1/check,
/v1/checks или /v1/checks/domains: только тогда ответ HTTP 200 ожидается до
полного завершения. /v1/jobs всегда асинхронный. Для пользовательского
интерфейса используйте немедленный HTTP 202 и опрос /partial.
| Метод | Назначение |
|---|---|
| GET /v1/jobs | Последние 25 заданий своего аккаунта, объект с массивом jobs |
| GET /v1/jobs/JOB_ID | Состояние задания |
| GET /v1/jobs/JOB_ID/results | 202 пока не готово, 200 полный результат |
| GET /v1/jobs/JOB_ID/partial | Готовые строки и прогресс, не дожидаясь пакета |
| DELETE /v1/jobs/JOB_ID | Отменить дальнейшую обработку |
Статусы: running, completed, waiting_configuration, cancelled. Чужой/неизвестный job_id — 404. Результаты отменённого задания — 409.
Показывать готовые позиции сразу
GET /v1/jobs/JOB_ID/partial возвращает HTTP 200 и объект:
{"job_id":"JOB_ID","status":"running","total":105,"completed":1,"pending":104,"complete":false,"results":[{"index":2,"result":{"check":{"domain":"example.org","query":"третья фраза","region":213,"device":"mobile","pages":10},"status":"found","position":13,"url":"https://example.org/","pages_scanned":2,"results_scanned":13,"diagnostics":[]}}]}
Пример сокращён; значения условные. index — исходный индекс проверки с нуля.
В results присутствуют только законченные found/not_found; ошибки и блокировки
не превращаются в позиции. Ответ — полный текущий набор готовых строк, а не
дельта: обновляйте ячейки по index, не добавляйте повторные строки.
Индексы могут приходить не по порядку: третья фраза может завершиться раньше первой.
complete=false при HTTP 200 означает, что пакет ещё выполняется.
Пустой results означает отсутствие готовых строк на данный момент.
diagnostics здесь пустой ради компактного опроса; полная диагностика — в /results.
Опрос по Retry-After (обычно 2 секунды, 60 при waiting_configuration).
При cancelled прекратите опрос; уже готовые строки остаются доступны для чтения.
Метод использует тот же лимит 120 запросов/мин и доступ только к своему заданию.
Существующие клиенты /results по-прежнему ждут весь пакет. Чтобы ячейки обновлялись постепенно, интеграция клиента должна читать /partial и сохранять result по исходному index. Готовый пример: examples/progressive_client.py. Это не запускает повторный съём и не меняет ранее сохранённые результаты. При неверном ключе Capsola, нулевом балансе, запрете IP или отключённом распознавании задание ожидает настройки: waiting_configuration. Только явно синхронный POST (Prefer: respond-sync) возвращает 503 с job_id; обычный POST сразу даёт 202, опрос полного результата тоже 202 до готовности. Проверка восстановления раз в минуту, готовые строки сохраняются. Уведомления о таких сбоях, проблемах прокси и прочих ошибках идут владельцу в Telegram. Повторные ошибки досъёма объединяются в сводку по заданию раз в 15 минут; ошибка доступа/баланса уведомляется отдельно. Сводка содержит готово/всего, остаток и короткий хеш ключевой фразы. Счётчик попыток относится к одной фразе. Сообщение о восстановлении прокси отправляется после получения выдачи, а не капчи/429. При сетевой недоступности прокси разрешён прямой резервный режим; факт виден в connection_mode. Telegram отправляется напрямую.
Idempotency-Key: 1–200 символов, один стабильный ключ на один съём. Повтор того же POST с тем же ключом не создаёт дубль, включая готовый съём. Другие параметры под тем же ключом — 409. Для нового съёма нужен новый ключ. Без заголовка одинаковые активные задания объединяются, после завершения следующий POST создаёт новый съём. Не создавайте новый POST на каждый HTTP 202.
Статистика и состояние
GET /v1/stats: total, successful, found, not_found, blocked, errors, attempts, pages_scanned, success_rate (проценты). successful = found + not_found: корректное отсутствие тоже успешная проверка. Завершённый ключ нового задания записывается один раз, атомарно с результатом. Историческая статистика может содержать blocked/error старых запусков.
GET /v1/stats/sites: объект sites (массив) и unattributed_checks (старые записи без домена). Каждая строка содержит domain, total, successful, found, not_found, blocked, errors, attempts, pages_scanned, best_position, last_check_at (Unix UTC), success_rate. best_position — минимальная найденная позиция за историю, а не последняя позиция.
GET /v1/status: загрузка работников/очереди, active_jobs, pending_job_checks, retrying_job_checks, paused_job_checks, captcha_provider=capsola, captcha_configured и device_policy. Это состояние процесса, не список позиций.
GET /v1/limits: актуальные лимиты, concurrent_checks, max_domains, max_queries, max_batch_checks, attempt_timeout_seconds, extra_page_seconds, max_attempt_timeout_seconds, check_budget_seconds, queue_timeout_seconds, recovery_mode=until_complete, durable_jobs=true, async_jobs=true, device_policy, supported_devices и job_retry_max_delay_seconds. recovery_passes/max_attempts_per_check/max_execution_seconds равны null: общего конечного лимита нет.
Лимиты запросов на аккаунт: общий API — 10/мин; /v1/status — отдельные 10/мин; чтение/отмена заданий — отдельные 120/мин; Wordstat — отдельные 10/мин. HTTP 429 от нашего API означает превышение соответствующего лимита.
Wordstat — отдельный метод
POST /v1/wordstat:
{"query":"купить сбис","region":213,"device":"all","allow_stale":false}
query: 1–400 символов, region обязателен, device: all/mobile/desktop/tablet. Политика мобильных позиций на Wordstat не распространяется. Сейчас источник не авторизован: HTTP 503 WORDSTAT_NOT_CONFIGURED. Ключ нашего API и ключ Capsola не заменяют доступ к Wordstat. Реализованы адаптеры Yandex Cloud (WORDSTAT_PROVIDER=yandex, WORDSTAT_API_KEY, WORDSTAT_FOLDER_ID) и XMLStock (provider=xmlstock, WORDSTAT_API_KEY, WORDSTAT_XMLSTOCK_USER). Прямой сбор через авторизованный сайт Wordstat пока не реализован.
Ответ при подключённом источнике: query, region, device, frequency, period=last_30_days_reported_by_provider, provider, fetched_at (Unix UTC), data_available_through, freshness, warning. frequency берётся из totalCount. Это статистика отчётного периода источника, не число запросов за сегодня. Операторы Wordstat сохраняются. Нулевой totalCount допустим; отсутствие поля не трактуется как нулевая частотность.
В конфигурации стоит WORDSTAT_DATA_THROUGH=2026-10-07: это установленное ограничение свежести, а не утверждение о текущем состоянии внешнего источника. При нём allow_stale=false даёт WORDSTAT_CURRENT_DATA_UNAVAILABLE после настройки доступа. allow_stale=true разрешает ограниченные данные с предупреждением. Снимать ограничение администратор должен после проверки свежести источника.
GET /v1/wordstat/stats: total, successful, errors — отдельный учёт обращений, включая ошибки настройки. Позиций и браузера этот метод не запускает. До двух обращений к источнику одновременно, сетевой тайм-аут 30 секунд, без автоматических платных повторов и кэша. Ошибки: 503 WORDSTAT_NOT_CONFIGURED / WORDSTAT_CURRENT_DATA_UNAVAILABLE / WORDSTAT_UPSTREAM_LIMIT; 502 WORDSTAT_UPSTREAM_AUTH / WORDSTAT_UPSTREAM_ERROR / WORDSTAT_INVALID_RESPONSE / WORDSTAT_CONNECTION_ERROR; 504 WORDSTAT_TIMEOUT.
Аккаунты и ключи (служебные методы)
Основной вход в личный кабинет — через Telegram. Email-методы сохранены для совместимости; для существующего Bearer-ключа они не нужны. POST /auth/register и POST /auth/login принимают email и password (12–128 символов). Нужны Origin, совпадающий с YANDEX_LIVE_PUBLIC_ORIGIN либо базовым адресом, и X-Requested-With: position-ui. Ответ — email и cookie yp_session. Cookie HttpOnly/SameSite=Strict; Secure включён по умолчанию. Лимит авторизации: 10 попыток за 5 минут на IP. POST /auth/logout с этими заголовками завершает сессию. GET /account с cookie возвращает email и keys. POST /account/key с cookie и защитными заголовками выдаёт новый ключ в поле key и отзывает старые ключи аккаунта. DELETE /account/key отзывает ключи. Секрет нового ключа нужно сохранить при выдаче.
Общие ошибки и диагностика
401 — неверная авторизация; 403 — источник служебного запроса не разрешён; 404 — задание отсутствует/чужое; 409 — конфликт Idempotency-Key/отмена; 422 — неверные поля; 429 — лимит нашего API; 503 — ожидается настройка. HTTP-код нашего API не является HTTP-кодом Яндекса. /partial отвечает 200 даже в процессе работы: окончание определяется по complete=true. Капчи/429 Яндекса обрабатываются внутри задания, не превращаются в not_found. Журналы попыток собираются в data/checks.jsonl с ротацией, параметры/результаты заданий — в data/accounts.sqlite3. OpenAPI-схема: GET /openapi.json. Swagger /docs и /redoc отключены.
Минимальный алгоритм клиента
- Создать уникальный идентификатор съёма, сохранить его как Idempotency-Key.
- POST /v1/jobs с checks, Bearer и этим ключом.
- Сохранить job_id, опрашивать results_url с тем же Bearer по Retry-After.
- При 202 продолжать; при 200 сохранить весь массив в исходном порядке.
- При сетевом обрыве повторить POST с тем же ключом либо продолжить GET.
- При waiting_configuration показывать ожидание владельцу, не создавать дубли.
- Новый съём — новый Idempotency-Key.
Продолжение глубокой проверки
Проверенные страницы незавершённого ключа сохраняются в SQLite. После сетевого сбоя/перезапуска съём продолжается со следующей страницы с сохранённым органическим смещением, не с первой. Регион и фраза каждой страницы по-прежнему проверяются. Страницы одного продолженного съёма собираются в пределах 15 минут от первой сохранённой страницы; после истечения этого срока проверка начинается заново. Разные IP и время могут менять выдачу: это последовательный живой съём, не одномоментный снимок поискового индекса.
Цена и баланс
Цена одной пары «домен + ключ» — 10 копеек (0,10 ₽), независимо от глубины и количества повторов. При первой регистрации через Telegram начисляется 25 бесплатных проверок (2,50 ₽ на сервисном балансе), один раз на аккаунт Telegram.
GET /v1/balance с вашим Bearer-ключом возвращает balance_kopecks, balance_rub, reserved_kopecks, reserved_rub, spent_kopecks, spent_rub, available_checks, price_per_check_kopecks=10, price_per_check_rub=0.10 и currency=RUB. Деньги хранятся целым числом копеек.
Перед запуском резервируется стоимость всего задания. Если средств не хватает, POST отвечает HTTP 402, не создаёт задание и не запускает браузер:
{"error_code":"INSUFFICIENT_BALANCE","message":"Недостаточно баланса","balance_kopecks":9,"required_kopecks":10,"currency":"RUB"}
Оплата из резерва фиксируется при готовом found/not_found, по одному разу на ключ. Повторы, капчи и сетевые ошибки не создают новых списаний. При отмене задания неиспользованный резерв возвращается, готовые строки остаются оплаченными. Средства в резерве уже оплачивают принятое задание: его работа продолжается, даже если доступный остаток стал нулевым. Новое неоплаченное задание не запустится. Повтор с тем же Idempotency-Key не резервирует и не списывает деньги повторно. Старые задания, принятые до включения биллинга, завершаются на прежних условиях.
Пополнение — в личном кабинете https://async-xml.com/panel.html через Crypto Pay. Сумма счёта задаётся в рублях, оплата выполняется криптовалютой по курсу провайдера. Зачисление происходит только после серверной проверки оплаченного счёта; возврат пользователя на страницу сам по себе не подтверждает оплату.
Вход на сайт
Откройте @async_xml_bot, нажмите «Запустить», затем введите выданный восьмизначный код на сайте. Код одноразовый, действителен 5 минут. В панели доступны баланс, создание API-ключа, проверки с прогрессом, статистика по сайтам, платежи и движение баланса. API-ключ показывается полностью только при создании. Telegram- и платёжные токены клиенту не передаются.