Partner API

Работа с External API

Через API можно получать товары из раздела Наличие в Китае: список с фильтрами, постраничную выдачу, карточку товара по ID и создавать бронь товара.

Base URL: https://madoauto.online/api/external/v1Формат: JSONЛимит: 120 запросов в минуту

Быстрый старт

Получите API-ключ у madoauto.

Передавайте ключ в заголовке каждого запроса.

Загружайте товары страницами через limit и offset. Для брони используйте id товара.

Авторизация

API-ключ можно передать одним из двух способов. Используйте тот вариант, который удобнее для вашей системы.

Authorization: Bearer <API_KEY>x-api-key: <API_KEY>

Endpoints

Метод	Path	Назначение
GET	/china-stock/products	Получить список товаров.
GET	/china-stock/products/{id}	Получить один товар по ID.
POST	/products/reservations	Создать бронь товара.

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

Все параметры необязательные. Если параметры не переданы, API вернет первую страницу товаров с настройками по умолчанию.

Параметр	Тип	Как использовать
limit	integer	Количество товаров на странице. По умолчанию 100, максимум 500.
offset	integer	Смещение для следующей страницы. По умолчанию 0.
createdSince	ISO date	Вернуть товары, созданные начиная с указанной даты.
updatedSince	ISO date	Вернуть товары, обновленные начиная с указанной даты.
search	string	Поиск по основным данным товара: название, артикул, код, деталь, бренд, модель.
brand	string	Фильтр по бренду.
model	string	Фильтр по модели.
categoryId	string	Фильтр по категории.
availability	enum	in-stock, in-transit или out-of-stock.

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

curl "https://madoauto.online/api/external/v1/china-stock/products?limit=100&offset=0&updatedSince=2026-05-01T00:00:00.000Z" \
  -H "Authorization: Bearer mado_xxxxxxxxxxxxxxxx_secret"

Ответ API

В списке товаров ответ содержит массив data, блок pagination и служебный блок meta. В карточке товара data содержит один объект товара.

Поля brand, model, year, engineVolume, horsepower, fuelType и transmission заполняются из доп. полей МойСклад, выбранных администратором.

Поле товара	Тип	Значение
id	string	ID товара.
numericId	number \| null	Дополнительный числовой ID, если есть.
url	string	Ссылка на карточку товара на сайте.
article	string	Артикул.
code	string	Код товара.
name	string	Название товара.
brand	string	Бренд.
model	string	Модель.
year	number \| null	Год автомобиля.
engineVolume	number \| null	Объем двигателя.
horsepower	number \| null	Мощность в лошадиных силах.
fuelType	string	Тип топлива.
transmission	string	Трансмиссия.
bodyCode	string	Код кузова.
partName	string	Название детали.
partLocation	string	Расположение детали.
partSide	string	Сторона детали.
category	object	Категория: id, numericId, name.
price	object	Цена: amount и currency. Валюта всегда CNY.
stock	object	Остатки: quantity, stock, available, status.
images	string[]	Ссылки на изображения.
videoUrl	string \| null	Ссылка на видео, если есть.
arrivalDate	YYYY-MM-DD \| null	Дата поступления, если известна.
createdAt	ISO date \| null	Дата создания.
updatedAt	ISO date \| null	Дата обновления.

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

{
  "data": [
    {
      "id": "product-1",
      "numericId": 123,
      "url": "https://madoauto.online/china-stock/product-1",
      "article": "A-1",
      "code": "C-1",
      "name": "Фара Toyota Camry",
      "brand": "Toyota",
      "model": "Camry",
      "year": 2020,
      "engineVolume": 2.5,
      "horsepower": 181,
      "fuelType": "Бензин",
      "transmission": "AT",
      "bodyCode": "XV70",
      "partName": "Фара",
      "partLocation": "Перед",
      "partSide": "Левая",
      "category": {
        "id": "category-1",
        "numericId": 12,
        "name": "Оптика"
      },
      "price": {
        "amount": 1500,
        "currency": "CNY"
      },
      "stock": {
        "quantity": 2,
        "stock": 1,
        "available": true,
        "status": "in_stock"
      },
      "images": [
        "https://cdn.example.com/products/1.jpg"
      ],
      "videoUrl": "https://disk.yandex.ru/i/example",
      "arrivalDate": null,
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-05-02T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 320,
    "hasMore": true
  },
  "meta": {
    "source": "china",
    "section": "china-stock",
    "currency": "CNY",
    "generatedAt": "2026-05-03T12:00:00.000Z"
  }
}

Пример запроса карточки

curl "https://madoauto.online/api/external/v1/china-stock/products/product-1" \
  -H "x-api-key: mado_xxxxxxxxxxxxxxxx_secret"

Бронь товара

Endpoint создает бронь на указанное количество товара. Используйте ID товара из поля data.id.

Поле	Тип	Как использовать
productId	string	Обязательный ID товара из поля data.id.
quantity	integer	Необязательно. Количество для брони. По умолчанию 1.
comment	string	Необязательно. Комментарий к брони, максимум 1000 символов.

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

curl -X POST "https://madoauto.online/api/external/v1/products/reservations" \
  -H "Authorization: Bearer mado_xxxxxxxxxxxxxxxx_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product-1",
    "quantity": 2,
    "comment": "Комментарий к брони"
  }'

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

{
  "reserved": true,
  "productId": "product-1",
  "quantity": 2,
  "reservationId": "reservation-1"
}

Если бронь не создана

При статусе 409 поле reason может быть out_of_stock, not_reservable или reservation_unavailable.

{
  "reserved": false,
  "reason": "out_of_stock"
}

Ошибки

HTTP	Что значит
400	Некорректный параметр запроса.
401	API-ключ не передан или недействителен.
404	Товар не найден.
409	Бронь не создана: товара нет в наличии, товар не подходит для брони или бронь временно недоступна.
429	Превышен лимит запросов. Повторите запрос после времени из заголовка Retry-After.
500	Временная ошибка API.

Пример ошибки

{
  "error": "Invalid API key"
}

Вопросы по интеграции

Если нужен ключ или помощь с подключением, свяжитесь с madoauto.

Контакты