Расширенная аналитика 1688 API

Четыре POST-метода работают в отдельном сервисе BHAPI. Создайте токен именно для аналитики 1688: токен обычного 1688 и его квота сюда не подходят. Каждый успешный вызов расходует одну единицу квоты этого сервиса. Цены и лимиты зависят от активного тарифа.

Методы и быстрый старт

Передавайте токен в X-API-Token, JSON в Content-Type: application/json. Не помещайте токен в URL.

curl -X POST "https://bhapi.ru/analytics/1688/api/v1/products/search" \
  -H "X-API-Token: ВАШ_ТОКЕН_АНАЛИТИКИ" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"保温杯","period":"rolling_30d","page":1,"page_size":10}'

import requests

response = requests.post(
    "https://bhapi.ru/analytics/1688/api/v1/products/search",
    headers={"X-API-Token": "ВАШ_ТОКЕН_АНАЛИТИКИ"},
    json={"keyword": "保温杯", "period": "rolling_30d", "page": 1, "page_size": 10},
    timeout=120,
)
response.raise_for_status()
items = response.json()["data"]["items"]

Поиск и витрина: параметры

Укажите ровно один селектор: keyword (непустая строка до 50 символов), goods_url (публичный HTTPS URL до 4096 символов) или product_ids (1–20 уникальных положительных числовых строк, каждая до 64 символов). ID как JSON number не принимается. Не передавайте пользовательские URL с приватными адресами.

Каждый диапазон в filters — объект с min, max или обеими границами; при двух границах требуется min ≤ max. Для диапазона дат используйте from, to или обе даты. Для match значение по умолчанию fuzzy задаётся только при Search с keyword; Billboard не добавляет режим сам.

Для диапазонов передайте хотя бы одну границу. Денежные границы принимают JSON число или десятичную строку; строка сохраняет точность. Значения должны быть неотрицательными, а нижняя граница не больше верхней.

Дата Billboard выбирает календарный период, а не время обновления данных. Для примеров выбирайте последний завершённый период. Неизвестные поля отклоняются.

Пример календарной витрины

curl -X POST "https://bhapi.ru/analytics/1688/api/v1/products/billboard" \
  -H "X-API-Token: ВАШ_ТОКЕН_АНАЛИТИКИ" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"保温杯","period_type":"week","date":"2026-10-18","page":1,"page_size":10}'

Для месячного среза используйте "period_type":"month","date":"2026-09-01". Примеры дат обновляются на странице автоматически.

Карточка товара

offer_id обязателен: положительная числовая строка до 64 символов. Необязательная currency — три ASCII-буквы, приводится к верхнему регистру. Неизвестные поля и числовой ID отклоняются.

{"offer_id":"745678901234","currency":"CNY"}

curl -X POST "https://bhapi.ru/analytics/1688/api/v1/products/detail" \
  -H "X-API-Token: ВАШ_ТОКЕН_АНАЛИТИКИ" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"745678901234","currency":"CNY"}'

{"status":"ok","data":{"product":{"offer_id":"745678901234",
  "title":"Термокружка","title_translated":null,"product_url":null,
  "image_urls":[],"company":null,"status":null,"created_at":null,
  "category_id":null,"top_category_id":null,"second_category_id":null,
  "third_category_id":null,"min_order_quantity":2,"attributes":[],
  "pricing":null,"skus":[],"description_html":null,"description_truncated":false}},
  "meta":{"request_id":"пример-id","retrieved_at":"2026-10-01T10:00:00Z","snapshot_date":null}}

Ценовые ступени не включают доставку и налоги; остаток не равен продажам. Фактическую валюту каждой цены проверяйте в Money.currency ответа. description_html считайте недоверенным HTML и экранируйте перед показом.

Поиск по изображению

Укажите ровно одно: image_url (публичный HTTP/HTTPS URL до 1000 символов), image_base64 (raw Base64 PNG/JPEG до 5 MiB после декодирования, без data URI) или image_id из предыдущего ответа. Тело запроса ограничено 7 MiB.

page по умолчанию 1, page_size по умолчанию 20 (1–50). Дополнительно: price={"min":...,"max":...} в CNY, sort.field=price|repurchase_rate|monthly_units_sold с direction=asc|desc, keyword, collection_id.

