API разработчикам

REST API нужен, чтобы запускать парсинг товаров, собирать категории сайтов, выгружать товары в нужный формат и забирать результаты из своих скриптов и сервисов — без ручной работы на сайте.

Базовый адрес: https://q-parser.ru/api/v1. API-ключ можно посмотреть и перевыпустить в настройках профиля.

Тело POST-запросов — JSON с заголовком Content-Type: application/json. Даты в ответах — unix timestamp в миллисекундах.

Ошибки приходят в виде { "error": { "code": "...", "message": "..." } }. Типичные коды: unauthorized, bad_request, forbidden, not_found, unprocessable, internal.

Авторизация

В каждом запросе передайте API-ключ в заголовке Authorization: Bearer ВАШ_КЛЮЧ или X-Api-Key: ВАШ_КЛЮЧ. Ключ передавайте только в заголовках, не публикуйте его и не вставляйте в клиентский код.

GET /api/v1/me

Текущий пользователь: тариф, баланс и AI Points.

Ответ (200):

• email — email пользователя
• tariff_id — идентификатор тарифа
• tariff_until — срок действия тарифа (unix ms)
• balance — баланс в рублях
• ai_points — AI Points, как в шапке кабинета

GET /api/v1/website/:domain

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

Запрос: domain в пути (например example.com).

Ответ (200):

• domain — канонический домен
• protocol — http или https
• auth_required — нужна ли авторизация на сайте
• manual_categories — нужно ли передавать категории вручную
• options — объект опций (может быть пустым). Ключ опции передаётся в options при запуске парсинга категорий или товаров. Типы: select, input, file, text, html, vkcom, okru

GET /api/v1/credentials

Список сохранённых логинов для сайтов, где нужна авторизация. Пароли не возвращаются.

Запрос: необязательный query-параметр domain — фильтр по сайту.

Ответ (200): объект credentials — массив записей:

• id — идентификатор записи (UUID), его передают в credentials_id
• domain — домен сайта
• login — логин
• last_login — время последней успешной авторизации (unix ms) или null

POST /api/v1/credentials

Добавляет логин и пароль. Если такая пара уже есть, пароль обновляется, id остаётся прежним.

Запрос (JSON):

• domain — домен сайта
• login — логин
• password — пароль

Ответ (201): id, login, domain.

POST /api/v1/categories

Запускает сбор категорий сайта. Если список уже есть в кэше, сразу возвращается completed без повторного сбора.

Запрос (JSON):

• domain — домен сайта
• credentials_id — UUID сохранённого логина, если на сайте нужна авторизация
• options — значения опций сайта (ключи из GET /api/v1/website/:domain), строки или null

Ответ (201):

• id — идентификатор задачи, его передают в GET /api/v1/categories/:id
• status — running или completed

GET /api/v1/categories/:id

Статус и результат сбора категорий.

Запрос: id задачи из POST /api/v1/categories.

Ответ (200):

• id — идентификатор задачи
• status — running, completed или error
• updated — время обновления кэша (unix ms) или null
• categories — массив { title, url } или null, пока статус running

POST /api/v1/parser

Запускает парсинг товаров. Полноценный парсинг платного сайта — только с действующим тарифом. Пробный парсинг — с trial: true, доступен без тарифа. Если categories не передан или пустой, список категорий будет загружен автоматически на старте парсинга.

Одновременно не больше 100 незавершенных парсингов. Пока лимит занят, запрос вернёт unprocessable.

Запрос (JSON):

• domain — домен сайта
• categories — необязательный массив { title, url }. Элементы без названия или ссылки пропускаются. Ссылка должна вести на этот же сайт
• credentials_id — UUID логина, если нужна авторизация
• options — значения опций сайта
• trial — true для пробного парсинга

Ответ (201): id парсинга в виде id1234567.

GET /api/v1/parser/list

История парсингов.

Запрос:

• limit — размер страницы, по умолчанию 100, максимум 1000
• offset — смещение, по умолчанию 0

Ответ (200):

• total — всего парсингов
• limit, offset — фактическая пагинация
• list — массив: id, domain, status (queued, running, completed, canceled, error), goods_processed, goods_limited, categories_total, categories_processed, created, finished (unix ms, finished может быть null), archive

GET /api/v1/parser/:id

Статус парсинга: очередь, прогресс, ошибка.

Запрос: id в пути — полный id парсинга, например id1234567.

Ответ (200):

• id — идентификатор парсинга
• status — queued, running, completed, canceled или error
• domain — домен сайта
• goods_processed — сколько товаров уже спарсено
• goods_limited — лимит товаров по тарифу или null
• categories_total — всего категорий в задании
• categories_processed — сколько категорий уже обработано
• created — время создания (unix ms)
• finished — время завершения (unix ms) или null
• archive — архивный парсинг
• error — текст ошибки или null

GET /api/v1/parser/:id/goods

Список товаров парсинга с постраничной выдачей.

Для архивного парсинга товары недоступны, запрос вернёт unprocessable.

Запрос:

• id в пути — полный id парсинга, например id1234567
• limit — размер страницы, по умолчанию 100, максимум 1000
• offset — смещение, по умолчанию 0

Ответ (200):

• total — всего товаров
• limit, offset — фактическая пагинация
• goods — массив товаров: title, article, url, price, old_price, currency, brand, quantity, publish (наличие, true / false / null), images, file_links, video_links (массивы ссылок), category_title, category_url, description, short_description, data — дополнительные характеристики с человекочитаемыми ключами

GET /api/v1/format

Список форматов выгрузки: идентификаторы, названия и схема опций.

Ответ (200): объект formats — массив записей:

• id — идентификатор формата, его передают в POST /api/v1/export
• title — название формата
• options — объект опций (может быть пустым). Ключ опции передаётся в options при запуске выгрузки. Каждая опция: title, type, values — массив { key, label }. Для выбора обычно берут key первого элемента values

POST /api/v1/export

Запускает выгрузку товаров парсинга в выбранный формат.

Одновременно не больше 100 незавершенных выгрузок любого формата. Пока лимит занят, запрос вернёт unprocessable.

Запрос (JSON):

• parser_id — полный id парсинга, например id1234567
• format — id формата из GET /api/v1/format
• options — значения опций формата (ключи из схемы формата). Необязательно можно передать offset (с какого товара, с нуля) и limit (сколько товаров выгрузить)

Ответ (201): id выгрузки (UUID).

GET /api/v1/export/:id

Статус выгрузки: очередь, прогресс, файлы или ссылки результата.

Запрос: id в пути — UUID выгрузки из POST /api/v1/export.

Ответ (200):

• id — идентификатор выгрузки
• status — queued, running, completed, canceled или error
• parser_id — id парсинга
• format — id формата
• goods_exported — сколько товаров уже обработано
• created — время создания (unix ms)
• finished — время завершения (unix ms) или null
• error — текст ошибки или null
• message — сообщение результата или null
• files — массив ссылок на файлы выгрузки (может быть пустым)
• links — массив { title, url } (может быть пустым)
• progress — { current, max, message } во время работы или null

Связанные материалы

• Как выгружать товары
• Форматы выгрузки
• Автовыгрузки по расписанию
• Выгрузка на FTP и S3