async-xml
· Личный кабинет · Скачать Markdown

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}

Все перечисленные 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 отключены.

Минимальный алгоритм клиента

  1. Создать уникальный идентификатор съёма, сохранить его как Idempotency-Key.
  2. POST /v1/jobs с checks, Bearer и этим ключом.
  3. Сохранить job_id, опрашивать results_url с тем же Bearer по Retry-After.
  4. При 202 продолжать; при 200 сохранить весь массив в исходном порядке.
  5. При сетевом обрыве повторить POST с тем же ключом либо продолжить GET.
  6. При waiting_configuration показывать ожидание владельцу, не создавать дубли.
  7. Новый съём — новый 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- и платёжные токены клиенту не передаются.