curl -X POST "https://bhapi.ru/analytics/1688/api/v1/products/search-by-image" \
  -H "X-API-Token: ВАШ_ТОКЕН_АНАЛИТИКИ" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://images.example.com/product.jpg","page":1,"page_size":20}'

{"status":"ok","data":{"items":[],"pagination":{"page":1,
  "page_size":20,"total":null},"image_id":null,"total_pages":null,
  "page_item_count":0},"meta":{"request_id":"пример-id",
  "retrieved_at":"2026-10-01T10:00:00Z","snapshot_date":null}}

{
  "offer_id": "745678901234",
  "title": "Термокружка",
  "product_url": "https://detail.1688.com/offer/745678901234.html",
  "image_url": "https://images.example.com/product.jpg",
  "price": {"amount": "20.00", "currency": "CNY", "estimated": false},
  "consign_price": null,
  "monthly_units_sold": 23,
  "estimated_monthly_sales": {
    "amount": "460.00", "currency": "CNY", "estimated": true
  },
  "one_piece_dropshipping": null,
  "repurchase_rate": null
}

В этом сокращённом фрагменте показаны отдельные поля одного data.items[]. Полный объект содержит также все остальные ключи из таблицы ниже, даже когда их значения равны null.

Для следующей страницы передайте data.image_id без изменений с тем же токеном. Это временный идентификатор BHAPI, действующий до одного часа. Если image_id равен null, можно снова отправить исходное изображение с нужным page; такой запрос может занять больше времени. pagination.total здесь всегда null; число результатов текущей страницы проверяйте по data.items и page_item_count, если оно заполнено.

Строковые проценты и оценки не имеют подтверждённой общей шкалы; месячные показатели требуют осторожной интерпретации. Метка патента не является юридическим заключением.

Ответы, единицы и ограничения

Все перечисленные поля успешного ответа присутствуют в JSON. Запись | null означает, что значение может быть null, а не что ключ пропускается.

{
  "status": "ok",
  "data": {
    "items": [{
      "offer_id": "745678901234", "title": "Термокружка",
      "product_url": null, "image_url": null,
      "price": {"amount": "20.00", "currency": "CNY", "estimated": false},
      "dropship_price": null, "min_order_quantity": 2, "unit": "шт",
      "available_date": null, "delivery_time": null,
      "company": null, "shop_id": null, "shop_url": null,
      "analytics": {"period": "rolling_30d", "orders": 18,
        "units_sold": 23, "estimated_sales": {
          "amount": "460.00", "currency": "CNY", "estimated": true}}
    }],
    "pagination": {"page": 1, "page_size": 10, "total": 1, "total_pages": null}
  },
  "meta": {"request_id": "пример-id", "retrieved_at": "2026-10-01T10:00:00Z", "snapshot_date": null}
}

Это синтетический пример, не измерение. orders — заказы, units_sold — единицы, а не выкупы. estimated_sales — оценочная денежная сумма. Money.amount — десятичная строка, currency может быть null; estimated указывает оценку. null означает отсутствие подтверждённого значения, не ноль. meta.snapshot_date=null означает неизвестную свежесть источника; retrieved_at — время получения BHAPI. pagination.total — сообщённое сервисом число в доступной выборке, не полный объём рынка.

Для Detail объект data содержит ровно один product; его поля приведены в разделе карточки товара. Для поиска по изображению структура data описана ниже.

Обычный 1688 возвращает поля карточек, цены, SKU и свойства; аналитика добавляет нормализованные показатели с явным периодом. В legacy поиске есть текстовая метка продаж, но она не заменяет периодные orders, units_sold и estimated_sales. Сопоставляйте товары в одном периоде; Search и Billboard используют разные типы периодов.

Ошибки, квоты и повторы

Таблицы и примеры этого раздела описывают ошибки legacy (формат по умолчанию). Чтобы получать единый контракт ошибок, передайте заголовок X-BHAPI-Error-Format: problem-v1. Статусы некоторых ошибок в этом режиме отличаются; успешные ответы не меняются. Общий справочник кодов, форматов и действий клиента →

Внешний вызов не повторяется автоматически. Повтор с вашей стороны является новым вызовом и может повлечь новый расход. Успешный проверенный ответ расходует одну единицу BHAPI; актуальные лимиты смотрите в тарифном меню и кабинете.