Жизненный цикл приложения

Узнайте, как приложения проходят путь от разработки до продакшена — от создания черновика до проверки, публикации, версионирования и управления правами.

Статусы приложения

Каждое приложение Bazex проходит через следующие статусы:

DRAFT — Начальный статус. Приложение видно только вам.

↓

PENDING_REVIEW — Отправлено на проверку. Редактирование недоступно.

↓

APPROVED — Опубликовано в маркетплейсе. Продавцы могут устанавливать.

Если приложение отклонено во время проверки, оно возвращается в статус DRAFT с комментариями ревьюера, объясняющими, что необходимо изменить.

Шаг 1: Создайте приложение

Войдите в портал разработчика по адресу admin.bazex.co и перейдите в Developer → My Apps → Create App.

Вам потребуется указать:

Поле	Обязательно	Описание
Name	Да	Отображаемое название (например, "Order Analytics Pro")
Slug	Да	URL-совместимый идентификатор (например, "order-analytics-pro")
Description	Да	Краткое описание, отображаемое на карточках маркетплейса
Category	Да	Одна из: analytics, marketing, sales, shipping, pos, communication, automation, loyalty, other
Scopes	Да	Разрешения, необходимые приложению (например, read_products, read_orders)
Redirect URL	Да	URL обратного вызова OAuth для вашего приложения
Webhook URL	Нет	Базовый URL для доставки вебхуков и вызовов хуков
Icon	Нет	Иконка приложения в каталоге маркетплейса
Screenshots	Нет	До 5 скриншотов для страницы приложения

После создания вы получите Client ID и Client Secret (префикс: fbcs_). Сохраните Client Secret в безопасном месте — он показывается только один раз.

Шаг 2: Тестирование в песочнице

Для каждого аккаунта разработчика автоматически создаётся песочница для тестирования. Вы можете установить приложение в статусе DRAFT на эту песочницу без прохождения проверки.

Test install via APIbash

curl -X POST https://api.bazex.co/developer/apps/APP_ID/test-install \
  -H "Authorization: Bearer YOUR_JWT"

Responsejson

{
  "installationId": "clx1install789",
  "accessToken": "fbat_test_abc123...",
  "webhookSecret": "whsec_test_def456...",
  "businessId": "clx1sandbox123",
  "isTestInstall": true
}

Тестовую установку также можно выполнить через интерфейс портала разработчика. На странице приложения отображается карточка "Test Installation" с кнопкой для установки и диалогом для получения токена доступа.

ℹ

Поведение тестовой установки

• Тестовые установки помечаются флагом isTestInstall: true
• Они исключаются из счётчиков установок и аналитики маркетплейса
• Токен доступа работает со всеми эндпоинтами API, как в продакшене
• Тестовые установки автоматически конвертируются в продакшен-установки после одобрения приложения

Вы также можете протестировать полный OAuth-поток — эндпоинт авторизации OAuth поддерживает роль DEVELOPER и выполняет установку на вашу песочницу.

Управление тестовыми установками

# Check test install status
curl https://api.bazex.co/developer/apps/APP_ID/test-status \
  -H "Authorization: Bearer YOUR_JWT"

# Uninstall test
curl -X POST https://api.bazex.co/developer/apps/APP_ID/test-uninstall \
  -H "Authorization: Bearer YOUR_JWT"

Шаг 3: Настройте манифест

Если ваше приложение использует блоки, вставки или хуки, настройте JSON-манифест в портале разработчика. Манифест определяет точки расширения и синхронизируется с платформой при сохранении. Подробный формат манифеста описан в руководстве Расширения.

Манифест также поддерживает settingsSchema верхнего уровня для глобальных настроек приложения, которые продавцы могут настраивать после установки.

Шаг 4: Отправьте на проверку

Когда приложение готово, нажмите "Submit for Review" в портале разработчика. Приложение перейдёт в статус PENDING_REVIEW.

⚠

Перед отправкой

• Протестируйте все OAuth-потоки и API-вызовы в песочнице
• Убедитесь, что проверка подписи вебхуков работает корректно
• Проверьте, что все блоки правильно отображаются в конструкторе сайта
• Добавьте понятное описание и скриншоты
• Запрашивайте только те разрешения, которые действительно нужны приложению

Пока приложение находится на проверке, его нельзя редактировать. Если нужно внести изменения, дождитесь результата проверки.

Процесс проверки

Команда Bazex проверяет ваше приложение по следующим критериям:

