Shopcore AI API: підключення та всі методи

AI API Shopcore — це один шлюз до дозволених дій магазину. Агент не отримує доступу до Python, бази даних, файлової системи чи сервера: він бачить лише методи нижче та їхні параметри.

Для AI-агента: ця стаття пояснює архітектуру й правила. Перед роботою завжди отримай живий каталог через GET /ai/v1/methods/. Не вигадуй назви методів або параметрів. Спочатку використовуй read-методи з низьким ризиком; для небезпечних дій отримай явне підтвердження власника.

Де взяти доступ

Новий магазин

На екрані онбордингу залиште модуль «API для AI-агентів» увімкненим.
Відкрийте випадаючу секцію «Доступ для AI-агента».
Скопіюйте готовий промпт або повний токен і передайте лише агенту, якому довіряєте.

Якщо вимкнути AI-модуль на онбордингу, секція доступу зникне, а після збереження API буде вимкнений і на сайті.

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

В адмінці Hive відкрийте Налаштування сайту.
Переконайтеся, що останній тумблер «API для AI-агентів» увімкнений.
Відкрийте секцію «Доступ для AI-агента». Тут можна побачити ідентифікатор, скопіювати промпт і перегенерувати токен; попередній токен одразу перестане діяти.

Ідентифікатор ключа — несекретна службова мітка для журналу, розпізнавання та відкликання ключа. Окремо він показується в налаштуваннях Hive й не дає доступу сам по собі. Токен — секрет; саме він авторизує запити.

Як працює API

Спочатку агент читає актуальний manifest:

GET https://<ваш-hive-host>/ai/v1/methods/
Authorization: Bearer <ваш-токен>

Manifest можна фільтрувати параметрами group, access і risk. Він повертає ієрархію груп, доступність модулів, schema параметрів, ризик, потребу підтвердження та побічні ефекти.

Усі дії виконуються через один шлюз:

POST https://<ваш-hive-host>/ai/v1/invoke/
Authorization: Bearer <ваш-токен>
Content-Type: application/json

{
  "method": "system.status",
  "params": {},
  "options": {"confirmed": false}
}

Для завантаження файлів використовуйте multipart/form-data: поля method, params_json, options_json та названі файлові поля, описані вибраним методом.

Відповідь і контекст

Успішна відповідь містить ok, status, request_id, назву методу, ризик, версію каталогу, data і контекст магазину. Дані предметної області повертаються в data; якщо їх немає, агент має викликати відповідний read-метод, а не вгадувати стан.

{
  "ok": true,
  "status": "success",
  "request_id": "...",
  "method": "system.status",
  "data": {},
  "context": {"shop": {"id": 1, "public_url": "https://..."}}
}

Ризики й підтвердження

Рівень	Правило агента
`low`	Безпечне читання або вузька оборотна зміна.
`medium`	Перевірити поточний стан read-методом і пояснити наслідок.
`high`	Показати користувачу конкретну дію та отримати явне підтвердження.
`dynamic`	Ризик залежить від параметрів; наприклад HTML, індексація або реквізити вимагають підтвердження.

Для методів із confirmation: required шлюз не виконає дію без options.confirmed=true. Кожен виклик записується в журнал із request ID; токени, паролі й секрети автоматично приховуються.

Критичні правила предметної області

Товари й автоімпорт

Перед будь-якою ручною зміною товару викличте exchange.auto_import.get. Якщо is_active=true, will_update_existing_products=true і потрібне поле є в managed_fields, наступний автоімпорт може перетерти зміну.

Агент має показати власнику три варіанти: продовжити разово з підтвердженням, змінити/вимкнути мапінг автоімпорту або не виконувати ручну зміну.

Склад і наявність

Коли модуль складу ввімкнений, catalog.products.update технічно відхиляє patch.warehouse_count. Правильний шлях: warehouse.stock.list → warehouse.revisions.create → перевірка через warehouse.revisions.get → підтверджене warehouse.revisions.post.

Блоки та власний HTML

Спочатку шукайте готовий тип через pages.blocks.catalog. Якщо потрібного візуального блока немає, дані слід вивести стандартними data-блоками, а html_code використати поверх них для власного UI.

HTML-блок не дає доступу до Python, backend або нових приватних даних. Створення й редагування HTML потребують явного підтвердження.

Каталог методів: 137

Нижче — повний знімок каталогу для людей і агентів. Живий manifest має пріоритет, якщо версії відрізняються. catalog_version: 2026-09-08.3

Система (4)

Стан і можливості (2)

read Ризик: low

`system.overview` — Огляд даних магазину

Що робить: Дає компактні лічильники каталогу, сторінок, замовлень, клієнтів і журналу AI без завантаження самих записів.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.capabilities

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`system.status` — Стан магазину

Що робить: Повертає ідентичність магазину, публічний URL, стан підписки та модулів.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`public`, `shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.capabilities

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Журнал AI (2)

read Ризик: medium

`audit.requests.get` — Деталі AI-запиту

Що робить: Повертає один запис журналу з автоматично прихованими секретами.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: ai.audit_log

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "request_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`audit.requests.list` — Список AI-запитів

Що робить: Повертає журнал викликів цього магазину з фільтрами за методом і статусом; вміст запитів не включає.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: ai.audit_log

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "method": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "running",
        "success",
        "error"
      ]
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Каталог (32)

Категорії (5)

write Ризик: medium Підтвердження: recommended

`catalog.categories.create` — Створити категорію

Що робить: Створює категорію у наявному MPTT-дереві; slug генерується автоматично, якщо не переданий.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`catalog_tree_changed`

Додатковий контекст для AI

Що зачіпає: catalog.categories, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

catalog.categories.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "parent_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "number": {
      "type": "integer"
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`catalog.categories.delete` — Видалити категорію

Що робить: Видаляє категорію. Через правила моделі також може видалити її дочірню гілку; товари отримують порожню основну категорію.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`category_branch_deleted`, `products_detached`

Додатковий контекст для AI

Що зачіпає: catalog.categories, storefront.catalog

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

catalog.categories.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "category_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "category_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.categories.get` — Дані категорії

Що робить: Повертає категорію, її шлях, переклади, медіа, SEO та кількість товарів.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.categories, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "category_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "category_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.categories.list` — Список категорій

Що робить: Повертає дерево категорій магазину з батьком, рівнем і кількістю дочірніх категорій.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.categories, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "parent_id": {
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.categories.update` — Оновити категорію

