Taobao: карточка товара по ID

GET /taobao/api/v1/item/detail-by-id

Получите карточку товара по числовому идентификатору. Для вызова нужен API-токен BHAPI с доступом к парсеру Taobao. Ответ соответствует схеме карточки товара.

Параметры и заголовки

Входные данные карточки по ID
Где	Имя	Обязательный	Описание
Query	`item_id`	Да	Положительное число из 1–20 ASCII-цифр, передаваемое строкой. Ведущие нули удаляются. Это единственный допустимый query-параметр.
Заголовок	`X-API-Token`	Да	Ваш API-токен для Taobao. Передавайте его в заголовке.

Пример запроса

cURL

curl "https://bhapi.ru/taobao/api/v1/item/detail-by-id?item_id=123456789" \
  -H "X-API-Token: ВАШ_API_TOKEN"

Успешный ответ 200 OK

JSON · синтетические данные

{
  "status": "ok",
  "data": {
    "item_id": "123456789",
    "product_url": "https://item.taobao.com/item.htm?id=123456789",
    "title": "Пример товара",
    "currency": "CNY",
    "price_info": {"sale_price": "73.40", "origin_price": null},
    "main_imgs": ["https://img.example.org/product-1.jpg"],
    "video_url": null,
    "category_id": "70000123",
    "product_props": [{"name": "Цвет", "value": "Синий"}],
    "shop_info": {"shop_id": "987654", "shop_name": "Пример магазина", "shop_url": "https://shop.example.org"},
    "review_info": {"rating_star": null, "review_count": null},
    "sku_props": [{"prop_name": "Цвет", "pid": "9001", "values": [{"vid": "1", "name": "Синий", "image_url": null}]}],
    "skus": [{"sku_id": "555555", "sale_price": "73.40", "origin_price": null, "stock": 17, "props_ids": "9001:1"}]
  }
}

Идентификаторы и цены в ответе представлены строками. Необязательные значения могут быть null, а отсутствующие списки возвращаются как [].

Taobao: карточка товара по URL

POST /taobao/api/v1/item/detail-by-url

Получите ту же схему карточки по ссылке на товар. В ответе URL приводится к каноническому виду с одним параметром id.

Параметры и заголовки

Входные данные карточки по URL
Где	Имя	Обязательный	Описание
JSON body	`url`	Да	HTTPS URL товара. В объекте JSON разрешено только поле `url`; максимум 4096 символов.
Заголовок	`Content-Type`	Да	`application/json`. Максимальный размер тела — 16 КиБ.
Заголовок	`X-API-Token`	Да	Ваш API-токен для Taobao.

Допустимые ссылки. Домены: item.taobao.com, detail.tmall.com, detail.tmall.hk, chaoshi.detail.tmall.com. Путь: /item.htm или /item.html. Требуется ровно один параметр id с положительным ID из 1–20 цифр. Другие параметры ссылки удаляются. Короткие ссылки, редиректы, фрагменты и URL с учётными данными не принимаются.

Пример запроса

cURL

curl -X POST "https://bhapi.ru/taobao/api/v1/item/detail-by-url" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://item.taobao.com/item.htm?id=123456789"}'

Успешный ответ 200 OK

JSON · сокращённый пример

{
  "status": "ok",
  "data": {
    "item_id": "123456789",
    "product_url": "https://item.taobao.com/item.htm?id=123456789",
    "title": "Пример товара",
    "currency": "CNY",
    "price_info": {"sale_price": "73.40", "origin_price": null},
    "main_imgs": ["https://img.example.org/product-1.jpg"],
    "video_url": null,
    "category_id": "70000123",
    "product_props": [],
    "shop_info": null,
    "review_info": {"rating_star": null, "review_count": null},
    "sku_props": [],
    "skus": []
  }
}

Taobao: изображения описания по ID

GET /taobao/api/v1/item/description-by-id

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

Параметры и заголовки

Входные данные изображений описания
Где	Имя	Обязательный	Описание
Query	`item_id`	Да	Положительное число из 1–20 ASCII-цифр; единственный допустимый query-параметр.
Заголовок	`X-API-Token`	Да	Ваш API-токен для Taobao.

Пример запроса

cURL

curl "https://bhapi.ru/taobao/api/v1/item/description-by-id?item_id=123456789" \
  -H "X-API-Token: ВАШ_API_TOKEN"

Успешный ответ 200 OK

JSON · синтетические данные

{
  "status": "ok",
  "data": {
    "item_id": "123456789",
    "detail_imgs": ["https://img.example.org/detail-1.jpg"]
  }
}

Если изображений нет, detail_imgs содержит пустой массив.

Схема карточки товара

Оба метода карточки возвращают объект data в обёртке {"status":"ok","data":{...}}.

Основные данные и медиа

