Market NinjaMarket Ninja

Обзор API

Как получить ключ, авторизоваться и начать работу с API Market Ninja — модель поиск → получение, лимиты, формат ошибок.

API Market Ninja даёт программный доступ на чтение к тому же краудсорсинговому датасету, который вы видите в интерфейсе расширения: товары, цены (текущие и исторические), продавцы и категории с Wildberries, Ozon, Яндекс Маркета и Lamoda.

API не собирает данные и не может запустить парсинг — это доступ только на чтение уже накопленного датасета. Новые товары в него добавляются исключительно через браузерное расширение Market Ninja: если нужного товара ещё нет в базе, сначала соберите его расширением, и только затем он станет доступен через API.
API предназначен только для серверных интеграций (server-to-server). Секретный ключ — это долгоживущий пароль, и он никогда не должен попадать в код, исполняемый в браузере (так же, как секретные ключи Stripe).

Получение ключа

Ключ выпускается в настройках расширения — раздел API-ключи, доступен на тарифе Premium. Полное значение ключа (mn_live_...) показывается только один раз, в момент создания — сохраните его сразу, восстановить позже нельзя (только отозвать и выпустить новый).

Авторизация

Каждый запрос должен содержать заголовок:

Authorization: Bearer mn_live_ваш_ключ
curl -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products?page_size=3"

Главная модель использования: «найти → получить»

Никто извне не знает внутренний id товара в нашей базе — он никому не известен заранее. Вместо этого вы всегда начинаете с того, что у вас уже есть:

Найдите товар через GET /products, передав то, что у вас есть: ссылку на товар (url), артикул маркетплейса (external_id + marketplace) или ваш собственный внутренний артикул (seller_code).

Получите id из поля data[].id в ответе — это наш внутренний идентификатор.

При необходимости обратитесь к товару напрямую по id (GET /products/{id}) или к истории его цен (GET /products/{id}/price-history) — но учтите, что текущая цена уже есть в ответе на шаге 1, отдельный запрос нужен только для анализа динамики.

Подробные сценарии с примерами — в разделах Поиск товаров, История цен, Продавцы, Категории, Бренды, Массовая выгрузка, Сессии парсинга (получение того, что вы только что спарсили через расширение) и Вебхуки (уведомление о завершении сессии вместо опроса). Полное описание параметров и ответов каждого эндпоинта — в разделе Справочник.

Формат ошибок

Любая ошибка возвращается в едином виде:

