1688 v2: актуальные эндпоинты портала

API 1688 v2 предназначен для получения карточек товаров, описаний, отзывов, доставки, данных магазинов, категорий и результатов поиска по каталогу 1688. Публичный префикс маршрутов на портале: /1688/api/v2.

Версия v2 не заменяет документацию /1688/api/v1/...: это отдельный набор маршрутов с другим набором полей запроса и ответа. Для новых интеграций по карточкам, магазинам и каталогу используйте v2.

Авторизация

Во все запросы передавайте API-токен портала, выпущенный для парсера 1688. Рекомендуемый способ - заголовок X-API-Token. Альтернативно можно передать токен query-параметром apiToken.

Заголовок

X-API-Token: ВАШ_API_TOKEN

Список маршрутов 1688 v2

Метод	Путь	Назначение	Ключевые поля
`POST`	`/1688/api/v2/item/detail`	Детальная карточка товара по ID.	`item_id`, `language`, `scene`
`POST`	`/1688/api/v2/item/detail-by-url`	Детальная карточка товара по URL.	`url`, `language`, `scene`
`POST`	`/1688/api/v2/item/desc`	Изображения и блоки описания товара.	`item_id`
`POST`	`/1688/api/v2/item/ratings`	Отзывы и оценки товара.	`item_id`, `page`, `sort_type`
`POST`	`/1688/api/v2/item/shipping-fee`	Расчет доставки по товару.	`item_id`, `province`, `total_quantity`
`POST`	`/1688/api/v2/search/factories`	Поиск фабрик по ключевому слову.	`keywords`, `page`, `page_size`
`POST`	`/1688/api/v2/shop/items`	Товары выбранного магазина.	`shop_url`, `page`, `page_size`
`POST`	`/1688/api/v2/shop/info`	Информация о магазине.	`shop_url` или `member_id`
`POST`	`/1688/api/v2/shop/categories`	Категории магазина.	`shop_url` или `member_id`
`POST`	`/1688/api/v2/category/info`	Информация о категории.	`cat_id`
`POST`	`/1688/api/v2/category/items`	Товары категории.	`cat_id`, `page`, `page_size`
`POST`	`/1688/api/v2/cross-border/search-by-image`	Поиск товаров по изображению.	`img_url`, `language`, фильтры
`POST`	`/1688/api/v2/cross-border/search-by-keyword`	Поиск товаров по ключевому слову или категории.	`keyword` или `cat_id`, фильтры

Товар

Детальная карточка по ID

POST /1688/api/v2/item/detail

Поле	Тип	Обязательное	Описание
`item_id`	integer	да	ID товара 1688.
`language`	string	нет	Язык ответа, по умолчанию `zh`. Часто используются `zh`, `en`, `ru`.
`scene`	string	нет	Оставьте пустым или передайте `drop_shipping`.
`optimize_title`	boolean	нет	Если `true`, заголовок может быть дополнительно подготовлен для карточки.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/item/detail" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "item_id": 652702302959,
    "language": "ru"
  }'

Детальная карточка по URL

POST /1688/api/v2/item/detail-by-url

Поле	Тип	Обязательное	Описание
`url`	string	да	Полная ссылка на карточку товара 1688.
`language`	string	нет	Язык ответа, по умолчанию `zh`.
`scene`	string	нет	Оставьте пустым или передайте `drop_shipping`.
`optimize_title`	boolean	нет	Если `true`, заголовок может быть дополнительно подготовлен для карточки.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/item/detail-by-url" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "url": "https://detail.1688.com/offer/652702302959.html",
    "language": "ru"
  }'

Описание товара

POST /1688/api/v2/item/desc

Возвращает блоки описания и изображения для карточки товара.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/item/desc" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "item_id": 652702302959
  }'

Отзывы товара

POST /1688/api/v2/item/ratings

Поле	Тип	Обязательное	Описание
`item_id`	integer	да	ID товара 1688.
`page`	integer	нет	Номер страницы, по умолчанию `1`.
`sort_type`	string	нет	Сортировка отзывов, по умолчанию `default`.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/item/ratings" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "item_id": 652702302959,
    "page": 1,
    "sort_type": "default"
  }'

Расчет доставки

POST /1688/api/v2/item/shipping-fee

Поле	Тип	Обязательное	Описание
`item_id`	integer	да	ID товара 1688.
`province`	string	да	Провинция доставки.
`total_quantity`	integer	нет	Количество единиц товара, по умолчанию `1`.
`total_weight`	number	нет	Общий вес, если он нужен для расчета.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/item/shipping-fee" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "item_id": 652702302959,
    "province": "Guangdong",
    "total_quantity": 10
  }'

Магазин

Товары магазина

POST /1688/api/v2/shop/items

Поле	Тип	Обязательное	Описание
`shop_url`	string	да	URL магазина 1688.
`page`	integer	нет	Номер страницы, по умолчанию `1`.
`page_size`	integer	нет	Размер страницы: от `1` до `20`, по умолчанию `20`.
`sort`	string	нет	Сортировка, по умолчанию `default`.
`cat`, `cat_type`	string	нет	Фильтр по категории магазина.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/shop/items" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "shop_url": "https://shop9520c699v9334.1688.com",
    "page": 1,
    "page_size": 20
  }'

