Каталог и остатки
JSON API для каталога наличия: товары, категории, пакетное обновление остатков и цен. Ключ связи с вашей системой — external_id.
Это не импорт файла в модуль «Прайс-листы». Файл прайса: Прайс-листы.
Базовый префикс: /api/integrations/v1
Цены при записи — в копейках. Обозначения: Структура и обозначения.
Подходит для ERP / склада / учётной системы, которая выгружает номенклатуру и остатки в магазин.
Список товаров
GET /products — products.read
Query: since, per_page, cursor, external_id, article.
Snapshot (то же для GET /products/{id}):
{
"id": 100,
"external_id": "prod-1",
"name": "Колодки BOSCH",
"article": "0986AB1234",
"brand_id": 12,
"brand": "BOSCH",
"slug": "kolodki-bosch",
"is_active": true,
"description": null,
"image_source_mode": "download",
"images": [
{ "url": "https://…/photo1.jpg", "is_main": true, "sort_order": 1 }
],
"images_count": 1,
"has_images": true,
"updated_at": "2026-07-10T10:00:00+03:00"
}Перед upsert сначала читайте товар по external_id или id: если has_images: true, блок images в batch можно не передавать — существующие фото не затираются.
curl -sS "https://ВАШ_ДОМЕН/api/integrations/v1/products?external_id=prod-1" \
-H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
-H "Accept: application/json"curl -sS "https://ВАШ_ДОМЕН/api/integrations/v1/products/100" \
-H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
-H "Accept: application/json"Batch: категории
Upsert
POST /categories/batch-upsert — categories.write
Тело: массив категорий или { "categories": [ ... ] }.
| Поле | Обяз. | Описание |
|---|---|---|
external_id | да | Внешний id категории |
name | да | Название |
parent_external_id | нет | Родитель |
description / slug / sort_order / is_active / image_url | нет | Прочее |
200: { "processed", "created", "updated", "errors": [{ "external_id", "message" }] }
Удаление (деактивация)
POST /categories/delete — categories.delete Тело: { "external_ids": ["cat-1", "cat-2"] }200: { "requested", "deactivated", "not_found": [] }
Batch: товары
Upsert
POST /products/batch-upsert — products.write
Тело: массив или { "products": [ ... ] }.
| Поле | Обяз. | Описание |
|---|---|---|
external_id | да | Внешний id товара |
name | да | Название |
brand | нет | Бренд (создастся при необходимости) |
article | нет | Артикул |
category_external_id / category_external_ids | нет | Категории |
replace_categories | нет | Заменить набор категорий |
description_short / description_full | нет | Описания |
slug / sort_order / is_active | нет | Служебные |
attributes[] | нет | Атрибуты (name обязателен вместе с блоком); у атрибута можно external_id, group_external_id |
replace_attributes | нет | Заменить атрибуты |
images[] | нет | { "url", "sort_order?", "is_main?" } |
200: { "processed", "created", "updated", "errors": [...] }
curl -sS -X POST "https://ВАШ_ДОМЕН/api/integrations/v1/products/batch-upsert" \
-H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
-H "Content-Type: application/json" \
-d '{
"products": [
{
"external_id": "prod-1",
"name": "Колодки BOSCH",
"brand": "BOSCH",
"article": "0986AB1234",
"category_external_id": "cat-brakes",
"is_active": true
}
]
}'{
"processed": 1,
"created": 1,
"updated": 0,
"errors": []
}Удаление (soft-delete)
POST /products/delete — products.delete Тело: { "external_ids": ["prod-1"] }200: { "requested", "deactivated", "not_found": [] }
Остатки и цены
POST /stocks/batch-update — stocks.write
Тело: массив или объект:
{
"storage_id": 1,
"pick_up_point_id": 1,
"stocks": [
{
"product_external_id": "prod-1",
"quantity": 10,
"selling_price": 150000,
"purchase_price": 100000,
"old_price": 170000,
"delivery_days": 2
}
]
}| Поле | Обяз. | Описание |
|---|---|---|
stocks.*.product_external_id | да | Ищет товар по внешнему id |
stocks.*.quantity | да | Остаток ≥ 0 |
stocks.*.purchase_price / selling_price / old_price | нет | Копейки |
stocks.*.supply_date / delivery_days | нет | Поставка |
storage_id / pick_up_point_id | условно | В теле или в настройках API; оба должны быть известны, иначе 422 |
Ненайденный товар попадает в errors, HTTP при этом обычно остаётся 200.
curl -sS -X POST "https://ВАШ_ДОМЕН/api/integrations/v1/stocks/batch-update" \
-H "Authorization: Bearer pp_abc123:ВАШ_СЕКРЕТ" \
-H "Content-Type: application/json" \
-d '{
"storage_id": 1,
"pick_up_point_id": 1,
"stocks": [
{
"product_external_id": "prod-1",
"quantity": 10,
"selling_price": 150000,
"purchase_price": 100000
}
]
}'{
"processed": 1,
"updated": 1,
"errors": []
}