# 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` и перезапуском.

## Проверки позиций

Объект проверки:

```json
{"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 проверок. Для нескольких доменов:

```json
{"domains":["example.org","example.net"],"queries":["первая фраза","вторая фраза"],"region":213,"device":"mobile","pages":10}
```

До 10 доменов и 100 фраз; создаётся декартово произведение.
Повторы доменов и фраз в этом методе удаляются.
Промо, реклама, рекламные редиректы и дополнительные ссылки не увеличивают
органическую позицию. Рекламное размещение проверяемого домена тоже исключается.
Позиция считается среди распознанных органических результатов; страницы
могут содержать разное число результатов. 10 страниц не гарантируют 100 мест.
Выдача зависит от региона, устройства, времени и персонализации.

Пример структуры результата (числа условные):

```json
{"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` необязателен.

```sh
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 и объект:

```json
{"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:

```json
{"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, не создаёт задание и не запускает браузер:

```json
{"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- и платёжные токены клиенту не передаются.
