Рефсейлс API
Товары

Создать товар

POST
/api/v1/products

Создаёт товар. Обязательны name и price. Цена в копейках. Категорию укажите через categoryId или categoryExternalId. Действует лимит товаров тарифа. Для синхронизации по своему ID удобнее PUT /api/v1/products/external/{externalId}: его можно повторять. Право: products:write.

Авторизация

bearerApiKey
headerАвторизацияBearer <ключ>

Ключ API в заголовке Authorization: Bearer rsk_live_…. Ключ создаёт владелец магазина: Настройки → Интеграции → API-ключи.

Тело запроса

application/json
  1. body
name*string

Название, от 3 до 200 символов.

Length3 <= length <= 200
description?|

Описание, HTML или текст.

price*integer

Цена в копейках.

Range0 <= value <= 2000000000
stockQuantity?integer

Остаток.

Range0 <= value <= 100000000
sku?|

Артикул, уникален в магазине. null снимает артикул.

categoryId?|

ID категории из GET /api/v1/references/categories. null убирает товар из категории.

categoryExternalId?string

Категория по её externalId. Удобно при синхронизации: не нужно хранить наши ID. Вместе с categoryId не передаётся.

Length1 <= length <= 255
url?|

Страница товара на сайте магазина.

imageUrl?|

Главное изображение.

weightGrams?|

Вес в граммах.

widthCm?|

Ширина упаковки, см.

heightCm?|

Высота упаковки, см.

depthCm?|

Длина упаковки, см.

externalId?string

ID товара в вашей системе, уникален в магазине. Для повторяемой синхронизации удобнее PUT /api/v1/products/external/{externalId}.

Length1 <= length <= 255

Ответ

Товар создан.

application/json
  1. response
data*
curl -X POST "https://example.com/api/v1/products" \  -H "Content-Type: application/json" \  -d '{    "externalId": "MS-00125",    "name": "Свеча ароматическая «Лаванда», 200 г",    "price": 120000,    "stockQuantity": 20,    "sku": "CNDL-200-LAV",    "categoryExternalId": "MS-CAT-7",    "weightGrams": 350  }'
{  "data": {    "id": "dcd53ddb-8104-4e48-8cc0-5df1c5a0d1e2",    "externalId": "MS-00124",    "sku": "CNDL-200-PINE",    "name": "Свеча ароматическая «Хвоя», 200 г",    "description": "Соевый воск, хлопковый фитиль, горит 40 часов.",    "price": 120000,    "stockQuantity": 34,    "categoryId": "5b2e8d1a-7c3f-4e9a-b0d6-1f4a8c2e9b73",    "categoryName": "Свечи",    "parentId": null,    "variantAttributes": null,    "url": "https://candles.ru/tproduct/124-hvoya",    "imageUrl": "https://static.tildacdn.com/tild3139/hvoya.jpg",    "weightGrams": 350,    "widthCm": 9,    "heightCm": 11,    "depthCm": 9,    "createdAt": "2026-05-04T12:00:00.418265+00:00",    "updatedAt": "2026-09-20T08:15:42.418265+00:00"  }}

Получить товар GET

Один товар. Ищет по ID Рефсейлс, а с by=externalId или by=sku по внешнему ID или артикулу. Если совпадений несколько, вернётся самый старый товар. Право: products:read.

Создать или обновить товар по внешнему ID PUT

Главный метод синхронизации каталога. Если товара с таким externalId нет, создаёт его: тогда нужны name и price. Если есть, меняет только переданные поля. Запрос можно повторять сколько угодно. Товар из YML-фида с тем же externalId при следующем импорте перезапишется данными фида. Право: products:write.