{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key" } }
HTTP-статусerror.codeЗначение
400validation_errorНекорректные параметры запроса.
401invalid_api_keyКлюч отсутствует, некорректен, отозван или истёк.
403subscription_lapsedКлюч верный, но подписка Premium сейчас не активна.
404not_foundТовар с указанным id не найден.
429rate_limitedПревышен лимит запросов в минуту — повторите через Retry-After секунд.
429quota_exceededИсчерпана дневная квота на объём данных — сбрасывается в 00:00 UTC.
500internal_errorВнутренняя ошибка сервера, можно повторить позже.
503query_timeoutЗапрос выполнялся слишком долго. Подождите Retry-After секунд и повторите; если ошибка повторяется, сузьте запрос (например, более длинное слово в name_contains или дополнительный фильтр).
503service_unavailableСервис временно перегружен — повторите через Retry-After секунд.
403 и 401 — разные проблемы для интегратора: «ключ неверный» (нужно проверить значение) и «нужно продлить подписку» (ключ рабочий, но доступ приостановлен). Не объединяйте их обработку в коде — сообщения пользователю должны различаться.

Лимиты и квоты

Доступ к API ограничен двумя независимыми лимитами: частотой запросов и дневным объёмом данных. Оба действуют на каждый API-ключ отдельно. При превышении любого из них API отвечает 429, а различить их можно по полю error.code.

ЛимитЗначениеЧто считаетсяКогда восстанавливаетсяКод ошибки
Лимит запросов120 запросов в минутуКаждый HTTP-запросВ начале каждой минутыrate_limited
Дневная квота75 000 записей в суткиЗаписи в ответахВ 00:00 UTC (03:00 МСК)quota_exceeded

Лимит запросов

Лимит запросов — это максимальное число запросов, которое ключ может отправить за одну минуту: 120. При превышении API отвечает 429 с кодом rate_limited. Считается каждый запрос, независимо от того, сколько записей он вернул, включая запросы к /categories и /brands и запросы, отклонённые из-за исчерпанной квоты.

Счётчик привязан к календарной минуте: он обнуляется в :00 секунд каждой минуты, а не через 60 секунд после первого запроса.

Получив 429 rate_limited, подождите столько секунд, сколько указано в Retry-After, и повторите тот же запрос.

Дневная квота

Дневная квота — это максимальное число записей, которое ключ может получить через API за сутки: 75 000. Когда она исчерпана, API отвечает 429 с кодом quota_exceeded. Считается не число запросов, а записи в ответах: запрос с page_size=500 расходует до 500 записей, запрос с page_size=10 — до 10.

ЭндпоинтЧто считается записью
GET /productsКаждый товар в ответе
GET /products/{id}Товар (1 запись)
GET /products/{id}/price-historyКаждая точка истории цен
GET /sellersКаждый продавец в ответе
GET /me/scrapes/{id}/productsКаждый товар в ответе (строки pending не считаются)
GET /categories, GET /brands, GET /me/scrapes, GET /me/scrapes/{id}Квоту не расходуют

Квота проверяется перед запросом: если она ещё не исчерпана, запрос выполняется полностью, поэтому последний запрос дня может немного превысить её.

Квота ограничивает объём за сутки, а не весь датасет: после сброса в 00:00 UTC (03:00 МСК) можно продолжить с того места, где вы остановились. Расход за текущий день по каждому ключу виден на странице API-ключи в личном кабинете.

Получив 429 quota_exceeded, остановите выгрузку до сброса: до этого времени API будет отвечать тем же. Заголовка Retry-After в этом ответе нет, сколько осталось ждать, показывает X-Quota-Reset.

Если для вашей задачи 75 000 записей в сутки мало, напишите нам в Telegram @getmarketninja, и мы обсудим лимит для вашего ключа.

Заголовки ответа

Заголовки с текущим состоянием лимитов есть в каждом ответе, кроме 401 и 403, в том числе в успешных. По ним можно распределять нагрузку, не дожидаясь 429.

ЗаголовокЗначение
X-RateLimit-LimitЛимит запросов в минуту
X-RateLimit-RemainingСколько запросов осталось в текущей минуте
X-RateLimit-ResetЧерез сколько секунд начнётся следующая минута
Retry-AfterВ ответах 429 rate_limited и 503: через сколько секунд повторить запрос
X-Quota-LimitДневная квота ключа
X-Quota-UsedСколько записей получено сегодня, с учётом этого ответа
X-Quota-RemainingСколько записей осталось до конца суток
X-Quota-ResetЧерез сколько секунд квота сбросится

/categories и /brands не расходуют квоту, поэтому возвращают только заголовки X-RateLimit-*.

Проблемы с подключением

Если соединение обрывается раньше, чем сервер успевает ответить, вы увидите одну из таких ошибок:

  • cURL: curl: (35) ... SSL_ERROR_SYSCALL или Connection reset by peer;
  • JavaScript (Node.js, fetch): TypeError: fetch failed, а в error.cause — ECONNRESET или Client network socket disconnected before secure TLS connection was established;
  • Python (requests): SSLError ... EOF occurred in violation of protocol.

Это значит, что соединение разорвалось по пути к серверу и запрос до API не дошёл. Ключ, подписка и лимиты здесь ни при чём: при проблемах с ними сервер всегда отвечает HTTP-статусом и JSON-телом (см. Формат ошибок). Если в ответ пришёл JSON, с соединением всё в порядке.

Чаще всего соединение прерывают VPN, прокси, антивирус с проверкой HTTPS или корпоративный сетевой фильтр. Что проверить:

  1. Полностью закройте VPN-приложение (выйдите из него, а не просто отключитесь) и повторите запрос. Исключения по домену в настройках VPN могут не действовать на скрипты и curl, и тогда их трафик всё равно идёт через VPN.

  2. Проверьте, через какой сетевой интерфейс идёт трафик. Узнайте IP-адрес сервера командой nslookup data.marketninja.ru (нужен адрес в конце вывода, а не адрес DNS-сервера в первых строках), затем выполните:

    • macOS: route -n get <IP> — если в строке interface: указан utun…, запросы идут через VPN;
    • Linux: ip route get <IP> — если после dev указан tun… или wg…, запросы идут через VPN;
    • Windows (PowerShell): Find-NetRoute -RemoteIPAddress <IP> — в поле InterfaceAlias будет название VPN-адаптера, если запросы идут через него.

    Если VPN нужен постоянно, добавьте этот IP-адрес в его исключения. Адрес может измениться, поэтому, если проблема вернётся, проверьте его снова.

  3. Проверьте переменные прокси в терминале (macOS/Linux): env | grep -i proxy.

  4. На Windows проверьте ошибку отзыва сертификата. Встроенный curl.exe проверяет, не отозван ли сертификат, и отказывается подключаться, если проверка не удалась (ошибка CRYPT_E_NO_REVOCATION_CHECK или CRYPT_E_REVOCATION_OFFLINE). Флаг --ssl-no-revoke отключает эту проверку и позволяет убедиться, что дело в ней. Используйте его только для диагностики.

  5. Убедитесь, что ваш клиент поддерживает TLS 1.2 или новее. Более старые версии протокола API не принимает.

Если ничего не помогло, напишите нам в Telegram @getmarketninja и пришлите полный вывод curl -v (ключ замажьте), примерное время попытки и IP-адрес, с которого вы подключаетесь (при включённом VPN — внешний адрес VPN-сервера).

Полезно знать

  • Кешируйте найденный id. Он не меняется — если вы регулярно опрашиваете один и тот же товар (например, бренд ежедневно сверяет свой каталог), сохраните id после первого поиска и в следующий раз обращайтесь сразу по нему, не повторяя GET /products — это экономит и запросы, и квоту.
  • unverified/flagged данные не скрываются по умолчанию. Поле trust_status всегда присутствует в ответе — решение, доверять ли ещё не подтверждённой записи, остаётся за вами.
  • Постраничная разбивка не требует явного знания общего числа страниц — у большинства списочных эндпоинтов есть точный meta.total; ориентируйтесь на него и продолжайте, пока не соберёте нужное количество записей. Исключение — GET /products: он возвращает meta.has_more вместо этого (см. Массовую выгрузку).

Обновлено

На странице