Що робить: Частково оновлює назву, дерево, порядок і SEO категорії з перевіркою циклів та належності магазину.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`catalog_tree_or_seo_changed`

Додатковий контекст для AI

Що зачіпає: catalog.categories, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

catalog.categories.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "category_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "category_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

Товари (15)

read Ризик: low

`catalog.buy_together.get` — Супутні товари

Що робить: Повертає супутні товари для одного товару.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.buy_together.set` — Задати супутні товари

Що робить: Замінює список супутніх товарів через наявну M2M-модель.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`buy_together_replaced`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "related_product_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "related_product_ids"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.product_images.add` — Додати фото товару

Що робить: Додає завантажене multipart-поле file до галереї; формат і resize перевіряє чинне поле ProductImg.

Важливо: Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`media_uploaded`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.product_images.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "file_field": {
      "type": "string",
      "default": "file"
    },
    "alt": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`catalog.product_images.delete` — Видалити фото

Що робить: Видаляє одне фото галереї разом із файлом через наявний signal моделі.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`media_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.product_images.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "image_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "image_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.product_images.list` — Фото товару

Що робить: Повертає головне фото й упорядковану галерею товару.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.product_images.set_cover` — Зробити фото головним

Що робить: Міняє місцями головне фото товару та вибране фото галереї за чинним UI-патерном.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`product_cover_changed`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.product_images.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "image_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "image_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: low

`catalog.product_images.update` — Оновити фото товару

Що робить: Змінює alt і порядок наявного фото галереї.

Доступ	`write`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`media_metadata_changed`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.product_images.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "image_id": {
      "type": "integer",
      "minimum": 1
    },
    "alt": {
      "type": "string"
    },
    "number": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "image_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.product_specifications.list` — Характеристики товару

Що робить: Повертає характеристики товару з перекладами.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.product_specifications.replace` — Замінити характеристики

Що робить: Атомарно замінює весь список характеристик товару; кожен елемент має spec, description і необов'язкові translations.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`product_specifications_replaced`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.product_specifications.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "items"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.products.create` — Створити товар

Що робить: Створює товар через чинну модель Product, тому автоматичні slug і SKU лишаються єдиним джерелом логіки. За замовчуванням товар не публікується.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`product_created`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.products.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    },
    "additional_category_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`catalog.products.delete` — Видалити товар

Що робить: Видаляє товар і його варіації через чинний сервіс масового видалення; склад не скидається автоматично.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`product_and_variations_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.products.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "reset_stock": {
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.products.get` — Дані товару

Що робить: Повертає повну безпечну картку товару, переклади, SEO, категорії та пов'язані дані.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.products.list` — Список товарів

Що робить: Повертає товари з пошуком, фільтрами категорії, публікації, архіву, варіацій і залишку.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "category_id": {
      "type": "integer",
      "minimum": 1
    },
    "is_published": {
      "type": "boolean"
    },
    "is_archival": {
      "type": "boolean"
    },
    "father_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "stock": {
      "type": "string",
      "enum": [
        "any",
        "positive",
        "zero"
      ]
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.products.update` — Оновити товар

Що робить: Частково оновлює дозволені поля товару й переклади; бізнес-логіка save() для slug/SKU не дублюється.

Важливо: Якщо склад увімкнений, patch.warehouse_count заборонений: створи ревізію, перевір її й проведи після підтвердження.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`product_changed`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.
Якщо склад увімкнений, patch.warehouse_count заборонений: створи ревізію, перевір її й проведи після підтвердження.

Що перевірити перед викликом

catalog.products.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)
settings.modules.get — Перевір, чи ввімкнений склад, перш ніж пропонувати зміну warehouse_count. (when_warehouse_count_requested)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.
warehouse.revisions.create
warehouse.revisions.post

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    },
    "additional_category_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      }
    },
    "expected_updated_at": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium

`catalog.products.visibility.set` — Публікація товару

Що робить: Вузько змінює стани публікації та архіву товару.

Доступ	`write`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`storefront_visibility_changed`

Додатковий контекст для AI

Що зачіпає: catalog.products, storefront.catalog

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.products.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "is_published": {
      "type": "boolean"
    },
    "is_archival": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.filter_values.create` — Створити значення фільтра

Що робить: Додає текстове або кольорове значення до фільтра.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`filter_value_created`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "minimum": 1
    },
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "filter_id",
    "data"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`catalog.filter_values.delete` — Видалити значення фільтра

Що робить: Видаляє значення та його прив'язки до товарів.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`filter_value_deleted`, `product_filter_links_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "value_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "value_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.filter_values.update` — Оновити значення фільтра

Що робить: Частково оновлює назву, колір, активність і порядок значення.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`filter_value_changed`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "value_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "value_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.filters.create` — Створити фільтр

Що робить: Створює фільтр checkbox, color або image через чинну модель.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`catalog_filter_created`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "data"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`catalog.filters.delete` — Видалити фільтр

Що робить: Видаляє фільтр, його значення та прив'язки товарів каскадно.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`catalog_filter_deleted`, `product_filter_links_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "filter_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.filters.get` — Дані фільтра

Що робить: Повертає один фільтр та всі його значення.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "filter_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.filters.list` — Список фільтрів

Що робить: Повертає фільтри каталогу та їх значення.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.filters.update` — Оновити фільтр

Що робить: Частково оновлює дозволені поля фільтра.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`catalog_filter_changed`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "filter_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.product_filters.get` — Атрибути товару

Що робить: Повертає значення фільтрів, призначені конкретному SKU.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`catalog.product_filters.set` — Задати атрибути товару

Що робить: Замінює прив'язки фільтрів товару атомарно; один фільтр може мати одне значення для SKU.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`product_filter_links_replaced`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Активний автоімпорт може перетерти змінені поля товару або відновити видалені дані під час наступного запуску.

Що перевірити перед викликом

catalog.product_filters.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
exchange.auto_import.get — Перевір активність, duplicate_policy і managed_fields; при перетині покажи ризик власнику та дай вибір. (before_product_write)

Безпечніший шлях

