Integration API · Синхронізація каталогу

Створити або замінити товар

PUThttps://{store}/api/v1/integrations/catalog/products/{external_id}

Створює товар, коли external_id трапляється вперше, і далі оновлює той самий товар — повтор запиту ніколи не робить дубля. Новому товару потрібні name і sku; він отримує один варіант із цим артикулом, ціною й залишком.

Категорії й мітки зв’язуються за вашими external id, тож їх треба створити раніше; переданий список замінює зв’язки товару. image_url — публічне зображення за https; магазин завантажує його до себе.

Для товару в кількох кольорах чи розмірах передайте variants: кожен варіант зі своїм артикулом, ціною, залишком і опціями (однакові назви опцій у всіх варіантах). Список замінює варіанти товару: збіг за артикулом, нові додаються, відсутні видаляються; рядок без price чи quantity лишає варіанту його власні, новому варіанту потрібна ціна. Без variants товар має один варіант із sku, price і quantity.

Ключ інтеграції з правом catalog:write: Authorization: Bearer {key}.

Параметри шляху

external_idstringобов'язковий

Ваш id товару, незмінний між повторами (1–191 символ).

Тіло запиту application/json

namestring

Назва товару. Обов’язкова для нового товару.

skustring

Артикул варіанта товару. Обов’язковий для нового товару.

priceinteger

Ціна в копійках (599900 = 5 999,00).

quantityinteger

Залишок.

descriptionstring

Опис простим текстом.

statusstring

draft або published. За замовчуванням draft.

draftpublished

image_urlstring

Публічна https-адреса головного зображення.

category_external_idsarray of strings

Ваші id категорій; замінюють зв’язки.

tag_external_idsarray of strings

Ваші id міток; замінюють зв’язки.

attributesobject

Characteristics by name, such as {"Матеріал": ["Бавовна", "Льон"], "Вага": "180 г", "Водонепроникний": true}; null removes one, names not sent stay. For a store on the one attribute model; elsewhere tags carry characteristics.

variantsarray of objects

До 100 варіантів: sku (обов’язковий), price, quantity і options — об’єкт «назва опції → значення», наприклад {"Колір": "Чорний", "Розмір": "M"}. Якщо variants передано, sku, price і quantity верхнього рівня не використовуються.

Приклад

{
    "name": "Навушники Sonar ANC повнорозмірні",
    "description": "Активне шумозаглушення, 40 годин роботи.",
    "status": "published",
    "image_url": "https://cdn.example.com/sonar-anc.jpg",
    "category_external_ids": [
        "erp-cat-audio"
    ],
    "tag_external_ids": [
        "erp-tag-new"
    ],
    "variants": [
        {
            "sku": "SONAR-ANC-BLK",
            "price": 599900,
            "quantity": 24,
            "options": {
                "Колір": "Чорний"
            }
        },
        {
            "sku": "SONAR-ANC-WHT",
            "price": 599900,
            "quantity": 9,
            "options": {
                "Колір": "Білий"
            }
        }
    ]
}

Відповіді

200Товар, як його тепер показує каталог, і ваш external_id.

{
    "external_id": "erp-10045",
    "data": {
        "id": 12,
        "name": "Навушники Sonar ANC повнорозмірні",
        "description": "Активне шумозаглушення, 40 годин роботи.",
        "sku": "SONAR-ANC-BLK",
        "thumbnail_url": "https://your-store.storeforma.shop/media/12/sonar-anc.webp",
        "quantity": 24,
        "currency_code": "UAH",
        "min_price": 599900,
        "max_price": 599900,
        "weight": 0.32,
        "length": null,
        "height": null,
        "width": null,
        "has_offers": false,
        "is_archived": false,
        "category_id": 7,
        "attributes": [
            {
                "handle": "kolir",
                "name": "Колір",
                "type": "swatch",
                "unit": null,
                "group": null,
                "variant_axis": false,
                "values": [
                    "Чорний"
                ]
            },
            {
                "handle": "vaga",
                "name": "Вага",
                "type": "number",
                "unit": "г",
                "group": "Загальні",
                "variant_axis": false,
                "values": [
                    "320 г"
                ]
            }
        ],
        "input_options": [
            {
                "key": "hraviiuvannia",
                "label": "Гравіювання",
                "type": "text",
                "required": false,
                "price": 10000,
                "max": 30,
                "choices": []
            }
        ],
        "created_at": "2026-10-01 10:12:00",
        "updated_at": "2026-10-12 08:40:00"
    }
}

401Ключа немає, він невідомий або відкликаний.

{
    "code": "unauthenticated",
    "message": "Integration key is inactive.",
    "field": null
}

403У ключа немає права catalog:write, або тариф магазину без доступу до API.

{
    "code": "forbidden",
    "message": "Integration key cannot catalog:write.",
    "field": null
}

422Поле має помилку; його назва — у field.

{
    "code": "validation_error",
    "message": "name is required.",
    "field": "name"
}

429Понад 60 запитів за хвилину для цього ключа. Зачекайте Retry-After секунд.

{
    "code": "rate_limited",
    "message": "Too many integration requests.",
    "field": null
}