XProject API

HTTP-интерфейс к сервисам XProject: один ключ, общий формат ответов и ошибок, консоль для запросов прямо со страницы.

https://bot.xproject.digital v0.1.0 11 методов

Разделы

Парсинг

/api/v1/parser

Задачи по площадкам объявлений: запуск с фильтрами, чтение выдачи страницами и остановка.

5 методов

Fiverr Unlocker

/api/v1/fiverr

Регистрация, активация, вход и верификация телефона на Fiverr через ваш прокси. Защиту PerimeterX проходим мы, вы получаете ответ Fiverr и cookies аккаунта.

6 методов

Авторизация

Каждый запрос требует заголовок X-API-Key. Ключ определяет пользователя, его подписку и доступ к задачам - чужую задачу по её task_id прочитать нельзя, придёт 404.

Без заголовка или с неверным ключом сервис отвечает 401. Если подписка на парсинг неактивна, запуск задачи вернёт 402, при этом чтение уже собранных данных продолжает работать. Fiverr Unlocker без активной подписки на площадку Fiverr тоже отвечает 402.

Передавайте ключ только в заголовке: в строке запроса он попадёт в логи и историю браузера.

request.http

GET /api/v1/parser/schema
Host: bot.xproject.digital
X-API-Key: xp-live-…

Парсинг

/api/v1/parser

Задачи по площадкам объявлений: запуск с фильтрами, чтение выдачи страницами и остановка.

Что приходит в выдаче

Объявление приезжает с заголовком, ценой, площадкой, страной и контактами продавца. Полный набор полей - в примере ответа GET /{task_id} ниже.

У каждой площадки свой цвет - он повторяется в ленте и в справочнике.

Выдача задачи

GET /api/v1/parser/{task_id}

Демонстрация формата ответа на примерных данных.

Быстрый старт

Четыре вызова - весь жизненный цикл задачи. Базовый путь /api/v1/parser, ключ передаётся заголовком X-API-Key.

Узнайте, что поддерживает площадка

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

Одна задача - одна площадка плюс набор фильтров. В ответ приходит `task_id`, по нему читается выдача. Неизвестный ключ фильтра - `422`, такая же активная задача - `409`.
python
Читайте объявления страницами

До 100 объявлений за вызов, свежие сверху. Пока `has_more` равен `true`, передавайте `next_cursor` из прошлого ответа в параметр `cursor`. Когда страницы закончились, задача продолжает работать - возвращайтесь через минуту-другую за новыми.
python
Остановите задачу

Новые объявления собираться перестанут, уже накопленные остаются доступными через `GET /{task_id}`. Здесь скрипт собран целиком - его можно забрать и запустить.
python

Методы

Раскройте метод, чтобы прочитать описание, собрать запрос и отправить его прямо отсюда - с вашим ключом на этот же хост.

› GET /api/v1/parser/schema Поддерживаемые платформы, страны, категории, поля фильтров

Возвращает справочник: для каждой платформы - список стран, категорий и допустимых ключей в `start.filters`. Список глобально допустимых filter columns - в поле `filter_columns`. Реально принимается только их пересечение со `supported_filters` конкретной платформы.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/parser/start Запустить задачу парсинга

Создаёт задачу под одну платформу с набором фильтров. Доступные ключи `filters` для каждой платформы - `GET /schema`. Невалидный ключ → 422. Если активная задача с теми же параметрами уже существует - 409.

curl

⌘↵ не отправлен

ответ

› GET /api/v1/parser/tasks Запущенные задачи текущего юзера

curl

⌘↵ не отправлен

ответ

› GET /api/v1/parser/{task_id} Объявления задачи (страница 100, cursor-пагинация)

Возвращает до 100 объявлений за вызов, отсортированных по `row_id` (самые свежие выше). Для следующей страницы передай `?cursor=<next_cursor>` из предыдущего ответа. Если `has_more=false` - это последняя страница на сейчас, можно опрашивать снова через минуту-две, чтобы поймать новые.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/parser/{task_id}/stop Остановить задачу

Помечает задачу как остановленную; новые объявления собираться не будут, но уже накопленные доступны через `GET /{task_id}`. 404, если задача не существует или принадлежит другому юзеру.

curl

⌘↵ не отправлен

ответ

Площадки

Как работают фильтры

Фильтры передаются объектом filters при запуске задачи. Ключ, которого нет у выбранной площадки, отклоняется с 422.

categories countries: Массивы значений из справочника площадки. Страны - ISO-коды из двух букв (Великобритания - gb, не uk). Пустой массив и отсутствие ключа означают «без ограничения».
price_min · price_max seller_*_max: Числовые границы: цена, количество отзывов, объявлений и продаж продавца. Суффикс _min задаёт нижнюю границу, _max - верхнюю.
delivery seller_email · seller_online: Булевы фильтры работают как включатели: true оставляет только подходящие объявления, null или отсутствие ключа снимает ограничение.
created_at_period: Глубина поиска по дате публикации: 1h, 3h, 7d, 2w, 6m, 1y - число и единица времени. 7d означает объявления за последние семь дней.
created_at_period: fresh: Отдельный режим: историю площадки задача не забирает и отдаёт только те объявления, которые появились после её запуска. Подходит для постоянного мониторинга - оставьте задачу активной и периодически читайте выдачу.
seller_created_at_period seller_created_at_max_period: Возраст аккаунта продавца в том же формате. Первый ключ оставляет продавцов не старше периода, второй - не моложе.
stop_words: Массив слов. Если хотя бы одно встречается в названии или описании, объявление в выдачу не попадает.
internal_listing_count internal_view_count: Лимит объявлений за один запуск и ограничение по тому, сколько раз объявление уже отдавалось парсером: 0 оставит только те, которые вы ещё не видели.