Змінити або вимкнути мапінг автоімпорту для поля, яке має керуватися вручну.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filter_id": {
            "type": "integer",
            "minimum": 1
          },
          "value_id": {
            "type": "integer",
            "minimum": 1
          }
        }
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "items"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`catalog.variations.get` — Варіації товару

Що робить: Повертає кореневий товар і впорядковані дочірні SKU.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`catalog.variations.set` — Задати варіації товару

Що робить: Атомарно замінює дочірні SKU кореневого товару й синхронізує поле father так само, як чинний admin inline.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`variation_family_rebuilt`

Додатковий контекст для AI

Що зачіпає: catalog.filters, catalog.variations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "child_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "product_id",
    "child_ids"
  ]
}

Результат (data)

{
  "type": "object"
}

Сторінки та контент (16)

Сторінки (8)

write Ризик: medium Підтвердження: recommended

`pages.create` — Створити сторінку

Що робить: Створює звичайну сторінку через чинну модель Page; за замовчуванням не публікує її.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`page_created`

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

pages.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "title"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`pages.delete` — Видалити сторінку

Що робить: Видаляє сторінку разом із блоками та файлами; підключені runtime-layout отримають порожнє посилання.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`page_and_blocks_deleted`, `layout_may_be_unassigned`

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

pages.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`pages.get` — Дані сторінки

Що робить: Повертає сторінку з перекладами, SEO, meta та впорядкованими блоками.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`pages.layouts.get` — Runtime-сторінки

Що робить: Повертає сторінки, призначені для каталогу, категорії, товару та checkout.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`pages.layouts.set` — Призначити runtime-сторінку

Що робить: Призначає наявну сторінку магазину для каталогу, категорії, товару або checkout через чинні layout-моделі.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`runtime_route_page_changed`

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

pages.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "runtime_context": {
      "type": "string",
      "enum": [
        "catalog",
        "category",
        "product",
        "checkout"
      ]
    },
    "page_id": {
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "runtime_context",
    "page_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`pages.list` — Список сторінок

Що робить: Повертає сторінки магазину, їх URL, роль у runtime та кількість блоків.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "include_unpublished": {
      "type": "boolean",
      "default": true
    },
    "runtime_context": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`pages.update` — Оновити сторінку

Що робить: Частково оновлює назву, URL, SEO, meta та переклади; не змінює блоки й публікацію.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`page_metadata_changed`

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

pages.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium

`pages.visibility.set` — Публікація сторінки

Що робить: Вузько публікує або приховує сторінку.

Доступ	`write`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`storefront_visibility_changed`

Додатковий контекст для AI

Що зачіпає: pages, storefront.routing

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

pages.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "is_published": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "is_published"
  ]
}

Результат (data)

{
  "type": "object"
}

Блоки (8)

read Ризик: low

`pages.blocks.catalog` — Каталог блоків

Що робить: Повертає реальний registry page builder: групи, всі зареєстровані типи блоків, контексти, schemas і defaults.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`public`, `shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "block_code": {
      "type": "string"
    },
    "runtime_context": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: dynamic Підтвердження: recommended

`pages.blocks.create` — Створити блок

Що робить: Вставляє зареєстрований блок через BuilderProvider із його defaults і перекладами магазину.

Доступ	`write`	Ризик	`dynamic`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`page_content_changed`

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Оціни фактичні поля; для HTML, секретів, індексації чи широкої зміни отримай явне підтвердження.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Ризик залежить від полів і контенту; перевір параметри та обери найвужчий метод.
html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "block_code": {
      "type": "string"
    },
    "insert_mode": {
      "type": "string",
      "enum": [
        "end",
        "before",
        "after"
      ]
    },
    "target_block_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "block_code"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`pages.blocks.delete` — Видалити блок

Що робить: Видаляє блок, переклади та завантажені assets через чинні cascade і signals.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`block_and_assets_deleted`

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "block_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "block_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: low

`pages.blocks.enabled.set` — Увімкнути або вимкнути блок

Що робить: Вузько змінює видимість одного блока без видалення контенту.

Доступ	`write`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`block_visibility_changed`

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "block_id": {
      "type": "integer",
      "minimum": 1
    },
    "is_enabled": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "block_id",
    "is_enabled"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`pages.blocks.get` — Дані блока

Що робить: Повертає один блок разом із його чинними schemas та значеннями.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "block_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "block_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`pages.blocks.list` — Блоки сторінки

Що робить: Повертає всі блоки сторінки з нормалізованим контентом, перекладами, дизайном і медіа.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: low

`pages.blocks.move` — Перемістити блок

Що робить: Міняє блок місцями з сусіднім у транзакції за чинним алгоритмом builder UI.

Доступ	`write`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`block_order_changed`

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "block_id": {
      "type": "integer",
      "minimum": 1
    },
    "direction": {
      "type": "string",
      "enum": [
        "up",
        "down"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "block_id",
    "direction"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: dynamic Підтвердження: recommended

`pages.blocks.update` — Оновити блок

Що робить: Частково оновлює content/design/data_config/extra через schemas і validators зареєстрованого backend; multipart-файли мають ті самі upload__... ключі, що й builder UI.

Доступ	`write`	Ризик	`dynamic`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`page_content_changed`, `media_may_change`

Додатковий контекст для AI

Що зачіпає: pages.blocks, storefront.layout

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Ризик залежить від полів і контенту; перевір параметри та обери найвужчий метод.
html_code змінює лише UI і не відкриває backend: потрібні дані слід отримувати через стандартні блоки та дозволені API-методи.

Що перевірити перед викликом

pages.blocks.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
pages.blocks.catalog — Спочатку знайди стандартний блок та його schema; власний HTML використовуй лише коли готового UI немає. (before_block_design)

Безпечніший шлях

Використай стандартний data/block provider для даних і html_code лише як presentation layer.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "minimum": 1
    },
    "block_id": {
      "type": "integer",
      "minimum": 1
    },
    "content": {
      "type": "object",
      "properties": {
        "shared": {
          "type": "object"
        },
        "translated": {
          "type": "object"
        }
      }
    },
    "design": {
      "type": "object"
    },
    "data_config": {
      "type": "object"
    },
    "extra": {
      "type": "object"
    },
    "expected_updated_at": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "page_id",
    "block_id"
  ]
}

Результат (data)

{
  "type": "object"
}

Налаштування (17)

Магазин (10)

read Ризик: low

`settings.catalog.get` — Налаштування каталогу

Що робить: Повертає чинні параметри показу дочірніх товарів і фільтрації варіацій.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`settings.catalog.update` — Оновити налаштування каталогу

Що робить: Частково змінює два чинні каталожні тумблери через helper налаштувань.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`catalog_behavior_changed`

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

settings.catalog.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: dynamic Підтвердження: recommended

`settings.company.update` — Оновити реквізити компанії

Що робить: Частково оновлює назву, email, ЄДРПОУ, IBAN, додаткову інформацію та переклади. Ідентифікаційні й банківські дані потребують явного підтвердження.

Доступ	`write`	Ризик	`dynamic`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`, `financial`
Наслідки	`legal_or_contact_details_changed`

