Магазин и интеграция

01 Магазин и интеграция

Marketplace — каталог приложений Axion: от себя вы распространяете .axn-пакеты, а из своих приложений — ищете и ставите чужие через публичный HTTP API.

1.1Что такое Marketplace

Marketplace — это не магазин в комплекте с движком, а отдельный сервис компании. Движок умеет устанавливать .axn из любого источника; Marketplace добавляет к этому каталог, версии, подписи и статистику:

• Каталог — поиск пакетов по названию, описанию и категориям;
• Версии — у пакета хранится список релизов с контрольными суммами;
• Подписи — каждый релиз подписывается разработчиком, подпись проверяется при установке;
• Права — скачивание доступно по API-ключу или подписке разработчика.

Пользовательский интерфейс каталога — на странице «Платформа». Ниже описан API, который можно вызывать прямо из приложения.

1.2Базовый URL и аутентификация

Все запросы идут к базовому адресу:

https://axion.zerodeon.com/api/axion

Эндпоинты каталога и поиска публичные, но скачивание требует авторизации. Токен передаётся стандартным HTTP-заголовком:

Authorization: Bearer blz_...

Ключ создаётся в разделе Платформа → API-ключи. Для работы магазина ключу нужны права axion:download (скачивание) и axion:stats (статистика) — оба выдаются по умолчанию при создании.

1.3Каталог и поиск

Список пакетов — публичный. Каталог по умолчанию отдаёт первых N пакетов:

GET /api/axion/?limit=30

Поиск по названию и описанию:

GET /api/axion/search?q=code+editor&limit=30

1.3.1

Ответ — массив кратких карточек:

{
  "items": [
    {
      "id": "code_editor",
      "title": "Code Editor",
      "description": "Минималистичный редактор кода",
      "version": "1.2.0",
      "categories": ["devtools"],
      "rating_avg": 4.8,
      "downloads_count": 15402
    }
  ]
}

Доступны и без авторизации — этого достаточно, чтобы показать каталог «до покупки».

1.4Карточка пакета

Детали одного пакета — по его id:

GET /api/axion/:id

Ответ дополняет список метаданными для установки:

{
  "id": "code_editor",
  "title": "Code Editor",
  "version": "1.2.0",
  "developer_name": "axion-labs",
  "description": "...",
  "downloads": 15402,
  "updated_at": "2026-09-01T10:00:00Z"
}

1.5Скачивание и проверка

Для скачивания нужен ключ с правом axion:download (или активная подписка разработчика):

GET /api/axion/:id/download

Ответ не содержит сам файл, а описывает релиз и место загрузки:

{
  "package": {
    "download_url": "https://...",
    "file_name": "code-editor-1.2.0.axn",
    "file_size_bytes": 284163,
    "sha256": "9f8e...",
    "version": "1.2.0"
  },
  "signature": { "value": "MEUC..." }
}

Дальше три проверки перед установкой:

1. Скачайте файл по download_url;
2. Сверьте sha256 — это защищает от подмены при передаче;
3. Проверьте signature.value подписью разработчика.

curl -s https://.../code-editor-1.2.0.axn -o code-editor.axn
echo "9f8e...  code-editor.axn" | sha256sum -c -
axion install code-editor.axn

1.6Встраивание в приложение

API рассчитан на вызовы из вашего кода. Пример — поиск, скачивание и установка прямо из приложения Axion:

const API = "https://axion.zerodeon.com/api/axion";
const key = await window.axion.secrets.get("market_key");

async function find(q) {
  const res = await fetch(API + "/search?q=" +
    encodeURIComponent(q) + "&limit=10");
  return (await res.json()).items;
}

async function install(id) {
  const res = await fetch(API + "/" + id + "/download", {
    headers: { "Authorization": "Bearer " + key }
  });
  if (res.status === 403) throw "no download permission";
  const d = await res.json();
  const file = await fetch(d.package.download_url);
  if (d.package.sha256 !== await sha256(file)) throw "checksum mismatch";
  await window.axion.package.install(d.package.download_url);
}

Для доступа к сети приложению нужна capability network.connect с областью https://axion.zerodeon.com — как заявлено в справочнике.

1.7Ошибки и коды статусов

Ошибки возвращаются в JSON с полем message. Перед повторным запросом стоит дождаться ретрая по Retry-After.

1.8Подписка разработчика

Скачивание и статистика через API доступны по подписке разработчика. Она действует независимо от тарифов Blaze и оплачивается через ЮKassa:

Подписка включает права axion:download и axion:stats. Оформить и отменить её можно в Консоли Marketplace; после отмены доступ сохраняется до конца оплаченного периода.

1.9Публикация пакета

Загрузка нового пакета — POST /api/axion/publish. Требует авторизации и права axion:create:

POST /api/axion/publish

Тело — ZIP-архив с пакетом (метод multipart/form-data, поле file):

curl -X POST https://axion.zerodeon.com/api/axion/publish \
  -H "Authorization: Bearer blz_..." \
  -F "file=@code-editor-1.2.0.axn"

Архив должен содержать манифест store-manifest.json — без него пакет отклоняется:

{
  "id": "code_editor",
  "name": "Code Editor",
  "version": "1.2.0",
  "description": "Минималистичный редактор кода",
  "developer_name": "axion-labs",
  "icon": "icon.png",
  "entry": "index.axn",
  "categories": ["devtools"],
  "tags": ["editor", "code"]
}

Поля icon и entry должны ссылаться на реальные файлы внутри архива — иначе FILE_MISSING. Из содержимого автоматически формируются векторное описание для рекомендаций (glue: name + description + tags + categories).

Успешный ответ (201):

{
  "id": "3f0b1c2e...",
  "slug": "code-editor"
}

1.10Мои пакеты и статистика

Список своих публикаций — только у автора:

GET /api/axion/mine

Статистика скачиваний и установок по всем моим пакетам — с правом axion:stats:

GET /api/axion/me/stats

Показывается суммарная статистика по всем пакетам автора. Приватные эндпоинты /mine и /me/stats требуют токен пользователя, а не только API-ключ.

1.11Персональный поток

Главная Marketplace собирается из блоков. Каталог — публичный, а блоки recommendations и continue появляются только для авторизованного пользователя:

GET /api/axion/home

Ответ — список блоков hero, trending, top, new и (для своих) recommendations/continue. Персональная лента постранично:

GET /api/axion/feed?cursor=...

Поиск при авторизованном пользователе дополнительно учитывает ваши интересы:

GET /api/axion/search?q=editor&limit=30

1.12Похожие и карточка

Похожие пакеты по векторной близости описаний:

GET /api/axion/:id/similar

Карточка пакета возвращает состояние установки (для авторизованного), баннеры и рейтинг:

GET /api/axion/:id

1.13Отзывы, просмотры, установка

Отзывы и оценки по пакету:

GET /api/axion/:id/reviews
POST /api/axion/:id/reviews
GET /api/axion/:id/ratings

Отзыв содержит rating (1–5) и text; создание отзыва требует подписки с правом reviews:write. Учёт просмотров и установки — отдельными вызовами:

POST /api/axion/:id/view
POST /api/axion/:id/install

Изменение метаданных своего пакета — PATCH /api/axion/:id, удаление — DELETE /api/axion/:id (только автор).