Ozon: получить карточку товара по URL

Метод возвращает данные одной карточки Ozon. Для вызова нужен отдельный API-токен Ozon.

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

Заголовки и тело запроса

Обязательные данные запроса
Место	Имя	Значение
Заголовок	`X-API-Token`	API-токен BHAPI для Ozon.
Заголовок	`Content-Type`	`application/json`.
JSON body	`url`	Полный URL карточки товара Ozon, строка до 4096 символов. Другие поля не принимаются.

Принимается только HTTPS-адрес на ozon.ru или www.ozon.ru с путём /product/<название>-<числовой ID>/. Номер порта можно опустить либо указать 443. Параметры после ? удаляются, домен приводится к www.ozon.ru, завершающий слеш добавляется. Короткие ссылки, другие домены, фрагмент после # и URL с учётными данными отклоняются.

JSON body

{"url":"https://www.ozon.ru/product/primer-tovara-123456789/"}

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

HTTP 200 содержит status: "ok" и один объект data. Идентификаторы и цены передаются строками; отсутствующие необязательные значения представлены null, списки — пустыми массивами.

Синтетический пример JSON

{
  "status": "ok",
  "data": {
    "item_id": "123456789",
    "product_url": "https://www.ozon.ru/product/primer-tovara-123456789/",
    "title": "Пример товара",
    "currency": "RUB",
    "brand": "Пример бренда",
    "price_info": {
      "sale_price": "1517",
      "normal_sale_price": "1685",
      "origin_price": null
    },
    "main_imgs": ["https://ir.ozone.ru/example/item.jpg"],
    "video_url": null,
    "category_id": "31510",
    "category_path": [{"name": "Бытовая техника"}],
    "product_props": [{"name": "Тип", "value": "Аксессуар"}],
    "shop_info": {
      "shop_name": "Пример магазина",
      "shop_logo": "https://ir.ozone.ru/example/shop.png"
    },
    "review_info": {"rating_star": 4.7, "review_count": 18},
    "desc": "Описание товара",
    "sku_props": [{
      "prop_name": "Размер",
      "pid": "100",
      "values": [{"vid": "101", "name": "M", "imageUrl": null}]
    }],
    "skus": [{
      "skuid": "123456789",
      "sale_price": "1517",
      "origin_price": "1685"
    }]
  }
}

Поля объекта data
Поле	Тип	Описание
`item_id`	string	Положительный числовой ID товара.
`product_url`	string	Канонический HTTPS URL карточки.
`title`	string	Название товара.
`currency`, `brand`	string \| null	Валюта и бренд.
`price_info`	object	`sale_price`, `normal_sale_price`, `origin_price`: десятичная строка или null.
`main_imgs`	array[string]	HTTPS URL изображений.
`video_url`	string \| null	HTTPS URL видео.
`category_id`	string \| null	ID категории.
`category_path`	array[object]	Цепочка категорий: объекты `{name: string}`.
`product_props`	array[object]	Характеристики: объекты `{name: string, value: string}`.
`shop_info`	object \| null	`shop_name`: string или null; `shop_logo`: HTTPS URL или null.
`review_info`	object	`rating_star`: число от 0 до 5 или null; `review_count`: неотрицательное целое или null.
`desc`	string \| null	Описание товара.
`sku_props`	array[object]	`prop_name`, `pid` и `values`: массив объектов с `vid`, `name`, `imageUrl` (HTTPS URL или null).
`skus`	array[object]	`skuid`, `sale_price`, `origin_price`; цены — строка или null.

Ошибки

Коды ответа метода Ozon
HTTP	Причина	Когда возникает
422	`invalid_request`	Некорректный JSON body или URL товара.
401 / 403	Общая авторизация BHAPI	Нет токена, токен недействителен или не подходит для Ozon.
429	Общие лимиты BHAPI	Превышен лимит запросов или квота тарифа.
503	`upstream_unavailable`, `upstream_unreachable`	Сервис временно недоступен.
504	`upstream_timeout`	Превышено время ожидания.
502	`upstream_invalid_response`	Получен некорректный ответ сервиса.

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

Доступ и объём успешных запросов определяются тарифом Ozon в кабинете BHAPI. Успешная карточка учитывается как один запрос. Некорректный URL и ошибка получения карточки не расходуют квоту успешных запросов. При исчерпании квоты или лимита запросов возвращается 429.

Пример cURL

cURL

curl -X POST "https://bhapi.ru/ozon/api/v1/item/detail-by-url" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.ozon.ru/product/primer-tovara-123456789/"}'

Пример Python

Python

import requests

response = requests.post(
    "https://bhapi.ru/ozon/api/v1/item/detail-by-url",
    headers={"X-API-Token": "ВАШ_API_TOKEN"},
    json={"url": "https://www.ozon.ru/product/primer-tovara-123456789/"},
    timeout=100,
)
response.raise_for_status()
print(response.json()["data"]["title"])

Пример JavaScript

JavaScript

const response = await fetch("https://bhapi.ru/ozon/api/v1/item/detail-by-url", {
  method: "POST",
  headers: {"X-API-Token": "ВАШ_API_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({url: "https://www.ozon.ru/product/primer-tovara-123456789/"})
});
if (!response.ok) throw new Error("Ошибка API: " + response.status);
const result = await response.json();
console.log(result.data.title);

Пример PHP

PHP

<?php
$ch = curl_init("https://bhapi.ru/ozon/api/v1/item/detail-by-url");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Token: ВАШ_API_TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://www.ozon.ru/product/primer-tovara-123456789/"
    ]),
    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);
}
$result = json_decode($body, true);
echo $result["data"]["title"];