Додатковий контекст для AI

Що зачіпає: shop.settings

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Ризик залежить від полів і контенту; перевір параметри та обери найвужчий метод.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.

Що перевірити перед викликом

settings.profile.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`settings.languages.base.set` — Задати базову мову

Що робить: Змінює базову мову через чинний helper сторінки налаштувань і прибирає її з додаткових.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`public_url_language_policy_changed`

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

settings.languages.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "code"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`settings.languages.extra.set` — Увімкнути додаткову мову

Що робить: Вмикає або вимикає додаткову мову через чинний helper налаштувань.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`store_languages_changed`

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

settings.languages.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "required": [
    "code",
    "enabled"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`settings.languages.get` — Мови магазину

Що робить: Повертає базову, увімкнені й доступні мови магазину.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`settings.modules.get` — Стани модулів

Що робить: Повертає тумблери модулів і тарифні стани з чинного serializer налаштувань.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`settings.modules.set` — Увімкнути або вимкнути модуль

Що робить: Змінює один чинний module toggle через існуючу тарифну та складську перевірку. Вимкнення AI заблокує наступні виклики цього токена.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`module_access_changed`, `warehouse_reset_may_be_enqueued`

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

settings.modules.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "module": {
      "type": "string",
      "enum": [
        "crm",
        "warehouse",
        "customer_account",
        "import_export",
        "ai_agent_api"
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "confirm_warehouse_reset": {
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": false,
  "required": [
    "module",
    "enabled"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`settings.profile.get` — Профіль налаштувань

Що робить: Повертає безпечний зріз базових, каталожних, модульних, мовних і компанійних налаштувань без паролів, токенів та секретів.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: low

`settings.site_name.update` — Змінити назву сайту

Що робить: Змінює назву сайту через той самий валідатор поля, який використовує сторінка налаштувань.

Доступ	`write`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`site_identity_changed`

Додатковий контекст для AI

Що зачіпає: shop.settings

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.

Що перевірити перед викликом

settings.profile.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "site_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    }
  },
  "additionalProperties": false,
  "required": [
    "site_name"
  ]
}

Результат (data)

{
  "type": "object"
}

Домен (2)

read Ризик: medium

`domain.settings.get` — Налаштування домену

Що робить: Повертає домен, DNS/TLS-статус, очікувані IP та помилку перевірки без внутрішніх шляхів nginx.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`, `contact`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: shop.domain, dns, tls, public_routing

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: contact. Не передавай їх поза завданням.
Зміна домену впливає на DNS, TLS-сертифікат, canonical URL та доступність storefront.

Безпечніший шлях

Спочатку збережи домен із connect_requested=false і перевір DNS-налаштування.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`domain.settings.update` — Оновити домен

Що робить: Частково змінює домен, email для Let's Encrypt і стан підключення через чинний save_domain_settings_from_user(); DNS/SSL обробляються наявним фоновим процесом.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`supported`
Потрібні модулі	—
Класи даних	`shop_internal`, `contact`
Наслідки	`public_domain_changed`, `dns_and_tls_workflow_changed`, `old_domain_runtime_may_be_cleaned`

Додатковий контекст для AI

Що зачіпає: shop.domain, dns, tls, public_routing

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Метод працює з чутливими класами даних: contact. Не передавай їх поза завданням.
Зміна домену впливає на DNS, TLS-сертифікат, canonical URL та доступність storefront.

Що перевірити перед викликом

domain.settings.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Безпечніший шлях

Спочатку збережи домен із connect_requested=false і перевір DNS-налаштування.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "maxLength": 253
    },
    "certificate_email": {
      "type": "string",
      "maxLength": 254
    },
    "connect_requested": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Дизайн (2)

read Ризик: low

`design.theme.get` — Дизайн теми

Що робить: Повертає активну тему, кольори, системні шрифти, ваги, розміри та власні font groups без бінарних даних.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: storefront.theme

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`design.theme.update` — Оновити дизайн теми

Що робить: Частково змінює дозволені кольори, стандартні шрифти, ваги, розміри та radius через ThemeUserSettings.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`site_design_changed`

Додатковий контекст для AI

Що зачіпає: storefront.theme

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

design.theme.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

SEO (3)

read Ризик: low

`seo.audit` — SEO-аудит

Що робить: Викликає чинний build_seo_audit(shop): score, секції, лічильники та рекомендації.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: seo, search_indexing

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`seo.settings.get` — SEO-налаштування

Що робить: Повертає глобальні SEO-поля магазину та URL OG-зображення.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: seo, search_indexing

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: dynamic Підтвердження: recommended

`seo.settings.update` — Оновити SEO

Що робить: Частково оновлює глобальні SEO-поля. Увімкнення або вимкнення індексації вимагає підтвердження.

Доступ	`write`	Ризик	`dynamic`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`search_indexing_or_metadata_changed`

Додатковий контекст для AI

Що зачіпає: seo, search_indexing

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Ризик залежить від полів і контенту; перевір параметри та обери найвужчий метод.

Що перевірити перед викликом

seo.settings.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

Продажі (21)

Замовлення (11)

write Ризик: high Підтвердження: required

`orders.cancel` — Скасувати замовлення

Що робить: Викликає Order.cancel_order(): скасовує замовлення і звільняє складський резерв; reason записується лише якщо передано author_user_id.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	`stock_released`, `order_cancelled`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    },
    "reason": {
      "type": "string"
    },
    "author_user_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`orders.comment.add` — Додати коментар до замовлення

Що робить: Додає внутрішній коментар від конкретного працівника магазину; автор задається явно, щоб журнал не приписував AI чужу особу.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	`order_comment_created`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    },
    "author_user_id": {
      "type": "integer",
      "minimum": 1
    },
    "text": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id",
    "author_user_id",
    "text"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.confirm` — Підтвердити замовлення

Що робить: Викликає Order.confirm_order(): підтверджує, резервує склад і ставить клієнтський email у чергу.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	`stock_reserved`, `customer_email_enqueued`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.documents.generate` — Згенерувати документи

Що робить: Викликає чинний Order.prepare_docs() для рахунку та видаткової накладної.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`invoice_and_waybill_generated`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.documents.mark_sent` — Позначити документи відправленими

Що робить: Викликає чинний Order.doc_send().

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`document_state_changed`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.fiscalization.mark` — Позначити фіскалізованим

Що робить: Викликає Order.order_fiscalized(check_link) і ставить лист із чеком у чергу.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`fiscalization_state_changed`, `customer_email_enqueued`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    },
    "check_link": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id",
    "check_link"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.fulfillment.pack` — Позначити запакованим

Що робить: Викликає Order.order_pack() і ставить клієнтський email у чергу.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`packing_state_changed`, `customer_email_enqueued`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.fulfillment.ship` — Позначити відправленим

Що робить: Викликає Order.order_send(ttn), синхронізує ТТН у чинній OrderDelivery і ставить email у чергу.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`shipping_state_changed`, `customer_email_enqueued`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    },
    "ttn": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id",
    "ttn"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`orders.get` — Дані замовлення

Що робить: Повертає повне замовлення: товари, суму, доставку, оплату, статуси, документи та внутрішні коментарі.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`, `financial`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii, financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`orders.list` — Список замовлень

Що робить: Повертає замовлення з пошуком, джерелом і окремими status-фільтрами; містить контактні дані клієнтів.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`, `financial`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii, financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "source": {
      "type": "string"
    },
    "confirmed": {
      "type": "boolean"
    },
    "is_paid": {
      "type": "boolean"
    },
    "is_cansel": {
      "type": "boolean"
    },
    "is_sended": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`orders.payment.mark_paid` — Позначити оплаченим

Що робить: Викликає Order.order_paid(): фіксує оплату, резервує склад і ставить email у чергу.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	`payment_state_changed`, `stock_reserved`, `customer_email_enqueued`

Додатковий контекст для AI

Що зачіпає: orders, customers, stock

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

orders.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "order_id"
  ]
}

Результат (data)

{
  "type": "object"
}

Оплати (3)

read Ризик: medium

`payments.settings.get` — Налаштування методу оплати

Що робить: Повертає один платіжний провайдер і його безпечну конфігурацію; секрет показується лише як secret_configured.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`financial`, `shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: checkout.payments, payment_configuration

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.
Зміна впливає на варіанти оплати в checkout; секрети приймаються, але ніколи не повертаються.

Безпечніший шлях

Спочатку налаштуй метод вимкненим, перевір реквізити й лише потім активуй.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "wayforpay",
        "bank_personal",
        "bank_business",
        "cash"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "code"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`payments.settings.list` — Налаштування оплат

Що робить: Повертає всі зареєстровані платіжні провайдери, checkout-представлення і стан налаштувань без secret_key.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`financial`, `shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: checkout.payments, payment_configuration

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.
Зміна впливає на варіанти оплати в checkout; секрети приймаються, але ніколи не повертаються.

Безпечніший шлях

Спочатку налаштуй метод вимкненим, перевір реквізити й лише потім активуй.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`payments.settings.update` — Оновити метод оплати

Що робить: Частково оновлює налаштування зареєстрованого платіжного provider через чинні моделі та full_clean(). secret_key можна передати для WayForPay, але він не повертається у відповіді або журналі.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`financial`, `secret_input`
Наслідки	`checkout_payment_options_changed`, `payment_credentials_may_change`

Додатковий контекст для AI

Що зачіпає: checkout.payments, payment_configuration

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Метод працює з чутливими класами даних: financial, secret_input. Не передавай їх поза завданням.
Зміна впливає на варіанти оплати в checkout; секрети приймаються, але ніколи не повертаються.

Що перевірити перед викликом

payments.settings.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Безпечніший шлях

Спочатку налаштуй метод вимкненим, перевір реквізити й лише потім активуй.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "wayforpay",
        "bank_personal",
        "bank_business",
        "cash"
      ]
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "code",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

Клієнти (5)

read Ризик: medium

`customers.get` — Дані клієнта

Що робить: Повертає профіль користувача магазину й останні замовлення.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`, `financial`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: customers

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii, financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "customer_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`customers.list` — Список клієнтів і працівників

Що робить: Повертає користувачів магазину з ролями; потрібний, зокрема, для явного author_user_id у внутрішніх коментарях.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: customers

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "role": {
      "type": "string",
      "enum": [
        "customer",
        "worker",
        "all"
      ]
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`customers.update` — Оновити профіль клієнта

Що робить: Частково змінює контактні дані й активність профілю; паролі, права та ролі не доступні.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	`customer_profile_changed`

Додатковий контекст для AI

Що зачіпає: customers

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Що перевірити перед викликом

customers.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "customer_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`subscribers.delete` — Видалити підписника

Що робить: Видаляє email із підписок магазину.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	`subscriber_deleted`

Додатковий контекст для AI

Що зачіпає: customers

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "subscriber_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`subscribers.list` — Підписники розсилки

Що робить: Повертає email-підписників магазину.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: customers

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Відгуки (2)

write Ризик: high Підтвердження: required

`reviews.delete` — Видалити відгук

Що робить: Видаляє відгук; чинний signal автоматично перерахує рейтинг товару.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	`review_deleted`, `product_rating_recalculated`

Додатковий контекст для AI

Що зачіпає: reviews, product_rating

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "review_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "review_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`reviews.list` — Список відгуків

Що робить: Повертає відгуки з фільтром товару й оцінки; містить email автора.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`customer_pii`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: reviews, product_rating

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: customer_pii. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Операції (47)

Склад (12)

read Ризик: medium

`warehouse.history.report` — Склад на дату

Що робить: Будує пагінований історичний звіт через чинний build_stock_history_page().

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`financial`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "ISO datetime"
    },
    "category_id": {
      "type": "integer",
      "minimum": 1
    },
    "query": {
      "type": "string"
    },
    "only_positive": {
      "type": "boolean",
      "default": true
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "additionalProperties": false,
  "required": [
    "date"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`warehouse.movements.list` — Рухи складу

Що робить: Повертає незмінюваний журнал складських рухів з фільтрами товару й типу.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`financial`, `shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "movement_type": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`warehouse.purchases.get` — Дані закупівлі

Що робить: Повертає закупівлю та її товарні партії.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`financial`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "purchase_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "purchase_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`warehouse.purchases.list` — Список закупівель

Що робить: Повертає закупівлі, їх етап, суми та стан синхронізації.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`financial`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "is_paid": {
      "type": "boolean"
    },
    "stage_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`warehouse.purchases.sync` — Синхронізувати закупівлю

Що робить: Викликає чинний request_purchase_sync(); залежно від обсягу виконує роботу одразу або через Celery.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`financial`
Наслідки	`physical_stock_rows_rebuilt`, `background_task_may_start`

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Метод працює з чутливими класами даних: financial. Не передавай їх поза завданням.

Що перевірити перед викликом

warehouse.purchases.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "purchase_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "purchase_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`warehouse.revisions.create` — Створити ревізію

Що робить: Створює чернетку ревізії й рахує system_qty кожного рядка через available_stock_count().

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	`stock_revision_draft_created`

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Проведення ревізії створює складські рухи та змінює фактичні залишки.

Що перевірити перед викликом

warehouse.revisions.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
warehouse.stock.list — Звір поточний точний залишок перед формуванням fact_qty. (before_revision_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "comment": {
      "type": "string"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "integer",
            "minimum": 1
          },
          "fact_qty": {
            "type": "integer",
            "minimum": 0
          },
          "comment": {
            "type": "string"
          }
        }
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "items"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`warehouse.revisions.get` — Дані ревізії

Що робить: Повертає ревізію і всі її товарні рядки.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Проведення ревізії створює складські рухи та змінює фактичні залишки.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "revision_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "revision_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`warehouse.revisions.list` — Список ревізій

Що робить: Повертає складські ревізії та їх фоновий стан.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Проведення ревізії створює складські рухи та змінює фактичні залишки.

Що перевірити перед викликом

warehouse.stock.list — Звір поточний точний залишок перед формуванням fact_qty. (before_revision_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "posted"
      ]
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`warehouse.revisions.post` — Провести ревізію

Що робить: Викликає чинний request_stock_revision_post(); операція може виконатися синхронно або перейти в Celery.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	`stock_quantities_changed`, `stock_movements_created`, `background_task_may_start`

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Проведення ревізії створює складські рухи та змінює фактичні залишки.

Що перевірити перед викликом

warehouse.revisions.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
warehouse.stock.list — Звір поточний точний залишок перед формуванням fact_qty. (before_revision_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "revision_id": {
      "type": "integer",
      "minimum": 1
    },
    "author_user_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "revision_id",
    "author_user_id"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`warehouse.revisions.update` — Оновити чернетку ревізії

Що робить: Замінює рядки лише чернетки ревізії та заново фіксує system_qty через наявний сервіс залишку.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`supported`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	`stock_revision_draft_replaced`

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.
Проведення ревізії створює складські рухи та змінює фактичні залишки.

Що перевірити перед викликом

warehouse.revisions.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)
warehouse.stock.list — Звір поточний точний залишок перед формуванням fact_qty. (before_revision_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "revision_id": {
      "type": "integer",
      "minimum": 1
    },
    "title": {
      "type": "string"
    },
    "comment": {
      "type": "string"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "revision_id",
    "items"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`warehouse.stock.list` — Залишки товарів

Що робить: Повертає кешований залишок SKU та, за потреби, точний доступний залишок із чинного available_stock_count().

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "only_positive": {
      "type": "boolean",
      "default": false
    },
    "exact": {
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`warehouse.summary` — Огляд складу

Що робить: Повертає кількість SKU, доступних одиниць, чернеток ревізій і незавершених складських операцій.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`warehouse`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: warehouse, stock_movements

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Доставка (5)

read Ризик: low

`shipping.methods.list` — Методи доставки

Що робить: Повертає публічні увімкнені методи через чинний shipping.registry.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: checkout.shipping, shipping_configuration

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`shipping.nova_poshta.cities.search` — Пошук міст Нової пошти

Що робить: Викликає чинний cached search_cities() з обмеженням результатів.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: checkout.shipping, shipping_configuration

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false,
  "required": [
    "query"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`shipping.nova_poshta.warehouses.list` — Відділення Нової пошти

Що робить: Викликає чинний cached get_warehouses() за city_ref, settlement_ref або city_name.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: checkout.shipping, shipping_configuration

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "city_ref": {
      "type": "string"
    },
    "settlement_ref": {
      "type": "string"
    },
    "city_name": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`shipping.settings.get` — Налаштування доставки

Що робить: Повертає конфіг усіх зареєстрованих shipping providers з перекладами.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: checkout.shipping, shipping_configuration

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Де можна помилитися

Зміна впливає на варіанти доставки та поля, які побачить покупець у checkout.

Безпечніший шлях

Спочатку збережи метод вимкненим або перевір його поточний settings snapshot.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`shipping.settings.update` — Оновити метод доставки

Що робить: Частково змінює is_active, title, description, address і переклади у settings_model зареєстрованого provider.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`checkout_shipping_options_changed`

Додатковий контекст для AI

Що зачіпає: checkout.shipping, shipping_configuration

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
Зміна впливає на варіанти доставки та поля, які побачить покупець у checkout.

Що перевірити перед викликом

shipping.settings.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Безпечніший шлях

Спочатку збережи метод вимкненим або перевір його поточний settings snapshot.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "translations": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "code",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

Імпорт та експорт (20)

read Ризик: medium

`exchange.auto_import.get` — Стан автоматичного імпорту

Що робить: Повертає активність, графік, політику дублікатів і managed_fields автоімпорту без повного source URL. Використовуй перед ручним оновленням товарів, щоб побачити, які поля може перетерти наступний запуск.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.
managed_fields — консервативний список полів, які наступний автоімпорт може оновити.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.catalog` — Можливості імпорту й експорту

Що робить: Повертає системні пресети, field registries, трансформації та marketplace providers із чинних registry-функцій.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`exchange.export_presets.create` — Створити експортний пресет

Що робить: Створює пресет і колонки, перевіряючи поля та transforms чинними registry validators.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`export_preset_created`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

exchange.export_presets.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "data",
    "columns"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`exchange.export_presets.delete` — Видалити експортний пресет

Що робить: Видаляє кастомний пресет, колонки й пов'язані data gateways каскадно.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`export_preset_and_gateways_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

exchange.export_presets.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "preset_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "preset_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.export_presets.get` — Дані експортного пресету

Що робить: Повертає кастомний експортний пресет і колонки через get_runtime_custom_preset().

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "preset_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "preset_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.export_presets.list` — Експортні пресети

Що робить: Повертає системні й кастомні експортні пресети через чинні serializers.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`exchange.export_presets.update` — Оновити експортний пресет

Що робить: Частково оновлює пресет і атомарно замінює колонки через чинні validators.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`export_preset_changed`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

exchange.export_presets.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "preset_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "preset_id",
    "patch",
    "columns"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`exchange.gateways.create` — Створити data gateway

Що робить: Створює публічний gateway через DataGateway.clean() і необов'язковий IP allowlist.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`public_export_endpoint_created`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

exchange.gateways.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "allowed_ips": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "data"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`exchange.gateways.delete` — Видалити data gateway

Що робить: Видаляє публічний data gateway та IP allowlist.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`public_export_endpoint_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

exchange.gateways.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "gateway_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "gateway_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.gateways.get` — Дані data gateway

Що робить: Повертає один публічний data gateway.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "gateway_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "gateway_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.gateways.list` — Публічні data gateways

Що робить: Повертає публічні URL експорту, джерела пресетів і IP allowlist.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`exchange.gateways.update` — Оновити data gateway

Що робить: Частково оновлює gateway і за потреби атомарно замінює IP allowlist.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`public_export_endpoint_changed`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

exchange.gateways.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "gateway_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "allowed_ips": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "gateway_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`exchange.import_presets.create` — Створити імпортний пресет

Що робить: Створює імпортний пресет і колонки, перевіряючи target fields і transforms чинними registry validators.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`supported`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`import_preset_created`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

exchange.import_presets.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "data",
    "columns"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`exchange.import_presets.delete` — Видалити імпортний пресет

Що робить: Видаляє кастомний імпортний пресет і його колонки.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`import_preset_deleted`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

exchange.import_presets.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "preset_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "preset_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.import_presets.get` — Дані імпортного пресету

Що робить: Повертає кастомний імпортний пресет і колонки через get_runtime_custom_import_preset().

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "preset_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "preset_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.import_presets.list` — Імпортні пресети

Що робить: Повертає системні й кастомні імпортні пресети через чинний payload builder.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`exchange.import_presets.update` — Оновити імпортний пресет

Що робить: Частково оновлює пресет і атомарно замінює колонки через чинні validators.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`import_preset_changed`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

exchange.import_presets.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "preset_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "preset_id",
    "patch",
    "columns"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`exchange.operations.cancel` — Скасувати операцію обміну

Що робить: Скасовує активну Celery-задачу, якщо вона є, і завершує операцію через чинний cancel_exchange_operation().

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	`background_task_revoked`, `exchange_operation_cancelled`

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "operation_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "operation_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.operations.get` — Дані операції обміну

Що робить: Повертає один статус імпорту/експорту та error_json.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "operation_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "operation_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`exchange.operations.list` — Операції обміну

Що робить: Повертає історію імпорту/експорту через чинний serialize_operation().

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	`import_export`
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: catalog.import_export, background_operations

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "status": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Канали сповіщень (6)

write Ризик: high Підтвердження: required

`notifications.channels.create` — Створити канал

Що робить: Створює канал; provider.clean_config() викликається чинним model.clean(). Секрети приймаються, але не повертаються й редагуються в аудиті.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`notification_channel_created`

Додатковий контекст для AI

Що зачіпає: notifications, delivery_logs

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

notifications.channels.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "kind",
    "data"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`notifications.channels.delete` — Видалити канал

Що робить: Видаляє канал; delivery logs залишаються з channel=null.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`notification_channel_deleted`

Додатковий контекст для AI

Що зачіпає: notifications, delivery_logs

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

notifications.channels.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string"
    },
    "channel_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "kind",
    "channel_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`notifications.channels.get` — Дані каналу

Що робить: Повертає один канал без секретних значень конфігурації.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: notifications, delivery_logs

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string"
    },
    "channel_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "kind",
    "channel_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`notifications.channels.list` — Канали сповіщень

Що робить: Повертає customer/form і merchant канали, schema провайдерів та ознаки налаштованих секретів без самих секретів.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: notifications, delivery_logs

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "kind": {
      "type": "string",
      "enum": [
        "form",
        "merchant"
      ]
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`notifications.channels.update` — Оновити канал

Що робить: Частково оновлює канал; відсутні секретні поля зберігаються, передані — замінюються й не повертаються.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`notification_channel_changed`

Додатковий контекст для AI

Що зачіпає: notifications, delivery_logs

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

notifications.channels.get — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string"
    },
    "channel_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "kind",
    "channel_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: medium

`notifications.delivery_logs.list` — Журнал доставок

Що робить: Повертає журнали customer/form або merchant повідомлень без повного HTML та секретів.

Доступ	`read`	Ризик	`medium`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: notifications, delivery_logs

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    },
    "kind": {
      "type": "string",
      "enum": [
        "form",
        "merchant"
      ]
    },
    "status": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

Редиректи (4)

write Ризик: medium Підтвердження: recommended

`redirects.create` — Створити редирект

Що робить: Створює правило base_path → target_url через чинну модель.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`routing_changed`

Додатковий контекст для AI

Що зачіпає: storefront.routing

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

redirects.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "base_path": {
      "type": "string"
    },
    "target_url": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "base_path",
    "target_url"
  ]
}

