Vendor API: разработка приложения для магазина решений

Vendor API 1.0 — это отдельный контур МойСклад для разработчиков приложений: через него платформа сообщает вашему серверу о том, что пользователь установил, настроил или удалил приложение, а вы получаете токены доступа к его аккаунту. Разберём архитектуру, аутентификацию и жизненный цикл приложения на конкретных запросах.

Зачем нужен Vendor API и чем он отличается от JSON API

В экосистеме МойСклад есть два принципиально разных контура. JSON API 1.2 (https://api.moysklad.ru/api/remap/1.2) работает с бизнес-сущностями конкретного аккаунта — товарами, заказами, отгрузками. Vendor API 1.0 (https://apps-api.moysklad.ru/api/vendor/1.0) обслуживает жизненный цикл вашего приложения: установку, настройку, оплату и удаление в чужих аккаунтах.

Логика такая: пользователь ставит приложение из каталога решений, МойСклад дёргает ваш сервер, вы получаете токен доступа к его аккаунту и дальше работаете с данными уже через JSON API 1.2. Без Vendor API опубликовать приложение в магазине решений нельзя — именно он отвечает за интеграцию с площадкой.

• iframe-приложение — встраивается в интерфейс МойСклад через iframe, показывает свой UI внутри аккаунта;
• серверное приложение — работает в фоне без интерфейса, синхронизирует данные;
• смешанное — сочетает iframe для настроек и фоновую логику.

Регистрация приложения в кабинете разработчика

Приложение создаётся в Кабинете разработчика (https://dev.moysklad.ru). При создании платформа выдаёт три ключевых идентификатора, которые нужно надёжно хранить на сервере:

В манифесте приложения (descriptor) вы указываете тип, требуемые scope доступа к JSON API, URL iframe и адрес вашего сервера обработки событий. Запрашивайте ровно те права, которые нужны: минимальный набор scope ускоряет модерацию и вызывает больше доверия у пользователя.

Жизненный цикл: активация, настройка, удаление

Когда пользователь ставит приложение, МойСклад отправляет на ваш сервер запрос PUT /api/moysklad/vendor/1.0/apps/{appId}/{accountId}. Тело содержит причину (cause: Install), данные аккаунта и массив access с токенами доступа к JSON API 1.2.

Ваш сервер обязан ответить статусом приложения. Основные статусы:

• Установка — PUT, вы сохраняете accessToken и отвечаете статусом;
• Проверка статуса — GET того же пути, отдаёте текущее состояние;
• Удаление — DELETE, вы чистите токены и подписки для этого accountId.

Если для работы нужна настройка, верните SettingsRequired — МойСклад подсветит приложение как требующее внимания и предложит пользователю открыть iframe.

Аутентификация: JWT для Vendor API

Запросы к apps-api.moysklad.ru авторизуются Bearer-токеном JWT, который вы подписываете своим secretKey по алгоритму HS256. Заголовок и полезная нагрузка выглядят так:

{"alg":"HS256","typ":"JWT"} — заголовок.

{"sub":"my-app.12345","iat":1721000000,"exp":1721003600,"jti":"a1b2c3"} — payload, где sub = appUid, jti — уникальный идентификатор запроса.

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

Доступ к JSON API 1.2 аккаунта

Главный приз активации — массив access, который приходит в теле PUT. Каждый элемент описывает ресурс и токен:

{"resource":"api.moysklad.ru","scope":["admin","print_custom"],"access_token":"..."}

С этим access_token вы обращаетесь к JSON API 1.2 от имени аккаунта — без логина и пароля пользователя:

GET https://api.moysklad.ru/api/remap/1.2/entity/product с заголовком Authorization: Bearer <access_token>.

• токены привязаны к accountId — храните их раздельно для каждого клиента;
• объём прав ограничен запрошенными scope: чтения справочников, изменения документов, печати и т.д.;
• при удалении приложения токены нужно инвалидировать на своей стороне.

Пример обработчика активации

Упрощённый псевдокод серверного обработчика на Node.js — принимает установку, сохраняет токен и решает, нужна ли настройка:

app.put('/api/moysklad/vendor/1.0/apps/:appId/:accountId', (req, res) => {

  const { access, cause } = req.body;

  const token = access.find(a => a.resource === 'api.moysklad.ru').access_token;

  saveToken(req.params.accountId, token);

  const status = isConfigured(req.params.accountId) ? 'Activated' : 'SettingsRequired';

  return res.json({ status });

});

Ключевые правила надёжности:

1. операция должна быть идемпотентной — повторный PUT с тем же accountId не должен ломать состояние;
2. отвечайте быстро (в пределах таймаута платформы), тяжёлую синхронизацию выносите в фоновую очередь;
3. логируйте cause и accountId — это основа отладки инцидентов.

Отладка и типичные ошибки

Чаще всего интеграция ломается на аутентификации и статусах. Короткий чек-лист:

• синхронизируйте часы сервера по NTP — расхождение бьёт по проверке exp;
• ведите отдельный лог входящих вызовов Vendor API с телом запроса;
• тестируйте на демо-аккаунте перед отправкой на модерацию.

Итог

Vendor API — это «клей» между вашим приложением и платформой: он управляет установкой, настройкой и удалением, выдаёт токены доступа к JSON API 1.2 и позволяет опубликоваться в каталоге решений. Ключевые опоры — корректная JWT-подпись, аккуратная обработка статусов и мультиаккаунтная архитектура хранения токенов.

Мы проектируем и разрабатываем такие интеграции под ключ: серверную часть обработки событий, безопасное хранение секретов, очереди синхронизации и отказоустойчивость под рост числа аккаунтов. Если планируете приложение для магазина решений МойСклад или связку с 1С-Битрикс — поможем спроектировать архитектуру и довести до боевой эксплуатации.