Рецепты интеграций

Пять задач, которые чаще всего решают через External API: синхронизация каталога, приём заказов и лидов с сайта, выгрузка продаж и онлайн-запись. Каждый рецепт — порядок вызовов, готовый curl и событие, на которое стоит подписаться вместо опроса.

Общие правила (аутентификация, форматы, пагинация, коды ошибок) описаны в статье External API, полный перечень методов — в Справочнике API. В примерах токен лежит в переменной MBS_TOKEN.

Синхронизация каталога с маркетплейсом

Витрина на стороне маркетплейса показывает те же позиции и цены, что и каталог компании.

Заведите токен со scope catalog:write — он включает чтение.
Заберите каталог страницами по 50 позиций, пока не выберете total.
Сопоставьте позиции по штрихкоду или артикулу и сохраните у себя пару «наш идентификатор — идентификатор маркетплейса».
Изменения возвращайте точечными PATCH по идентификатору товара.

curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://app.easymb.ru/api/external/v1/catalog/products?page=1&pageSize=50"

Цены приходят в копейках: 120000 — это 1 200 ₽. Например, каталог кофейни на 30 позиций выбирается одной страницей, и полный обход занимает один запрос.

Остатки живут отдельно от карточки товара: читайте их через warehouse/stocks, а меняйте только через warehouse/stocks/adjust. Подпишитесь на product.created, product.updated и product.bulk_repriced — тогда полный обход достаточно делать раз в сутки.

Приём заказов с сайта

Сайт оформляет заказ, а система ведёт его дальше по статусам.

Токен со scope orders:write и clients:write.
Найдите клиента по телефону через clients с параметром search или создайте нового.
Создайте заказ и передайте X-Idempotency-Key: обрыв связи после отправки не создаст второй заказ.
Статусами управляйте через смену статуса, а не пересозданием заказа.

curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)" \
-d '{
      "customerId": "123e4567-e89b-12d3-a456-426614174000",
      "items": [
        { "kind": "product", "refId": "…", "qty": 2, "unitPrice": 125000 }
      ]
    }' \
https://app.easymb.ru/api/external/v1/orders

Например, две упаковки по 1 250 ₽ дают заказ на 2 500 ₽: unitPrice задаётся в копейках за единицу, сумму система считает сама.

Ключ идемпотентности — UUID, уникальный для попытки. Пока первая попытка ещё выполняется, повтор с тем же ключом получает 409 с кодом IDEMPOTENCY_IN_FLIGHT: подождите секунду и повторите, чтобы забрать ответ первой.

Слушайте order.created и order.status_changed — в обоих data несёт заказ целиком, у смены статуса ещё и previousStatus; факт отгрузки ловите по событию order.shipped: его рождает проведённая накладная.

Выгрузка продаж в бухгалтерию

Надёжная схема — быстрый триггер плюс ночная сверка.

Подпишитесь на событие sale.completed и складывайте чеки у себя сразу после закрытия.
Раз в сутки перечитывайте продажи за прошедший день и сверяйте с тем, что дошло.
Расхождение означает пропущенную доставку: посмотрите её в истории доставок подписки.

curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://app.easymb.ru/api/external/v1/sales?dateFrom=2026-08-04T00:00:00.000Z&dateTo=2026-08-04T23:59:59.999Z&pageSize=100"

Даты передаются в UTC, поэтому смену с 9:00 до 21:00 по Москве забирают интервалом с 06:00 до 18:00 UTC. Возвраты приходят отдельным событием sale.refunded — в бухгалтерию они уходят такой же проводкой, только со знаком минус.

Приём лидов из формы на сайте

Заявка с лендинга попадает в раздел «Лиды» и превращается в клиента или сделку.

Токен со scope leads:write; у компании должен быть включён компонент «Маркетинг» (для конвертации в сделку — ещё и «Сделки»).
Отправьте заявку, передав externalId — номер записи в вашей форме.
Дальше меняйте статус, назначайте ответственного или конвертируйте лид.

curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
      "name": "Иван Петров",
      "phone": "+79991234567",
      "message": "Хочу записаться на диагностику",
      "source": "landing",
      "externalId": "form-8123",
      "utm": { "source": "yandex", "medium": "cpc", "campaign": "spring" }
    }' \
https://app.easymb.ru/api/external/v1/leads

Создание идемпотентно по паре «источник плюс externalId»: повторная отправка той же заявки возвращает уже созданный лид и не поднимает второе событие lead.created. Например, форма на лендинге отправляет заявку дважды из-за двойного клика — в системе она одна.

Конвертация — два разных вызова: leads/{id}/convert заводит клиента и возвращает clientId, leads/{id}/convert-deal заводит клиента и сделку и возвращает dealId. Статусы лида: new, in_progress, converted, spam.

Онлайн-запись клиента

Форма записи на сайте показывает свободное время и создаёт бронь.

Токен со scope scheduling:write; включён компонент «Планирование».
Покажите свободные интервалы ресурса на выбранный день.
Создайте бронь на выбранный интервал.
Дождитесь подтверждения администратором или клиентом.

curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://app.easymb.ru/api/external/v1/scheduling/bookings/slots?resourceId=…&date=2026-08-05&serviceId=…"

Ответ — массив интервалов с полем free. Если передан serviceId, шаг сетки берётся из длительности услуги: стрижка на 60 минут даёт слоты 10:00–11:00, 11:00–12:00 и так далее.

curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)" \
-d '{
      "resourceId": "…",
      "serviceId": "…",
      "startAt": "2026-08-05T07:00:00.000Z",
      "customerName": "Иван Петров",
      "customerPhone": "+79991234567"
    }' \
https://app.easymb.ru/api/external/v1/scheduling/bookings

Бронь создаётся в статусе pending. Подтверждение приходит событием booking.confirmed, неявка — booking.no_show, завершение — booking.completed; вместе с каждым из них приходит и booking.status_changed. Свой статус можно проставить через смену статуса брони.

Чек-лист перед продом

Отдельный токен на каждую интеграцию, с минимальным набором scope.
Секрет в защищённом хранилище, а не в репозитории и не в переменной сборки фронта.
Обработаны 429, IDEMPOTENCY_IN_FLIGHT и сетевые ошибки: повтор с увеличением паузы.
Все мутации идут с заголовком X-Idempotency-Key.
Клиент не падает на незнакомых полях в ответах.
Настроен мониторинг: 401 и 403 поднимают тревогу.
У вебхуков проверяется подпись, а история доставок просматривается хотя бы раз в неделю.

Коротко

Каталог и продажи выгружаются страницами, изменения ловятся событиями.
Заказы и брони создаются с ключом идемпотентности: повтор не даёт дубля.
Лиды дедуплицируются по вашему externalId в рамках источника.
Свободное время для онлайн-записи отдаёт запрос слотов ресурса на день.

См. также: External API, Webhooks, Справочник API.