Результат (data)

{
  "type": "object"
}

write Ризик: high Підтвердження: required

`redirects.delete` — Видалити редирект

Що робить: Видаляє правило редиректу.

Доступ	`write`	Ризик	`high`
Підтвердження	`required`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`routing_changed`

Додатковий контекст для AI

Що зачіпає: storefront.routing

Правило рішення: Отримай явне підтвердження конкретної дії безпосередньо перед викликом.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Дію може бути складно або неможливо скасувати; потрібне підтвердження точної операції.

Що перевірити перед викликом

redirects.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "redirect_id": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "redirect_id"
  ]
}

Результат (data)

{
  "type": "object"
}

read Ризик: low

`redirects.list` — Список редиректів

Що робить: Повертає правила редиректів магазину.

Доступ	`read`	Ризик	`low`
Підтвердження	`none`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	—

Додатковий контекст для AI

Що зачіпає: storefront.routing

Правило рішення: Можна викликати без підтвердження, але запитуй лише потрібні дані й не роби зайвих змін.

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Пошук за текстовими полями."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  },
  "additionalProperties": false
}

Результат (data)

{
  "type": "object"
}

write Ризик: medium Підтвердження: recommended

`redirects.update` — Оновити редирект

Що робить: Частково змінює source і target правила редиректу.