Функциональность — работает ли приложение так, как описано?
Безопасность — безопасно ли приложение обрабатывает данные? Проверяются ли подписи?
Соответствие разрешений — запрашивает ли приложение только необходимые разрешения?
Качество — понятно ли описание? Есть ли скриншоты?
Соблюдение правил — соответствует ли приложение правилам платформы?

Одобрено: Приложение немедленно публикуется в маркетплейсе. Продавцы могут найти и установить его.

Отклонено: Приложение возвращается в статус DRAFT. Ознакомьтесь с комментариями ревьюера, внесите исправления и отправьте повторно.

Версионирование

Ваше приложение имеет поле version, которое можно обновлять в портале разработчика. При обновлении приложения после одобрения платформа отслеживает изменения версий.

Система также хранит снимок approvedScopes — набор разрешений, одобренных во время последней проверки. Это важно для обнаружения расширения прав.

Расширение прав и повторное согласие

Если после установки приложения продавцами вам потребуются дополнительные разрешения, Bazex автоматически обрабатывает процесс повторного согласия:

Добавьте новые разрешения в портале разработчика и отправьте обновление на проверку
После одобрения существующие установки помечаются флагом needsReConsent: true
Продавцы видят запрос на подтверждение дополнительных разрешений в админ-панели
До повторного согласия токен доступа предоставляет только первоначальные разрешения. API-вызовы, требующие новых разрешений, вернут ошибку 403.
После подтверждения продавцом флаг needsReConsent снимается и токен предоставляет полный набор разрешений

💡

Корректная деградация

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

Установка и удаление

Когда продавец устанавливает приложение через маркетплейс:

Он перенаправляется через OAuth-поток (экран согласия → авторизация → обмен токенов)
Создаётся запись AppInstallation
Вы получаете токен доступа, привязанный к бизнесу продавца
Вебхуки, определённые в вашем приложении, автоматически создаются для этого бизнеса
Блоки, вставки и хуки становятся доступны в конструкторе сайта / витрине

Когда продавец удаляет приложение:

Токен доступа отзывается — все API-вызовы будут возвращать 401
Вебхуки для этой установки деактивируются
Блоки удаляются со страниц сайта
Вставки перестают внедряться в витрину
Внутренне генерируется событие app.uninstalled
Через 48 часов отправляется вебхук business.data_erasure — ваше приложение обязано удалить все сохранённые данные продавца (см. Вебхуки)

Управление учётными данными

Вы можете перегенерировать Client Secret приложения в портале разработчика, если он был скомпрометирован. Старый секрет становится недействительным немедленно.

Учётные данные	Префикс	Перегенерация?	Примечание
Client ID	—	Нет	Фиксированный, присваивается при создании
Client Secret	fbcs_	Да	Используется для обмена токенов OAuth (Basic auth)
Access Token	fbat_	Нет	Индивидуальный для установки, выдаётся при OAuth. Отзывается при удалении.
Webhook Secret	whsec_	Нет	Индивидуальный для установки, выдаётся при OAuth

Аналитика разработчика

Портал разработчика предоставляет аналитику для каждого вашего приложения:

Всего установок — общее количество установок за всё время
Активные установки — текущее количество установленных (не удалённых)
Успешность вебхуков — процент успешных доставок вебхуков
Средняя задержка вебхуков — скорость ответа вашего эндпоинта
Тренд установок — 30-дневный график установок и удалений
График доставки вебхуков — 30-дневный график успешных и неудачных доставок

Аналитику также можно получить программно:

curl https://api.bazex.co/developer/apps/APP_ID/analytics \
  -H "Authorization: Bearer YOUR_JWT"

Лучшие практики

Запрашивайте минимум разрешений — продавцы охотнее устанавливают приложения с меньшим количеством запрашиваемых разрешений
Тщательно тестируйте — используйте песочницу для проверки всех функций перед отправкой
Пишите понятные описания — объясните, что делает приложение и зачем оно нужно продавцам
Добавляйте скриншоты — визуальные примеры помогают продавцам понять ваше приложение
Обрабатывайте ошибки корректно — если хук не успевает ответить или API возвращает ошибку, магазин продавца должен продолжать работать
Проверяйте все подписи — всегда валидируйте подписи вебхуков и хуков перед обработкой
Храните токены безопасно — никогда не раскрывайте токены доступа или Client Secret в клиентском коде
Отвечайте на вебхуки быстро — возвращайте 200 в течение нескольких секунд, обрабатывайте события асинхронно