Информация о магазине

POST /1688/api/v2/shop/info

Передайте shop_url или member_id. Хотя бы одно поле обязательно.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/shop/info" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "shop_url": "https://shop9520c699v9334.1688.com"
  }'

Категории магазина

POST /1688/api/v2/shop/categories

Передайте shop_url или member_id. Хотя бы одно поле обязательно.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/shop/categories" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "member_id": "b2b-2201234567890abcdef"
  }'

Каталог и поиск

Поиск фабрик

POST /1688/api/v2/search/factories

Поле	Тип	Обязательное	Описание
`keywords`	string	да	Поисковый запрос.
`page`	integer	нет	Номер страницы, по умолчанию `1`.
`page_size`	integer	нет	Размер страницы: от `1` до `20`.
`sort`	string	нет	Сортировка, по умолчанию `default`.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/search/factories" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "keywords": "phone case factory",
    "page": 1,
    "page_size": 20
  }'

Информация о категории

POST /1688/api/v2/category/info

Передайте cat_id, если нужно получить данные по конкретной категории.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/category/info" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "cat_id": 1031917
  }'

Товары категории

POST /1688/api/v2/category/items

Поле	Тип	Обязательное	Описание
`cat_id`	integer	да	ID категории.
`language`	string	нет	Язык ответа, по умолчанию `en`.
`page`, `page_size`	integer	нет	Пагинация. `page_size` от `1` до `20`.
`sort`	string	нет	Сортировка, по умолчанию `default`.
`price_start`, `price_end`	string	нет	Фильтр по цене.
`new_arrival`	boolean	нет	Только новые товары.
`support_dropshipping`	boolean	нет	Товары с поддержкой дропшиппинга.
`free_shipping`	boolean	нет	Товары с бесплатной доставкой.
`is_super_factory`	boolean	нет	Только супер-фабрики.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/category/items" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "cat_id": 1031917,
    "language": "en",
    "page": 1,
    "page_size": 20,
    "support_dropshipping": true
  }'

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

POST /1688/api/v2/cross-border/search-by-image

Поле	Тип	Обязательное	Описание
`img_url`	string	да	Публичная ссылка на изображение товара.
`language`	string	нет	Язык ответа, по умолчанию `en`.
`page`, `page_size`	integer	нет	Пагинация. `page_size` от `1` до `20`.
`sort`	string	нет	Сортировка, по умолчанию `default`.
`price_start`, `price_end`	string	нет	Фильтр по цене.
`support_dropshipping`, `is_factory`, `verified_supplier`, `free_shipping`, `new_arrival`	boolean	нет	Дополнительные фильтры выдачи.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/cross-border/search-by-image" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "img_url": "https://example.com/product.jpg",
    "language": "en",
    "page": 1,
    "page_size": 20,
    "verified_supplier": true
  }'

Поиск по ключевому слову или категории

POST /1688/api/v2/cross-border/search-by-keyword

Поле	Тип	Обязательное	Описание
`keyword`	string	условно	Поисковая фраза. Передайте `keyword` или `cat_id`.
`cat_id`	integer	условно	ID категории. Передайте `keyword` или `cat_id`.
`language`	string	нет	Язык ответа, по умолчанию `en`.
`page`, `page_size`	integer	нет	Пагинация. `page_size` от `1` до `20`.
`sort`	string	нет	Сортировка, по умолчанию `default`.
`price_start`, `price_end`	string	нет	Фильтр по цене.
`new_arrival`, `support_dropshipping`, `free_shipping`, `is_super_factory`	boolean	нет	Дополнительные фильтры выдачи.

cURL

curl -X POST "https://bhapi.ru/1688/api/v2/cross-border/search-by-keyword" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "keyword": "phone case",
    "language": "en",
    "page": 1,
    "page_size": 20,
    "support_dropshipping": true
  }'

Формат ответа

Успешный запрос возвращает JSON-объект со служебным статусом и данными результата. Конкретные поля внутри data.data зависят от выбранного маршрута: карточка товара, список товаров, отзывы, доставка, магазин или категория.

JSON

{
  "status": "ok",
  "data": {
    "code": 200,
    "msg": "success",
    "data": {
      "...": "данные выбранного эндпоинта"
    }
  }
}

Для списковых запросов ответ обычно содержит массив товаров или категорий и данные пагинации. Для запросов по одному товару или магазину ответ содержит один объект с найденными полями.

Ошибки и лимиты

HTTP	Когда возникает
`401`	Не передан `apiToken` или `X-API-Token`.
`403`	Токен не относится к парсеру 1688, отключён или у пользователя нет активного доступа по тарифу.
`422`	Некорректное тело запроса: отсутствуют обязательные поля, нарушены ограничения или не выполнено условие выбора одного из полей.
`429`	Исчерпан дневной, общий или месячный лимит запросов.
`500`	Внутренняя ошибка портала при обработке запроса.
`502`	Ответ не удалось обработать как корректный JSON.
`503`	Парсер временно недоступен или вернул ошибку обработки.

Лимиты проверяются до выполнения запроса. Если вы получили 429, проверьте дневной лимит токена, общий лимит токена и месячную квоту тарифа.