Доступ	`write`	Ризик	`medium`
Підтвердження	`recommended`	Ідемпотентність	`not_needed`
Потрібні модулі	—
Класи даних	`shop_internal`
Наслідки	`routing_changed`

Додатковий контекст для AI

Що зачіпає: storefront.routing

Правило рішення: Спочатку виконай preflight, покажи користувачу наслідок і віддай перевагу вузькому методу.

Де можна помилитися

Змінює live-стан магазину; результат і помилки записуються в AI-журнал.
Помилка може змінити поведінку магазину або дані; покажи очікуваний результат до запису.

Що перевірити перед викликом

redirects.list — Прочитай поточний стан і не перезаписуй поля, яких користувач не просив змінювати. (before_write)

Вхідні дані (params)

{
  "type": "object",
  "properties": {
    "redirect_id": {
      "type": "integer",
      "minimum": 1
    },
    "patch": {
      "type": "object",
      "description": "Частковий набір дозволених полів."
    }
  },
  "additionalProperties": false,
  "required": [
    "redirect_id",
    "patch"
  ]
}

Результат (data)

{
  "type": "object"
}

Як підключити AI-агента до магазину Shopcore

Де взяти доступ

Новий магазин

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

Як працює API

Відповідь і контекст

Ризики й підтвердження

