Руководство по разработке приложений для рынка

Blesium приложения являются дополнения, которые добавляют новые возможности для панелей и продуктов (CRM, ERP, электронной коммерции, почты...) - как Shopify App Store или Slack приложений. Не мобильные приложения, установленные на телефоне.

Рабочая модель

Ваше приложение работает по модели "удаленного HTTP": код не загружается в Blesium, он запускается за пределами сети на вашем сервере и взаимодействует с подписанными, защищенными SSRF, ограниченными скоростью REST-вызовами. Нет прямого доступа к базе данных.

• В Блезиуме. → Идентификация приложения, категория, целевые продукты, запрошенные разрешения, цены и история версий
• У тебя есть. → Само приложение: бизнес-логика, интерфейс, обработка данных
• Доступ к данным → Только через API, только в пределах разрешений, утвержденных арендатором

1. Определите Ваше приложение

Поля, которые необходимо заполнить при создании нового приложения из консоли:

• Имя → Имя отображается в магазине
• Слизевик → Адресное вложение; только строчные буквы, цифры и дефисы
• Категория → Один из следующих канонических списков
• Описание → Что делает приложение
• Целевые продукты → CRM · ERP · B2B · почта · колл-центр · магазин · musavir
• Требуемые разрешения → Области, в которых ваше приложение должно работать
• Ценообразование → Бесплатно · Единовременно · Подписка

Категория должна быть из канонического списка; ключ вне списка будет отклонять представление.

• интеграция → Подключает Blesium к внешней системе
• доклад → Добавление отчета/индикатора на панель
• тема → Визуальная тема
• автоматизация Автоматизация рабочего потока
• канал_продажи → Канал продаж
• Передача сообщений → Сообщения канал
• доставка → Груз/севкият
• виджет → Панель виджетов
• Сектор_пакет → Сектор пакет
• язык_пакет → Языковой пакет
• прочие → Другие

2. Разрешения

Приложение будет запускаться только с теми разрешениями, которые оно запрашивает и арендатор утверждает во время установки. Запросить меньше разрешений: ненужные широкие разрешения потеряют доверие к авторизации установки.

3. Аутентификация

Каждый запрос в Blesium API подписывается с помощью API-ключа. Формат ключа blsk_{ortam}_{kimlik}_{gizli}, а секретная часть показывается только один раз во время создания.

curl https://firmaniz.blescript.com/api/v1/me \
  -H "Authorization: Bearer blsk_live_ab12cd34_gizli-anahtariniz"

4. Прослушивание событий с помощью webhooks

Вместо того, чтобы постоянно задавать вопросы, связаться, когда это происходит. Каждая партия содержит три заголовка:

• Х-блески-выпуск Название события (или. Счет-фактура. оплачена)
• x-blesyum-доставка → Идентификатор доставки; используется для устранения дубликатов
• х-блезюмная подпись → HMAC-SHA256 подпись сырого тела (шестнадцатеричная)

События, на которые можно подписаться, и когда они запускаются:

• invoice.создан → Создание нового счета-фактуры
• счет.оплачен → Счет оплачен
• invoice.refund → Счет возвращен
• subscription.продлен → Подписка продлена
• подписка. План_измененияd → Изменение плана подписки
• подписка.отменена → Подписка отменена
• пользователь. Приглашен → Пользователь приглашен в команду
• user.присоединился → Приглашенный пользователь присоединился
• ticket.создан → Запрос поддержки открыт
• билет.ответил → Ответ на запрос поддержки

Проверьте подпись по отношению к необработанному телу, используя сравнение с фиксированным временем (не в преобразованном виде в JSON — различия в пространстве нарушат подпись):

import crypto from "node:crypto";

export function imzaDogrula(rawBody, header, secret) {
  const beklenen = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(beklenen);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

5. Выпуск

Поля, которые вы вводите при публикации версии:

• Канал → стабильная или бета
• Спред → Постепенное открытие от 0–100%
• Дурум → Передачи или отзыв

Поток публикаций:

1. Отправить версию — Введите номер версии, канал и примечание об изменении.
2. Распаковывайте постепенно — Сначала дайте небольшую часть продукта с процентным распределением.
3. Ожидание обзора — когда приложение проходит обзор, оно выпускается в магазине.
4. Отмена, если необходимо — отмена проблемной версии; запись не удаляется, восстанавливается предыдущая версия.

Показать состояние приложения в консоли:

6. Контрольный список перед выпуском

• Вы минимизировали требуемые разрешения.
• Вы проверяете подпись webhook, не переобрабатывая повторную доставку.
• API-ключ находится только на стороне сервера; ваш поток утечки резервного копирования готов.
• Ваше приложение не останавливает работу арендатора в случае отказа (soft drop).
• Описание и скриншоты показывают, что приложение на самом деле делает.