Skip to content

Правила разработки миниапов (обязательно к прочтению)

← Home · Это первый документ. Прочитать до начала работы.

Миниап — HTML/JS/CSS-приложение в изолированном iframe внутри Korfix CRM. Эти правила — про безопасность, корректность и портируемость.

Безопасность

Токены и секреты держи в env, не в коде.

  • KORFIX_TOKEN — в переменных окружения разработчика. Никогда не коммить в git миниапа, никогда не класть в zip, никогда не показывать в UI.
  • Если токен попал в коммит — сразу отзови его в /db/api и выпусти новый.
  • Для прода и теста — разные токены.
  • Токен должен иметь минимум прав: только каталоги, которые реально нужны миниапу, только нужные методы (read/write).
  • Секреты в config.json (API-ключи внешних сервисов и т.п.) хранить в App.storage, а не в файлах приложения.

Работа с API — только правильные каналы

Внутри iframe: используй App.fetch('/db/...'). Снаружи (webhook, n8n, скрипты): Authorization: Bearer <token> с /api/....

  • Никогда не делай window.fetch() напрямую из миниапа — CORS его заблокирует.
  • Никогда не используй куки/сессии браузера в обход App.fetch — iframe изолирован, эти механизмы недоступны и могут дать неверный результат.
  • Никогда не захардкоживай URL инстанса (panel.korfix.ru и т.п.) — пиши относительные пути, чтобы приложение работало на любом инстансе.

Что можно положить в zip

Разрешено: .html, .js, .css, .svg, .png, .jpg, .webp, .ico, .gif, .json, .md, .woff, .woff2, .ttf, .eot.

Запрещено: любые исполняемые/серверные расширения — .php, .exe, .sh, .py, .rb и т.п. При попытке загрузить zip с такими файлами платформа откажет.

Серверная логика — только через «удалённое приложение» (install_url вместо urls в config.json). Тогда серверный код живёт на твоём сервере, а миниап получает данные по HTTP от платформы через afterSave-вебхуки.

Портируемость

  • urls в config.json — относительные пути ("main": "index.html"), если приложение упаковано в zip. Платформа сама подставит путь.
  • Не ссылайся на конкретный домен ни в коде миниапа, ни в config.json, если это локальное приложение. Миниап должен работать на panel.korfix.ru, acme.korfix.ru и любом другом инстансе без правок.
  • Не хардкодь ID статей, каталогов, групп — получай их через App.fetch('/db/{catalog}/sheme.json') или catalog_schema().

Владение записей

При создании любой записи через API:

  • alias — генерировать явно: Date.now().toString(36) + Math.random().toString(36).substr(2, 8). Не полагаться на автогенерацию, особенно при массовой вставке.
  • from_auth — ID создающего пользователя. Получать через catalog_schema().from_auth.arr — берёшь ключ отличный от 0.
  • from_group — тенант (группа). Обычно равен from_auth для персональных записей или ID группы для общих.

Без from_auth/from_group запись создаётся на суперадмина и не видна обычным пользователям. Это ошибка, не фича.

Принцип: не искать обходные пути

Если что-то не получается через App.fetch или документированные API — не ищи workaround. Остановись, задай вопрос: либо проблема в документации (раздел не покрыт), либо это действительно не должно делаться.

Примеры чего не надо: - Встраивать <script> с внешнего домена чтобы обойти CORS (вместо этого — App.fetch через postMessage) - Вызывать parent.postMessage напрямую с захардкоженным target origin (пиши через App-методы, они знают откуда пришли) - Сохранять состояние в localStorage iframe'а (изолирован; вместо этого — App.storage) - Использовать <iframe src="/db/..."> для обхода API (интерфейс платформы не гарантирован для встраивания)

Если не хватает API — создай issue в korfixdev/docs или спроси в коммьюнити. Не пиши код, который зависит от неописанного поведения платформы.

См. также

  • getting-started.md — первое приложение с нуля
  • data-api.md — форматы запросов и фильтры
  • js-api.md — VMCRMUserApp: методы и события
  • deploy.md — упаковка и деплой
  • checklist.md — проверка перед релизом

Дальше: getting-started.md · ← Home