Основные поля карточки Taobao
Поле data	Тип	Описание
`item_id`	string	Канонический ID товара.
`product_url`	string	Канонический HTTPS URL товара с тем же ID.
`title`	string	Непустое название товара.
`currency`	string \| null	Код валюты, если доступен.
`category_id`	string \| null	ID категории, если доступен.
`main_imgs`	array[string]	HTTPS URL основных изображений.
`video_url`	string \| null	HTTPS URL видео, если доступно.

Цена, свойства и варианты

Цена и варианты товара Taobao
Поле data	Тип	Описание
`price_info`	object	`sale_price` и `origin_price`: неотрицательная десятичная строка или `null`.
`product_props`	array[object]	Характеристики `{name: string, value: string}`.
`sku_props`	array[object]	`prop_name` — название свойства, `pid` — строковый ID; `values` содержит варианты `{vid, name, image_url}`. URL изображения может быть `null`.
`skus`	array[object]	`sku_id` — строковый ID; `sale_price` и `origin_price` — строки или `null`; `stock` — неотрицательное целое или `null`; `props_ids` — строка или `null`.

Магазин и отзывы

Данные магазина и отзывов Taobao
Поле data	Тип	Описание
`shop_info`	object \| null	`shop_id` и `shop_name` — строки или `null`; `shop_url` — HTTPS URL или `null`.
`review_info`	object	`rating_star` — число от 0 до 5 или `null`; `review_count` — неотрицательное целое или `null`.

Схема описания

Объект data в успешном ответе метода описания содержит только два поля.

Поля описания Taobao
Поле data	Тип	Описание
`item_id`	string	Канонический ID запрошенного товара.
`detail_imgs`	array[string]	HTTPS URL изображений описания; может быть пустым массивом.

При 429 parser_overloaded парсер перегружен. Увеличьте интервал между запросами и выдержите Retry-After (1–3600 секунд) перед повтором. Ответ содержит Cache-Control: no-store; неуспешный вызов не расходует успешную квоту. Общие 429 токена и тарифа сохраняют прежнюю форму.

Ошибки и действия

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

Ошибки метода возвращаются в detail с полями code, reason и message. Общие ошибки авторизации и лимитов BHAPI могут не содержать reason; для них ориентируйтесь на HTTP-код и message.

Коды ошибок и рекомендуемые действия
HTTP	Причина	Что делать
401 / 403	Токен отсутствует или нет доступа к Taobao.	Проверьте `X-API-Token` и доступ токена к парсеру в кабинете.
404	`item_not_found`	Товар не найден или недоступен. Проверьте ссылку или ID; неуспешный вызов не расходует успешную квоту.
413	`request_too_large`	Сократите JSON body до 16 КиБ.
415	`unsupported_media_type`	Для POST укажите `Content-Type: application/json`.
422	`invalid_request`	Для GET оставьте только `item_id`; для POST проверьте товарный URL и единственное поле JSON `url`.
429	`parser_overloaded` или лимит токена/тарифа.	Для перегрузки снизьте частоту и выдержите `Retry-After`; для квоты проверьте кабинет.
502	`upstream_invalid_response`	Повторите позже; если ошибка сохраняется, передайте в поддержку время запроса и его путь.
503	`upstream_unavailable`, `upstream_unreachable`, `upstream_access_restricted` или `parser_internal_error`	Сервис временно недоступен; повторите позже.
504	`upstream_timeout`	Время ожидания истекло; повторите запрос позже.
500	`internal_error`	Если ошибка повторяется, обратитесь в поддержку и укажите время и путь запроса.

Квоты и учёт запросов

Каждый успешный вызов любого из трёх методов учитывается как один успешный запрос. Ошибки не расходуют квоту успешных запросов. Доступность парсера и конкретные лимиты зависят от вашего токена и тарифа; проверьте их в кабинете BHAPI.

Пример Python

Python · карточка по ID

import requests

response = requests.get(
    "https://bhapi.ru/taobao/api/v1/item/detail-by-id",
    params={"item_id": "123456789"},
    headers={"X-API-Token": "ВАШ_API_TOKEN"},
    timeout=100,
)
response.raise_for_status()
print(response.json()["data"]["title"])

Пример JavaScript

JavaScript · изображения описания

const response = await fetch("https://bhapi.ru/taobao/api/v1/item/description-by-id?item_id=123456789", {
  headers: {"X-API-Token": "ВАШ_API_TOKEN"}
});
if (!response.ok) throw new Error("Ошибка API: " + response.status);
console.log((await response.json()).data.detail_imgs);

Пример PHP

PHP · карточка по ID

<?php
$ch = curl_init("https://bhapi.ru/taobao/api/v1/item/detail-by-id?item_id=123456789");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-API-Token: ВАШ_API_TOKEN"],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 100
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($body === false || $status !== 200) throw new RuntimeException("Ошибка API: " . $status);
echo json_decode($body, true)["data"]["title"];