Критичні правила предметної області

Товари й автоімпорт

Склад і наявність

Блоки та власний HTML

Каталог методів: 137

Система (4)

Стан і можливості (2)

system.overview — Огляд даних магазину

system.status — Стан магазину

Журнал AI (2)

audit.requests.get — Деталі AI-запиту

Де можна помилитися

audit.requests.list — Список AI-запитів

Де можна помилитися

Каталог (32)

Категорії (5)

catalog.categories.create — Створити категорію

Де можна помилитися

Що перевірити перед викликом

catalog.categories.delete — Видалити категорію

Де можна помилитися

Що перевірити перед викликом

catalog.categories.get — Дані категорії

catalog.categories.list — Список категорій

catalog.categories.update — Оновити категорію

Де можна помилитися

Що перевірити перед викликом

Товари (15)

catalog.buy_together.get — Супутні товари

catalog.buy_together.set — Задати супутні товари

Де можна помилитися

catalog.product_images.add — Додати фото товару

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.product_images.delete — Видалити фото

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.product_images.list — Фото товару

catalog.product_images.set_cover — Зробити фото головним

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.product_images.update — Оновити фото товару

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.product_specifications.list — Характеристики товару

catalog.product_specifications.replace — Замінити характеристики

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.products.create — Створити товар

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.products.delete — Видалити товар

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.products.get — Дані товару

