API — Пул портов

Открывает пул портов из списка прокси.

curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"tiktok-pool","target":100,"port_lo":20000,"port_hi":30000,
        "protocol":"socks5",
        "source":{"kind":"file","location":"C:/proxies.txt"},
        "up_policy":{"mode":"requests","n":1},
        "fp_policy":{"mode":"requests","n":10},
        "connect_timeout_seconds":5,"request_timeout_seconds":30}' \
  http://127.0.0.1:8891/api/v1/scraper/tasks

{
  "id": "pool-7f3a",
  "export_token": "3b91c0d4e5f6",
  "warnings": null
}

🔴 id и export_token берутся ОТСЮДА: id подставляется в /scraper/tasks/{id}/…, а export_token — в адрес выгрузки /export/{token}/proxies.txt. Другого места, где их видно, нет — кроме GET /api/v1/scraper/tasks. warnings несёт РОВНО ОДНО замечание — «opened N of M ports (range LO-HI too small or ports busy)», если удалось открыть меньше портов, чем просили в target; если открылись все, поле приходит как null. Про источник прокси warnings не сообщает НИЧЕГО: ни сколько записей не разобралось, ни того, что источник вовсе не прочитался (404 или таймаут по URL, отсутствующий файл). В этом случае пул всё равно поднимается — с пустым списком выходов — и отвечает 200, а узнать о беде можно только по отказам трафика. Проверять источник надо ЗАРАНЕЕ, отдельной ручкой POST /api/v1/scraper/probe: она возвращает total (пригодных записей) и bad (битых).

403 «the scraper port pool requires a Pro license (single-thread Lite cannot open a port pool)» на тарифе Lite; 503 «scraper manager not configured», если пул в этой сборке не поднят; 400 с объяснением, если конфигурация не сходится: port_lo больше port_hi, target меньше 1, неизвестное значение profile_source, up_policy.mode, fp_policy.mode или vdns_mode, неизвестная либо несовместимая пара device и device_os. 🔴 Диапазон, которого не хватает на target, отказом НЕ является: пул открывает столько портов, сколько поместилось — в том числе НИ ОДНОГО, если все они заняты, — отвечает 200 и кладёт в warnings строку вида «opened 11 of 100 ports (range 20000-20010 too small or ports busy)». Поэтому проверяйте warnings, а не только код ответа.

Два умолчания ставятся на СОЗДАНИИ, а не хранятся в конфигурации: protocol, если он не задан, становится socks5 (чтобы работали UDP и HTTP/3), а vdns_mode — forced, то есть имя цели резолвится на стороне выхода и не утекает в DNS вашей сети. Явное "off" остаётся выключением.

Снимок всех пулов: сколько портов открыто, какие именно и в каком диапазоне они выданы.

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks

[
  {
    "id": "pool-7f3a",
    "name": "catalogue-pool",
    "target": 100,
    "ports_up": 98,
    "ports": [20000, 20001, 20002],
    "export_token": "3b91c0d4e5f6",
    "port_lo": 20000,
    "port_hi": 30000
  }
]

• Пустой массив означает, что ни одного пула сейчас нет — это не ошибка. 503 «scraper manager not configured», если пул в этой сборке не поднят.
• Числа прокси в источнике и состояния ротации в ответе НЕТ: сколько записей в источнике — отвечает POST /api/v1/scraper/probe (поле total), а какая ротация настроена — GET /api/v1/scraper/tasks/{id}/config (up_policy и fp_policy). Поле ports_up — счётчик поднятых портов, а ports — их номера.

Останавливает пул и закрывает все его порты. Трафик, идущий через них, обрывается.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks/pool-7f3a

{
  "ok": true
}

• 404 с текстом менеджера, если пула с таким идентификатором нет.

Прогоняет полную проверку порта пула — ту же, что POST /api/v1/port/{port}/test, — на одном из живых портов и возвращает, какой порт проверялся.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks/pool-7f3a/test

{
  "port": 20134,
  "report": { "leak": { "…": "…" }, "fingerprint": { "match": true },
                "udp": { "supported": true }, "ok": true }
}

• 409 «scraper task has no open ports yet», пока пул не поднял ни одного порта, и 409 «scraper task ports are not live», если порты уже не работают. 404, если пула нет.

Возвращает сохранённую конфигурацию пула в том самом виде, который принимает POST /api/v1/scraper/tasks: правку делают остановкой и повторным запуском.

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/tasks/pool-7f3a/config

{
  "id": "pool-7f3a",
  "name": "catalogue-pool",
  "port_lo": 20000,
  "port_hi": 30000,
  "target": 100,
  "protocol": "socks5",
  "source": { "kind": "file", "location": "C:/proxies.txt" },
  "up_policy": { "mode": "requests", "n": 1 },
  "fp_policy": { "mode": "requests", "n": 10 },
  "vdns_mode": "forced",
  "export_token": "3b91c0d4e5f6"
}

• 404 «task not found». Конфигурация несёт и продвинутые поля, которых нет в таблице открытия: cache_mode, leak_guard, js_solver, keep_sessions, captcha_action и три тайм-аута порта.

Перечисляет сочетания браузера и операционной системы, из которых можно собрать пул.

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/scraper/device_matrix

{
  "chrome": ["windows", "macos", "linux", "android", "ios"],
  "edge": ["windows", "macos", "linux", "android", "ios"],
  "firefox": ["windows", "macos", "linux", "android", "ios"],
  "safari": ["macos", "ios"]
}

• Значения отсюда кладут в поля device и device_os при открытии пула.
• Единственное, чего не бывает, — Safari вне техники Apple. Таблица описывает, что примет проверка при ЯВНОМ выборе; device: random тянет более узкий набор — без iOS у Chrome, Firefox и Edge и без Android у Firefox и Edge, — на такие пары попадают только явным указанием.

Скачивает и разбирает источник прокси, НЕ запуская пул: сколько записей пригодно, сколько битых, какие схемы встречаются и случайная выборка для собственной проверки связности.

{ "source": { "kind": "url", "location": "https://example.com/proxies.txt" } }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"source":{"kind":"url","location":"https://example.com/proxies.txt"}}' \
  http://127.0.0.1:8891/api/v1/scraper/probe

{
  "total": 13045,
  "bad": 210,
  "by_scheme": { "socks5": 12835, "http": 210 },
  "sample": ["socks5://203.0.113.10:1080", "socks5://203.0.113.11:1080"]
}

• 400 с объяснением, если источник не скачался или не разобрался. Тело ограничено 32 МиБ — столько весит список, вставленный целиком; проверка ограничена 35 секундами.
• 403 при неактивной лицензии: ручка за лицензией, как и остальные проверки выхода.

Скачивает порты пула в виде списка прокси в текстовом формате. Доступ предоставляется по токену в URL, поэтому API-ключ не требуется.

curl http://127.0.0.1:8891/export/TASK_TOKEN/proxies.txt