Кастомні редактори

Буває робота, якої немає в жодній панелі, бо вона тільки ваша: власний перерахунок цін за формулою постачальника, звіряння каталогу з чужою обліковою системою, екран «заповнити характеристики партії за один прохід». Розділ «Кастомні редактори» дає змогу написати такий мініредактор самому (або замовити його) і запустити всередині адмінки — у пісочниці, з доступом рівно до тих даних, які ви дозволили.

Відкрити: Адмін-панель → Кастомні редактори (admin.cenaly.com/custom-editors). Розділ вмикається карткою «Кастомні редактори (SDK)» у магазині додатків — за замовчуванням він прихований. Кнопка «📌 В сайдбар» на самій сторінці виносить його в бічне меню, коли він потрібен часто.

Що це за розділ#

Плагін — це зібраний скрипт (index.js) та його опис (manifest.json). Панель завантажує скрипт у ізольований фрейм: у нього немає доступу ні до вашої сесії, ні до коду адмінки, ні до мережі. Говорити з даними він може лише через міст — набір дозволених запитів, кожен з яких перевіряється за виданими правами.

Сторінка складається з блоків:

Відкритий редактор займає весь екран, а адреса сторінки отримує позначку ?app=<ідентифікатор> — таким посиланням можна поділитися з тим, у кого є доступ.

Що потрібно для запуску#

Крок 1. Вирішити, хто напише редактор#

Шляхів три, і вони відрізняються тим, хто тримає код:

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

Крок 2. Розробка з ШІ (вайб-кодинг)#

Блок «🤖 Розробка з ШІ (вайб-кодинг)» дає чотири речі, щоб віддати завдання ШІ-агенту (Claude Code, Cursor і подібним) і не пояснювати йому контракт з нуля:

1. «⬇️ Завантажити шаблон проєкту (zip)» — готовий каркас плагіна: маніфест, точка входу, опис контракту (GUIDE.en.md) та інструкція для агента. Архів збирається прямо в браузері, нічого зовнішнього завантажувати не потрібно.
2. «📋 Скопіювати промпт для агента» — текст завдання англійською: стартувати від шаблону, звірятися з гідом, чим перевіряти результат.
3. Конфігурація набору інструментів для агента — з нею агент збирає плагін, піднімає локальний стенд-копію пісочниці, робить скриншоти та знімки стану, а наприкінці збирає реліз: zip для ручного встановлення або реліз у GitHub.
4. «⬇️ Завантажити знімок каталогу (тестова фікстура)» — ваші категорії та товари файлом, щоб агент тестував на реальних даних, а не на вигаданих.

⚠️ Зі знімка цілком вирізаються кастомні поля інших плагінів: дані, які чуже розширення зберігає на ваших картках, не залишають обліковий запис разом із фікстурою.

Крок 3. Установити редактор#

З файлів. Блок «Установити редактор»: виберіть «Бандл (index.js)» і «Маніфест (manifest.json)» → «Перевірити й установити». Панель спершу перевіряє маніфест — ідентифікатор, локалізоване ім'я, версію, мінімальну версію SDK, місця розміщення, права та список мережевих хостів, — а потім показує консент: «Цей редактор запитує:» та список прав людською мовою. Поки ви не натиснули «Установити», нічого не встановлюється.

З GitHub. Блок «Установлення з GitHub»: поле «Репозиторій (URL або owner/repo)», поле «Тег (порожньо = останній реліз)» і кнопка «Перевірити репозиторій». Конвенція проста: manifest.json у корені репозиторію, зібраний dist/index.js у тезі, тег вигляду v{версія}. Маніфест і бандл тягнуться прямо з вашого браузера. В обох випадках під час установлення рахується й запам'ятовується відбиток бандла (sha256): якщо файл потім підмінять, запуск буде заблоковано, і панель попросить перевстановити редактор.

Права та місця розміщення#

Права (їх також називають скоупами) плагін просить у маніфесті, а ви підтверджуєте під час встановлення. Повний список — ось він, більше міст не вміє нічого:

Чого в списку немає взагалі — того плагін не отримає жодними налаштуваннями: гостей і клієнтів, замовлень, чеків, фінансів, співробітників, листувань і дзвінків міст не віддає.

Місця розміщення (слоти) — три:

Режим розробника та доступ підряднику#

Режим розробника (блок «🛠️ Режим розробника») монтує плагін живцем із вашого комп'ютера: поле «URL бандла» приймає лише адреси localhost / 127.0.0.1, поруч — «JSON маніфесту», кнопка «Запустити dev-сесію». Відбиток при цьому не піниться, а сесія живе до закриття вкладки; «Зупинити dev-сесію» вимикає її одразу.

Гранти розробнику (блок «👩‍💻 Доступ розробника») потрібні, коли пише не власник. Розробнику заводиться звичайний обліковий запис співробітника, а потім власник видає грант: «Email розробника (його staff-логін)», «Дозволені права», «Термін дії (днів)» і необов'язкова нотатка → «Видати доступ». Відкликати можна будь-якої миті кнопкою «Відкликати».

Що дає грант, а що ні:

• дає — лише режим розробника з правами, які ви позначили (типово термін 14 днів, максимум 90);
• права ріжуться перетином: що просить маніфест і що видано грантом; зайвого плагін не отримає, навіть якщо попросить у маніфесті;
• не дає — встановлення, увімкнення та видалення плагінів: це залишається власнику.

Оновлення, увімкнення та видалення#

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

Вбудовані розширення#

Частина наших власних модулів упакована в той самий формат — це видно з поведінки, але ставити їх не потрібно: вони приїздять разом із панеллю й вмикаються карткою в магазині додатків, а не в цьому розділі.

Зараз такий модуль один — «Меркурий/ВетИС» для Росії: він живе вкладкою розділу «Склад», виконується в тій самій пісочниці й з тими самими перевірками відбитка. До списку встановлених редакторів вбудовані розширення не потрапляють.

Що редактор може і чого не може#

Сторонні плагіни позначаються на картці попередженням: «Сторонній додаток у пісочниці — він ніколи не питає пароль». Якщо плагін просить логін від панелі, платіжні дані або код із SMS — це шахрайство, а не робота розширення.

Обмеження#

• Розділ вимкнено за замовчуванням і розрахований на тих, хто пише код (або замовляє його): пересічному власнику тут робити нічого.
• Усе, крім перегляду, — лише у власника облікового запису. Співробітник бачить хаб read-only; режим розробника — лише з активним грантом.
• Приватні GitHub-репозиторії не підтримуються — репозиторій має бути публічним, встановлення йде за тегом.
• Автооновлення немає: оновлення плагіна завжди запускає власник.
• Магазину чужих плагінів немає. Готові розширення не публікуються й не продаються через панель — джерело лише ваш файл або ваш репозиторій.
• Слотів три (власна сторінка, кнопка каталогу, вкладка складу) — вбудуватися в довільний екран панелі плагін не може.
• Міст не віддає гостей, замовлення, фінанси, співробітників і листування — обійти це правами не можна, таких запитів просто не існує.
• Окремого журналу «плагін зробив те-то» немає. Права видно на картці, а правки каталогу потрапляють у звичайну історію товарів; якщо потрібен контроль, починайте з плагіна, якому видано лише читання.
• Технічні стелі: бандл до 4 МБ, до 8 мережевих адрес у маніфесті, до 1 МБ на один ключ сховища; серверний прогін — до 30 секунд і до 50 звернень в інтернет за раз.
• Дані плагіна залишаються в хмарі вашого бренду: в облікового запису на cenaly.ru стан серверної частини лежить у російському контурі.

Усунення неполадок#

Часті питання#

Чи потрібно вміти програмувати?#

Щоб встановити готовий реліз — ні. Щоб отримати сам реліз — так: його пише розробник або ІІ-агент за нашим шаблоном із блоку «Розробка з ІІ». Розділ — інструмент для коду, а не конструктор «мишкою».

Чи може чужий плагін побачити моїх клієнтів або виручку?#

Ні. Плагін працює в пісочниці й отримує дані лише через міст, а міст уміє рівно шість речей: каталог, ціни та стоп-листи, довідник складу, власне сховище, виклик своєї серверної частини та елементи інтерфейсу. Гостей, замовлень, чеків, фінансів, співробітників і листування там немає в принципі. Що саме дозволено конкретному плагіну, завжди видно на його картці в рядку «Права».

Як віддати розробку підряднику й не пускати його в обліковий запис цілком?#

Заведіть йому обліковий запис співробітника, а потім видайте грант у блоці «Доступ розробника»: позначте лише потрібні права й поставте строк (за замовчуванням 14 днів, максимум 90). Він отримає режим розробника і нічого більше; встановлення плагіна все одно залишиться за вами. Грант відкликається однією кнопкою.

Чи оновиться плагін сам, коли автор випустить нову версію?#

Ні. Оновлення запускає власник: «Перевірити оновлення» → «Оновити до …». Так нова версія не з'явиться в обліковому записі без відома людини — разом із версією могли змінитися й запитувані права.

Де плагін зберігає свої налаштування та дані?#

У вашому обліковому записі, в окремому сховищі під його ідентифікатором (до 1 МБ на ключ), плюс, якщо він їх використовує, у кастомних полях ваших карток — кожен плагін бачить лише свій простір. В облікового запису на cenaly.ru серверна частина та її стан залишаються в російському контурі.

Чим це відрізняється від API і MCP?#

API для розробників і MCP своєї АТС потрібні, коли програма працює зовні: свій сайт, чужа облікова система, ІІ-агент. Кастомний редактор — навпаки, інтерфейс усередині панелі: співробітник відкриває його як звичайну сторінку адмінки й не виходить із робочого вікна.

Пов'язані розділи#

• Магазин додатків — де вмикається розділ і вбудовані розширення
• Склад — вкладка, у якій живуть розширення на кшталт «ВетИС», і довідник товарів
• Імпорт каталогу — штатний шлях завантаження товарів, якщо задача лише в цьому
• Вітрина на своєму коді (headless) — відкритий контракт даних для зовнішнього сайту
• API і MCP своєї АТС та Guest API для ІІ-агентів — робота зовні, а не всередині панелі
• Співробітники та зміни — обліковий запис для розробника й ролі
• Безпека та дані — де зберігаються дані та хто має до них доступ
• Підтримка — куди писати, якщо плагін поводиться підозріло