Fiverr Unlocker

/api/v1/fiverr

Что происходит за один вызов

Вы шлёте данные и прокси, всё остальное на нашей стороне. В ответ приходит ответ Fiverr как есть и cookies аккаунта для следующего шага.

проксиПроверяем, что ваш прокси жив, и дальше ходим только через него.
PerimeterXПроходим защиту Fiverr. Сессия запоминается за аккаунтом, следующие шаги берут её из кеша.
FiverrВыполняем действие и отдаём ответ без изменений.

Регистрация аккаунта

Демонстрация на примерных данных.

Быстрый старт

Регистрация аккаунта от почты до подтверждённого телефона: почта из AnyMessage, SMS из Spanch, запросы к Fiverr - через нас. Прохождение PerimeterX списывается с баланса (0.003 USDT, press-and-hold - 0.005 USDT) и переиспользуется между шагами одного аккаунта. Базовый путь /api/v1/fiverr, ключ передаётся заголовком X-API-Key.

Подготовьте ключи и закажите почту

Ключ XProject, прокси и токены AnyMessage и Spanch. Хелпер `fiverr()` добавляет прокси к каждому вызову. Лимит - 5 одновременных запросов на ключ.
python
Зарегистрируйте аккаунт

Ответ Fiverr приходит как есть в `response`, его HTTP-статус - в `status`. Отказ Fiverr, например занятый username, - это `ok: false`, а не ошибка HTTP. `cookies` из ответа передавайте в `auth_cookies` следующих шагов. Для готового аккаунта вместо регистрации - `POST /login`.
python
Активируйте почту кодом из письма

Ждём письмо в AnyMessage и берём из него шестизначный код. Письмо не пришло - `POST /resend-activation` и ждите снова.
python
Подтвердите телефон

Берём номер в Spanch, Fiverr отправляет на него SMS, код уходит в `/phone/verify`. SMS не пришла - отменяем номер и берём новый. Здесь скрипт собран целиком - его можно забрать и запустить.
python

Методы

› POST /api/v1/fiverr/activate Активация аккаунта кодом из письма

Подтверждает email кодом из письма. `auth_cookies` - из ответа `/register` или `/login`.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/fiverr/login Вход в аккаунт Fiverr

Логин по email и паролю. Возвращает cookies авторизованной сессии. Неверный пароль или бан аккаунта приходят от Fiverr в `response` с `ok: false`, а не HTTP-ошибкой.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/fiverr/phone/send-code Отправить код на телефон

Запускает верификацию телефона: Fiverr отправляет код на номер.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/fiverr/phone/verify Подтвердить телефон кодом

Завершает верификацию телефона кодом, полученным после `/phone/send-code`.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/fiverr/register Регистрация аккаунта Fiverr

Создаёт аккаунт на Fiverr. После успеха Fiverr отправляет письмо с кодом активации. `cookies` из ответа сохраните - они нужны для `/activate` и `/phone/*`.

curl

⌘↵ не отправлен

ответ

› POST /api/v1/fiverr/resend-activation Повторно отправить письмо активации

Просит Fiverr ещё раз прислать код активации на указанный email.

curl

⌘↵ не отправлен

ответ

Ошибки

Причина всегда приходит текстом в поле detail.

код

что произошло

что делать

401

Заголовок X-API-Key отсутствует или ключ неверный.

Проверьте ключ и то, что он уходит заголовком.

401

Fiverr UnlockerCookies из `auth_cookies` больше не действуют.

Войдите заново через `POST /login`.

402

ПарсингПодписка на парсинг неактивна.

Продлите подписку; чтение старых задач работает.

402

Fiverr UnlockerНет подписки на Fiverr или на балансе не хватает на прохождение PerimeterX.

Продлите подписку или пополните баланс.

403

Пользователь заблокирован.

Напишите в поддержку.

404

ПарсингЗадача не найдена или принадлежит другому пользователю.

Сверьте task_id и ключ.

409

ПарсингАктивная задача с такими же параметрами уже есть.

Читайте её выдачу вместо запуска новой.

409

Fiverr UnlockerАккаунт Fiverr Pro.

Работают только обычные аккаунты.

422

ПарсингНеизвестный ключ фильтра, страна, категория или формат периода.

Сверьтесь с GET /schema и разделом «Площадки».

422

Fiverr UnlockerНеверный формат прокси или в теле не хватает поля.

Прокси - `[scheme://][user:pass@]host:port`.

429

Слишком много запросов.

Повторите через интервал из заголовка Retry-After.

502

ПарсингПлощадка или сеть временно недоступны.

Повторите позже, задача не теряется.

502

Fiverr UnlockerПрокси не отвечает или Fiverr недоступен.

Проверьте прокси, причина - в `detail`.

503

Не удалось автоматически пройти защиту площадки.

Повторите позже; для Fiverr можно сменить прокси.

Для языковых моделей

Та же документация без вёрстки лежит по адресу /llm.txt: порядок вызовов, правила фильтров, площадки, категории и допустимые значения одним плоским текстом.

Дайте модели ссылку целиком - этого достаточно, чтобы она собрала клиент или готовый запуск задачи под нужные фильтры.

/llm.txtтекст для модели /openapi.jsonсхема OpenAPI

Авторизация

Парсинг

Что приходит в выдаче

Быстрый старт

Узнайте, что поддерживает площадка

Запустите задачу

Читайте объявления страницами

Остановите задачу

Методы

Площадки

Как работают фильтры

Fiverr Unlocker

Что происходит за один вызов

Быстрый старт

Подготовьте ключи и закажите почту

Зарегистрируйте аккаунт

Активируйте почту кодом из письма

Подтвердите телефон

Методы

Ошибки

Для языковых моделей