catalog.products.list — Список товарів

catalog.products.update — Оновити товар

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

catalog.products.visibility.set — Публікація товару

Де можна помилитися

Що перевірити перед викликом

Безпечніший шлях

Фільтри й варіації (12)

catalog.filter_values.create — Створити значення фільтра

`system.overview` — Огляд даних магазину

`system.status` — Стан магазину

`audit.requests.get` — Деталі AI-запиту

`audit.requests.list` — Список AI-запитів

`catalog.categories.create` — Створити категорію

`catalog.categories.delete` — Видалити категорію

`catalog.categories.get` — Дані категорії

`catalog.categories.list` — Список категорій

`catalog.categories.update` — Оновити категорію

`catalog.buy_together.get` — Супутні товари

`catalog.buy_together.set` — Задати супутні товари

`catalog.product_images.add` — Додати фото товару

`catalog.product_images.delete` — Видалити фото

`catalog.product_images.list` — Фото товару

`catalog.product_images.set_cover` — Зробити фото головним

`catalog.product_images.update` — Оновити фото товару

`catalog.product_specifications.list` — Характеристики товару

`catalog.product_specifications.replace` — Замінити характеристики

`catalog.products.create` — Створити товар

`catalog.products.delete` — Видалити товар

`catalog.products.get` — Дані товару

`catalog.products.list` — Список товарів

`catalog.products.update` — Оновити товар

`catalog.products.visibility.set` — Публікація товару

`catalog.filter_values.create` — Створити значення фільтра

`catalog.filter_values.delete` — Видалити значення фільтра

`catalog.filter_values.update` — Оновити значення фільтра

`catalog.filters.create` — Створити фільтр

`catalog.filters.delete` — Видалити фільтр

`catalog.filters.get` — Дані фільтра

`catalog.filters.list` — Список фільтрів

`catalog.filters.update` — Оновити фільтр

`catalog.product_filters.get` — Атрибути товару

`catalog.product_filters.set` — Задати атрибути товару

`catalog.variations.get` — Варіації товару

`catalog.variations.set` — Задати варіації товару

`pages.create` — Створити сторінку

`pages.delete` — Видалити сторінку

`pages.get` — Дані сторінки

`pages.layouts.get` — Runtime-сторінки

`pages.layouts.set` — Призначити runtime-сторінку

`pages.list` — Список сторінок

`pages.update` — Оновити сторінку

`pages.visibility.set` — Публікація сторінки

`pages.blocks.catalog` — Каталог блоків

`pages.blocks.create` — Створити блок

`pages.blocks.delete` — Видалити блок

`pages.blocks.enabled.set` — Увімкнути або вимкнути блок

`pages.blocks.get` — Дані блока

`pages.blocks.list` — Блоки сторінки

`pages.blocks.move` — Перемістити блок