Вернуться к документации

REST API для разработчиков

Справочник по REST API МСБонус

Введение

МСБонус предоставляет REST API для интеграции бонусной системы

API позволяет управлять клиентами, начислять и списывать бонусы, получать историю транзакций, настраивать правила начисления и списания, работать с уровнями лояльности.

Доступность

API доступен на тарифах Профессиональный (1 990 ₽/мес), Корпоративный (4 990 ₽/мес) и Максимальный (12 990 ₽/мес). На тарифах Стартовый и Базовый доступ к API недоступен.

Базовый URL

https://api.msbonus.ru/api/v1

Формат данных

  • •Все запросы и ответы используют формат JSON
  • •Кодировка: UTF-8
  • •Даты передаются в формате ISO 8601 (например: 2024-01-28T10:30:00Z)

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

Для работы с API используется API-ключ в заголовке X-API-Key

Получение API-ключа

  1. 1Откройте панель управления МСБонус из меню приложений в МойСклад
  2. 2Перейдите в раздел "Настройки"
  3. 3Найдите секцию "API-ключ"
  4. 4Нажмите "Сгенерировать ключ" (если его ещё нет)
  5. 5Скопируйте ключ (формат: sk_live_...)

Использование API-ключа

Добавьте заголовок X-API-Key ко всем API-запросам:

X-API-Key: sk_live_YOUR_API_KEY

Пример curl-запроса

curl -X GET "https://api.msbonus.ru/api/v1/customers" \ -H "X-API-Key: sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json"

⚠️ Безопасность API-ключа

  • • API-ключ даёт полный доступ к данным вашего аккаунта
  • • Не передавайте ключ третьим лицам
  • • Храните ключ в безопасном месте (переменные окружения, secrets manager)
  • • Никогда не коммитьте ключ в Git-репозиторий
  • • При компрометации немедленно сгенерируйте новый ключ в настройках

Работа с клиентами

API для управления клиентами и их балансами

POST/customers

Создаёт нового клиента в системе

Тело запроса

{ "externalId": "counterparty-uuid-from-moysklad", "phone": "+79991234567", "email": "customer@example.com", "name": "Иван Иванов", "loyaltyTierId": "tier-id-optional" }

Пример ответа (201 Created)

{ "id": "customer-uuid", "externalId": "counterparty-uuid-from-moysklad", "phone": "+79991234567", "email": "customer@example.com", "name": "Иван Иванов", "balance": 0, "lifetimeSpent": 0, "loyaltyTier": null, "createdAt": "2024-01-28T10:00:00Z", "updatedAt": "2024-01-28T10:00:00Z" }
GET/customers

Получает список всех клиентов с пагинацией

Параметры запроса:

  • page — номер страницы (по умолчанию: 1)
  • limit — количество записей (по умолчанию: 20)
  • search — поиск по имени, телефону или email
  • loyaltyTierId — фильтр по уровню лояльности
GET/customers/{id}

Получить клиента по ID

GET/customers/external/{externalId}

Получить клиента по externalId из МойСклад. Используется виджетом МойСклад.

PATCH/customers/{id}

Обновить данные клиента (все поля опциональны)

POST/customers/{id}/recalculate-balance

Пересчитать баланс клиента на основе всех транзакций

Привязка бонусной карты к аккаунту сайта

Подтверждение телефона через МСБонус, без зависимости от CMS

Сайт может сохранить вход покупателя по email и один раз привязать его бонусную карту по телефону. Все запросы выполняет сервер сайта с заголовком X-API-Key. Сервер создаёт случайный bindingId (от 16 до 128 символов), сохраняет его для текущего авторизованного аккаунта и передаёт на всех трёх шагах. Не принимайте bindingId или customerId другого аккаунта из браузера. Включать интеграцию Tilda не требуется.

POST/customer-verification/request-code

Отправить код для привязки

Запрос

{ "bindingId": "b27e019b-8a1c-4dac-8c5b-99e321fe8023", "phone": "+79991234567", "channel": "auto" }

Ответ

{ "challengeId": "НЕПРОЗРАЧНЫЙ_ИДЕНТИФИКАТОР_ИЗ_ОТВЕТА", "channel": "telegram", "expiresIn": 600, "retryAfter": 60 }

auto сначала пробует подключённые к карте Telegram, MAX и VK, затем SMS магазина. bot использует только мессенджеры; sms отправляет только SMS. Для нового участника без подключённого мессенджера нужен настроенный SMS-сервис с поддержкой кодов входа. Код не возвращается в API.

POST/customer-verification/verify-code

Проверить код и найти бонусную карту

Запрос

{ "bindingId": "b27e019b-8a1c-4dac-8c5b-99e321fe8023", "challengeId": "ИДЕНТИФИКАТОР_ИЗ_REQUEST_CODE", "code": "123456" }

Карта найдена

{ "status": "verified", "customerId": "ID_КЛИЕНТА_МСБОНУС", "externalId": "ID_КОНТРАГЕНТА_МОЙСКЛАД", "phone": "+79991234567" }

При status=verified сохраните customerId у авторизованного аккаунта сайта. Баланс запрашивайте через GET /customers/{customerId}/bonus-balance: activeBalance содержит активные бонусы, pendingBalance — ожидающие активации. Если карты нет, ответ содержит status=registration_required, registrationToken, expiresIn=600, registrationAllowed и требования к анкете в registration. Предложите регистрацию только при registrationAllowed=true. Найденный в МойСклад контрагент синхронизируется; новый контрагент на этом шаге не создаётся.

POST/customer-verification/register

Создать участника по подтверждённому телефону

Запрос

{ "bindingId": "b27e019b-8a1c-4dac-8c5b-99e321fe8023", "registrationToken": "ТОКЕН_ИЗ_VERIFY_CODE", "name": "Иван Иванов", "consentAccepted": true }

При необходимости передайте firstName, lastName, birthday (YYYY-MM-DD) и sex (MALE или FEMALE) согласно настройкам анкеты. Телефон берётся из подтверждения, email сайта автоматически в карту не записывается. Метод повторно ищет клиента под общей блокировкой создания. Если карта уже появилась, возвращает её; иначе создаёт контрагента МойСклад и карту МСБонус с учётом лимита тарифа и приветственных бонусов веб-регистрации. Ответ имеет status=verified и customerId. Саморегистрация должна быть включена в настройках магазина.

Срок действия и ошибки

Код действует 10 минут, допускается 5 попыток ввода. Повторная отправка доступна через 60 секунд, не более 5 отправок на телефон за 15 минут и 200 на магазин за час. Ответ 429 содержит retryAfter. Код и токен регистрации одноразовые и связаны с магазином, авторизацией и bindingId. При 409 требуется проверка неоднозначных или недоступных карточек, создавать новую вместо них нельзя. При 503 проверка МойСклад или доставка недоступна. После ошибки обработки подтверждения/регистрации запросите новый код: уже созданная карта будет найдена повторно. Не записывайте коды и токены в логи.

При отсутствии локальной карты выполняется проверка контрагентов МойСклад с нормализацией телефонов, включая дополнительные номера. Проверка ограничена 50 000 контрагентов; если её нельзя завершить, API возвращает 503 и не создаёт новую карту. Для крупных баз предварительно синхронизируйте клиентов. Списание бонусов эти методы не выполняют. Привязку и доступ к балансу своего аккаунта контролирует сервер сайта.

Управление транзакциями

Начисление, списание и управление бонусными транзакциями

POST/transactions/earn

Начисляет бонусы клиенту за покупку с применением правил начисления

Тело запроса

{ "customerId": "customer-uuid", "orderId": "order-uuid-from-moysklad", "orderSum": 10000, "categories": ["category-id-1", "category-id-2"], "items": [ { "categoryId": "category-id-1", "price": 5000 }, { "categoryId": "category-id-2", "price": 5000 } ], "expiresInDays": 365, "description": "Начисление за отгрузку #12345" }
POST/transactions/spend

Списывает бонусы у клиента с проверкой ограничений

Тело запроса

{ "customerId": "customer-uuid", "orderId": "order-uuid-from-moysklad", "amount": 200, "orderSum": 5000, "description": "Списание бонусов по заказу #12346" }

Пример ошибки (400 Bad Request)

{ "statusCode": 400, "message": "Insufficient balance", "error": "Bad Request" }
POST/transactions/refund

Обрабатывает возврат заказа: отменяет начисленные и возвращает списанные бонусы

POST/transactions/adjust

Ручная корректировка баланса клиента (положительная или отрицательная)

POST/transactions/preview/earn

Рассчитывает сумму начисления без создания транзакции

POST/transactions/preview/spend

Рассчитывает максимально возможную сумму списания с учётом ограничений

GET/transactions/history/{customerId}

Получить историю транзакций клиента

Правила начисления и списания

Управление правилами бонусной программы

Правила начисления

POST/rules/earning

Создать правило начисления

Тело запроса

{ "name": "Начисление 5% на всё", "type": "PERCENTAGE", "value": 5, "validityDays": 365, "priority": 0, "conditions": { "minOrderSum": 1000, "categoryIds": ["category-id-1"] }, "isActive": true }
GET/rules/earning

Получить все правила начисления

PATCH/rules/earning/{id}

Обновить правило начисления

DELETE/rules/earning/{id}

Удалить правило начисления

Правила списания

POST/rules/spending

Создать правило списания

Тело запроса

{ "name": "Списание до 10% от заказа", "maxPercentOfPurchase": 10, "conversionRate": 1, "minBonusesToSpend": 50, "excludedCategories": [], "conditions": { "minOrderSum": 1000 }, "isActive": true }
GET/rules/spending

Получить все правила списания

PATCH/rules/spending/{id}

Обновить правило списания

DELETE/rules/spending/{id}

Удалить правило списания

Уровни лояльности

Создание и управление уровнями программы лояльности

POST/loyalty-tiers

Создать уровень лояльности

Тело запроса

{ "name": "Золотой", "slug": "gold", "minLifetimeSpent": 100000, "earnPercent": 5, "benefits": { "freeShipping": true, "prioritySupport": true }, "position": 2, "isActive": true }
GET/loyalty-tiers

Получить все уровни лояльности

PATCH/loyalty-tiers/{id}

Обновить уровень лояльности

POST/loyalty-tiers/recalculate-all

Пересчитать уровни для всех клиентов

Интеграция с МойСклад

API для синхронизации с МойСклад

POST/moysklad/sync/customers

Загружает всех клиентов из МойСклад

POST/moysklad/sync/orders

Синхронизирует заказы из МойСклад

GET/moysklad/check-connection

Проверить подключение к МойСклад

GET/moysklad/product-folders

Получить список всех групп товаров (категорий) из МойСклад

Промокоды в заказах покупателей

Расчёт по товарам до сохранения заказа и работа с существующим заказом МойСклад

Расчёт до создания или изменения заказа

Для внешней интеграции используйте POST /api/v1/moysklad/promo/calculate с X-API-Key компании. Передайте код, UUID связанного контрагента МойСклад и полный будущий состав. Создавать заказ заранее не нужно. Рекомендуем protectFromAutomaticPromotions=true. Возвращённые orderAttributes объедините с attributes своего запроса МойСклад по meta.href, сохранив остальные дополнительные поля. Ответ positionDiscounts идёт в порядке входных товаров, index начинается с 0. Сохраните заказ в МойСклад сразу с этими итоговыми процентами скидок и атрибутами одним POST/PUT, затем передайте code и calculationToken в существующий POST /api/v1/moysklad/customerorder/{orderId}/promo. Этот вызов проверяет и учитывает сохранённый результат, повторно записывать скидки и вызывать preview/confirm не нужно.

Расчёт без заказа, POST /api/v1/moysklad/promo/calculate

{ "code": "SALE10", "customerExternalId": "11111111-1111-4111-8111-111111111111", "protectFromAutomaticPromotions": true, "positions": [ {"assortmentId":"33333333-3333-4333-8333-333333333333","assortmentType":"product","price":500000,"quantity":1,"discount":0} ] }

Фрагмент ответа calculate: перенесите orderAttributes в attributes запроса записи заказа

{ "positionDiscounts": [{"index": 0, "discount": 10}], "orderAttributes": [{ "meta": { "href": "https://api.moysklad.ru/api/remap/1.2/entity/customerorder/metadata/attributes/44444444-4444-4444-8444-444444444444", "type": "attributemetadata", "mediaType": "application/json" }, "value": true }] }

UUID поля в примере условный. Используйте meta и value из фактического ответа calculate. Дополнительный запрос сохранения не нужен: attributes и позиции входят в один запрос заказа.

После сохранения заказа, POST /api/v1/moysklad/customerorder/{orderId}/promo

{ "code": "SALE10", "calculationToken": "Значение calculationToken из ответа calculate без изменений" }

price задаётся до скидок в сотых долях валюты компании, для рублей в копейках. amount и orderSum в ответе указаны в денежных единицах. discount на входе означает исходную ручную скидку до промокода. Не подставляйте сюда итоговую скидку предыдущего расчёта. При следующих изменениях передайте orderId в calculate. Для ранее рассчитанной строки передайте id и опустите discount, чтобы взять её сохранённую исходную скидку; для новой строки без discount используется 0. Для ограниченного по точке кода передайте storeId, UUID склада будущего заказа. Переданный склад проверяется при учёте; без storeId склад не фиксируется в расчёте. Контрагент должен быть связан с активным клиентом МСБонус. Если связи ещё нет, вызовите POST /api/v1/moysklad/sync/customer/{customerExternalId}. При первом применении к существующему заказу можно передать orderId, чтобы исключить сам этот заказ из проверки firstOrderOnly.

Расчёт не меняет заказы, баланс или использование кода и не резервирует лимит. Токен действует 15 минут. При protectFromAutomaticPromotions=true первый вызов может создать только метаданные отдельного необязательного булева поля заказа МСБонус: скидки через API. Нужны права на дополнительные поля. Отказ в доступе даёт 403, конфликт типа существующего поля 409, ошибка чтения или создания метаданных 503, до сохранения заказа интеграцией. Чужие поля не меняются. При учёте проверяются сохранённые товары, цены, количество, скидки, контрагент, валюта и переданный в расчёт склад. При первом применении повторно проверяются активность, срок, лимиты и первый заказ. При пересчёте существующего применения эти проверки не повторяются; проверяются клиент и точка продаж. Изменение настроек между расчётом и учётом требует нового calculate. Повтор последнего успешно учтённого токена для того же неизменённого заказа возвращает alreadyApplied=true без повторного использования кода, даже после истечения срока токена. Привязка первоначального расчёта без orderId к заказу хранится вместе с применением и удаляется при его отмене. После отмены получите новый расчёт; постоянная блокировка прежнего токена не гарантируется. После учёта сверяются уже начисленные бонусы заказа: при noEarnOnSpend несовместимые начисления отменяются. Новые бонусы этот вызов не начисляет, success=true возвращается после сверки. Если сверка после учёта не завершилась, ответ 409 или 503 содержит promoApplied=true и retryWithSameToken=true. Промокод уже учтён. При 409 сначала устраните причину из message, при 503 повторите запрос после временного сбоя. Для неизменённого заказа используйте тот же POST с тем же calculationToken, без нового расчёта и повторной записи скидок. Дополнительное использование не расходуется. При 409 на этапе проверки прочитайте message: устаревший токен требует нового расчёта, конфликт другого сценария нужно сначала устранить. Если после сохранения лимит кода исчерпан или доступ потерян, восстановите исходные скидки либо устраните причину и пересчитайте. Сохраните исходные скидки отправленных строк до успешного учёта для компенсации отказа. DELETE отменяет последнее учтённое применение и не гарантирует откат ещё не учтённого расчёта. Если первое применение не учтено, другого применения нет и вы прекращаете попытку, восстановите собственные исходные скидки и запишите метку из calculate с value=false одним запросом МойСклад. DELETE для этого не нужен. При отказе повторного расчёта уже учтённое применение остаётся: сохраните метку и восстановите последнее согласованное состояние либо завершите новый расчёт. Для отмены самого применения используйте DELETE. При таймауте учёта повторите тот же запрос.

Кто пересчитывает скидки

После успешного учёта с calculationToken возвращаются externallyCalculated=true и autoRecalculate=false. Фоновый обработчик и GET /customer не пересчитывают эти скидки: интеграция повторяет calculate, сохранение заказа и POST promo с новым токеном. DELETE promo возвращает исходные скидки для строк, текущая скидка которых распознана как принадлежащая применению. Новые ручные скидки и скидки ещё не учтённых строк сохраняются, весь заказ не откатывается. Тип, величина скидки, товары, группы и настройка совмещения берутся из снимка первого применения. Для перехода с применения через виджет или старый API сначала один раз отмените код и сохраните восстановленные скидки, затем используйте calculate. Для других заказов поведение виджета сохраняется. При protectFromAutomaticPromotions=true автоматические обработчики МСБонус пропускают изменение скидок, обнаружив записанные orderAttributes, даже до учёта промокода. Новый заказ создавайте сразу с этой меткой. Для существующего заказа обработчик мог прочитать прежнее состояние без метки до вашего сохранения и записать скидки после него. При расхождении POST promo вернёт 409 без учёта нового результата: сверьте заказ и повторите calculate. Одно сохранение при одновременных правках существующего заказа не гарантируется. POST promo проверяет служебную метку из подписанного токена, без неё возвращает 409. GET /customer сообщает discountsManagedByApi=true; это не подтверждает регистрацию промокода. Скидками управляет внешняя интеграция. Для ранее защищённого применения с orderId calculate снова возвращает orderAttributes, даже если параметр пропущен или равен false. Защита касается автоматических скидок МСБонус, не ручных изменений и не других интеграций. По умолчанию параметр false для совместимости: без метки до первого учёта автоматическая акция всё ещё может изменить заказ. Тогда после 409 потребуются сверка и новый расчёт.

Без совмещения промокод заменяет скидку подходящей строки и считается от полной цены. С настройкой Складывать бонусы с текущими скидками он считается после исходной скидки. Минимальные цены и округление могут ограничивать результат. Исходные скидки товаров вне фильтра промокода сохраняются до этапа округления. При включённом priceRounding округление итоговой суммы может изменить итоговые проценты и вне фильтра: при roundAllPrices=false участвуют строки с уже ненулевой скидкой, при true также строки без скидки. Записывайте все возвращённые positionDiscounts. Поддержаны обычные DISCOUNT-промокоды и валюта компании, до 200 строк, без совместного списания бонусов, сертификата, кода активации акции и фиксации скидок. Первое применение без доступной скидки отклоняется. Кроме 200 строк ограничен общий размер расчёта, включая фильтры кода по товарам и группам: слишком большой расчёт отклоняется с HTTP 400 до сохранения заказа. Одинаковые новые строки с разными исходными скидками, но одинаковым итоговым процентом отклоняются: объедините их или задайте одинаковую исходную скидку. Каталог и минимальные цены кэшируются до 60 секунд. Результат calculate фиксируется на срок токена. При учёте каталог, группы и минимальные цены заново не читаются; их изменение само по себе не отменяет токен. Чтобы учесть изменения каталога, получите новый расчёт с учётом указанного срока кэша. Полный контракт полей, ответов и ошибок доступен в Swagger в разделе Интеграция МойСклад.

Применение к уже сохранённому заказу без calculationToken

Передайте UUID заказа МойСклад в orderId и ключ компании в заголовке X-API-Key. Запросы выполняются с сервера вашей интеграции. Сначала сохраните покупателя и позиции заказа в МойСклад, затем получите состояние через GET /api/v1/moysklad/customerorder/{orderId}/customer. Список кодов: GET /api/v1/moysklad/customerorder/{orderId}/promo-codes. Применение: POST /api/v1/moysklad/customerorder/{orderId}/promo. Отмена: DELETE по тому же адресу, без тела запроса. Эти методы требуют существующий заказ. Для расчёта по товарам без orderId используйте calculate, описанный выше. При discountsManagedByApi=true применение без calculationToken отклоняется с 409.

JSON-тело запроса применения

{"code":"SALE10"}

Поле code обязательно: передайте текст выбранного кода без пробелов по краям, не его внутренний id. Заголовок Content-Type: application/json. Клиента, сумму и позиции передавать не нужно, они определяются по сохранённому заказу. Применение изменяет состояние МСБонус, это не предварительный расчёт.

Ответ DISCOUNT, HTTP 201

{ "type": "DISCOUNT", "code": "SALE10", "amount": 100, "positionDiscounts": [ {"id": "22222222-2222-4222-8222-222222222222", "discount": 10} ], "message": "Скидка 100 ₽ по промокоду" }

Сохранение результата

Для DISCOUNT ответ содержит positionDiscounts с UUID позиций и итоговыми процентами скидки. Их нужно отдельно записать через API МойСклад. Значение discount: 10 означает 10%, оно заменяет текущий процент позиции. amount содержит сумму скидки в денежных единицах, не копейках. Для BONUS начисление выполняет МСБонус, amount содержит количество бонусов, positionDiscounts отсутствует.

Запись одной позиции в JSON API МойСклад

PUT https://api.moysklad.ru/api/remap/1.2/entity/customerorder/{orderId}/positions/{positionId} Content-Type: application/json {"discount":10}

Для этого запроса используйте отдельную авторизацию МойСклад с правом изменения заказа. positionId берётся из поля id элемента positionDiscounts, это UUID позиции, не товара. Обновление каждой строки отдельно необязательно: можно обновить заказ целиком с полным массивом positions. Сохраните ответ МСБонус перед записью позиций и после записи проверьте их в МойСклад. Не прибавляйте проценты к текущей скидке и не заменяйте весь состав заказа неполным массивом позиций.

В списке промокодов доступны параметры page (от 1, по умолчанию 1) и limit (от 1 до 50, по умолчанию 10). Ответ содержит promoCodes с полями id, code, description, а также total, page и limit. Список учитывает клиента, товары, точку продаж, сроки и лимиты. Для него должны быть включены promoCodesEnabled и showPromoCodesInWidget; иначе список пуст. Уже использованные коды исключаются. Коды активации акций не входят в этот список, но поддерживают ручной ввод через POST. Список можно запрашивать без предварительного GET /customer, он использует серверный контекст заказа.

Ответ отмены, HTTP 200

{ "success": true, "type": "DISCOUNT", "amount": 100, "positionDiscounts": [ {"id": "22222222-2222-4222-8222-222222222222", "discount": 0} ] }

При отмене DISCOUNT также запишите возвращённые проценты в МойСклад. Не подставляйте ноль самостоятельно. Если ответ содержит orderAttributes, объедините их с attributes и запишите вместе с восстановленными скидками одним запросом заказа. Значение false снимает служебную метку защиты. Сам DELETE не меняет МойСклад; пока метка true, автоматические скидки МСБонус не возобновляются. Для обычных DISCOUNT-применений с сохранёнными исходными скидками возвращаются проценты для восстановления, если текущая скидка строки распознана как принадлежащая применению. Новые ручные скидки и скидки ещё не учтённых строк сохраняются. Это отмена учтённого применения, а не откат всего заказа. Для старых применений без такого состояния восстановление прежних ручных скидок не гарантируется. Коды активации акций используют отдельный снимок исходных скидок. Если использование не найдено, ответ содержит success: false и message при том же HTTP 200. Он также может содержать orderAttributes с value=false, если метаданные поля известны. Это позволяет снять метку, но не восстанавливает исходные скидки неучтённого расчёта; используйте свой снимок. Для BONUS success: true не гарантирует обратную операцию по балансу, необходимо сверить баланс и историю.

Пересчёт после изменения заказа

Для новых обычных скидочных промокодов, применённых без calculationToken и других списаний, ответ содержит autoRecalculate: true. После добавления или удаления товаров, изменения цены или количества сохраните заказ. Виджет запускает синхронизацию, которая пересчитывает сумму промокода и сохраняет скидки в позициях МойСклад. Пересчёт также выполняется при обработке вебхука заказа. Повторное сохранение не расходует новое использование кода. GET состояния заказа обновляет расчёт в МСБонус, но сам не записывает проценты в МойСклад. Внешняя интеграция может записать возвращённые positionDiscounts самостоятельно. При ожидающем preview действуют ограничения, описанные ниже.

Без совмещения процент промокода рассчитывается от полной цены подходящих товаров и заменяет прежнюю скидку. С настройкой Складывать бонусы с текущими скидками процент рассчитывается от стоимости после исходной скидки: при цене 5 000 ₽, исходной скидке 50% и промокоде 20% итог составит 2 000 ₽. Для priceRounding и roundAllPrices действуют описанные выше правила округления, в том числе для товаров вне фильтра. Тип, величина скидки, товары, группы и исходные скидки запоминаются при таком применении. Его отмена возвращает исходные скидки, сохраняя распознанные сторонние изменения; поле orderSum в ответе содержит рассчитанную итоговую сумму и может отсутствовать у старых применений.

Для старых применений без сохранённых исходных скидок автоматический пересчёт не включается задним числом. Применения с externallyCalculated=true обслуживает интеграция через calculate. Для перехода отмените код, проверьте исходные скидки, сохраните заказ и примените код заново, затем запишите полученные скидки. Если одновременно используются списание бонусов, сертификат или фиксация скидок, пересчёт приостанавливается, что отражается в appliedPromo.recalculationPaused. Перед отменой такого промокода сначала отмените остальные списания и снимите фиксацию скидок. autoRecalculate=true само по себе не гарантирует доступность операции. recalculationPaused=false не подтверждает завершение ожидающего preview или запись скидок в МойСклад.

Альтернативный сценарий: preview для кода с автоматическим пересчётом

Если в существующем заказе уже применён обычный DISCOUNT-промокод с autoRecalculate=true, интеграция может передать будущие позиции, получить скидки и сохранить состав заказа сразу с этими скидками. Этот сценарий не выбирает новый промокод и не заменяет его первое применение. Совместное списание бонусов, сертификат и фиксация скидок не поддерживаются. Используйте X-API-Key компании и Content-Type: application/json.

POST /api/v1/moysklad/customerorder/{orderId}/promo/preview { "positions": [ { "clientRef": "existing-line", "id": "22222222-2222-4222-8222-222222222222", "assortmentId": "33333333-3333-4333-8333-333333333333", "assortmentType": "product", "price": 500000, "quantity": 1, "discount": 20 }, { "clientRef": "new-line", "assortmentId": "44444444-4444-4444-8444-444444444444", "assortmentType": "product", "price": 100000, "quantity": 1, "discount": 0 } ] }

Передавайте полный будущий состав, включая неизменённые строки, максимум 200 позиций. price задаётся в сотых долях валюты документа до скидки, для рублей это копейки. quantity должно быть положительным. discount означает текущую скидку, для новой строки это исходная ручная скидка, обычно 0. clientRef — уникальный ключ строки, от 1 до 64 латинских букв, цифр, _ или -. id — UUID строки заказа, его не передают для новой строки. assortmentId — UUID номенклатуры МойСклад, assortmentType принимает product, variant, service или bundle. Для модификации передавайте её UUID и тип variant; основной товар и группу сервер определит самостоятельно.

{ "previewId": "55555555-5555-4555-8555-555555555555", "code": "SALE20", "amount": 1200, "orderSum": 4800, "positionDiscounts": [ { "clientRef": "existing-line", "id": "22222222-2222-4222-8222-222222222222", "discount": 20 }, { "clientRef": "new-line", "discount": 20 } ] }

Сохраните исходный состав заказа со скидками и ответ preview до записи в МойСклад. amount и orderSum в ответе указаны в денежных единицах, не копейках. Метод сохраняет ожидающий план, но не меняет сумму использования, счётчики, баланс и позиции МойСклад. Запишите полный будущий состав с итоговыми процентами из positionDiscounts одним обновлением заказа через API МойСклад. Затем подтвердите результат, передав previewId. Соответствие clientRef / UUID новых строк можно опустить при однозначном сопоставлении; оно обязательно для одинаковых новых строк с разными исходными скидками. Для записи используется PUT /entity/customerorder/{orderId} с массивом positions, по документации МойСклад. Сохраните остальные поля строк, например НДС и резерв, в соответствии с вашим заказом.

POST /api/v1/moysklad/customerorder/{orderId}/promo/confirm { "previewId": "55555555-5555-4555-8555-555555555555", "positions": [ { "clientRef": "new-line", "id": "66666666-6666-4666-8666-666666666666" } ] }

Confirm перечитывает заказ и проверяет фактические товары, цены, количество и скидки. При совпадении фиксирует исходные скидки строк и сумму существующего применения. Сам метод позиции МойСклад не изменяет и бонусы не начисляет. Повтор последнего подтверждённого previewId при неизменённом заказе возвращает alreadyConfirmed=true. Такой же ответ возможен, если вебхук или GET /customer уже подтвердил полностью совпавший план. Отмена preview нужна только при отказе от расчёта, это не обязательный третий вызов.

Незавершённый предварительный расчёт

Пока исходный заказ не изменён, фоновый пересчёт сохраняет его скидки до сохранения или отмены плана. В этом сценарии изменяются только позиции. Контрагента, склад, организацию, валюту, курс, дату документа и канал продаж между preview и confirm менять нельзя. Выполняйте запросы последовательно для одного заказа. При частичной записи, изменении контекста заказа или неоднозначном сопоставлении строк пересчёт этого заказа блокируется, возвращается HTTP 409. При неполной записи завершите сохранение рассчитанного состава и повторите confirm с сохранённым previewId. Если изменились условия расчёта, повтор confirm не устраняет конфликт: восстановите исходные позиции, скидки и контекст, отмените план и выполните новый preview. Если сохранение отменено, восстановите исходные позиции и скидки и вызовите POST /api/v1/moysklad/customerorder/{orderId}/promo/preview/cancel с телом {"previewId":"…"}. Это отменяет ожидающий план, сам промокод остаётся применённым. До записи изменений план можно отменить сразу. Повтор cancel после успешной отмены или подтверждения плана возвращает 409. План не истекает автоматически; незавершённый план может блокировать последующие пересчёты этого заказа. Новый preview заменяет предыдущий только пока сохранённый заказ не изменился.

Поле appliedPromo в состоянии заказа показывает использование кода в МСБонус. Поле websitePromo сообщает о распознанной скидке сайта: её нельзя повторно применять или отменять через эти методы. websitePromo: null не гарантирует отсутствия скидки сайта, распознавание зависит от интеграции и связи заказов. Поле externalId клиента содержит UUID контрагента МойСклад; его Внешний код, externalCode, для привязки не используется.

Повторы и ошибки

Операции МСБонус и МойСклад не атомарны. При таймауте или HTTP 5xx сначала сверяйте appliedPromo, баланс для BONUS и сохранённые скидки МойСклад. Не повторяйте DELETE автоматически: использование могло уже отмениться, и повтор не вернёт проценты для восстановления. Пустой positionDiscounts при DISCOUNT также требует проверки. При HTTP 400 прочитайте message, при 401 проверьте ключ, при 403 доступ к API и подписку, при 404 UUID заказа и контрагента, при 409 состояние заказа и ожидающего preview, при 502 подключение к МойСклад. Для учёта с calculationToken ошибки 409/503 с promoApplied=true обрабатываются повтором того же токена, как описано выше.

Полные схемы и примеры запросов и ответов доступны в разделе Интеграция МойСклад в Swagger. Для применения в Swagger заполните JSON-тело code. Встроенный iframe требует контекст МойСклад, для внешней CRM предусмотрите собственный интерфейс и серверные запросы API.

Коды ошибок

HTTP коды состояния и формат сообщений об ошибках

КодНазваниеОписание
200OKЗапрос успешно обработан
201CreatedРесурс успешно создан
204No ContentУспешное выполнение без возврата данных
400Bad RequestНеверные параметры запроса
401UnauthorizedНеверный или отсутствующий токен
403ForbiddenДоступ запрещён
404Not FoundРесурс не найден
409ConflictКонфликт (например, клиент уже существует)
500Internal Server ErrorВнутренняя ошибка сервера

Формат сообщения об ошибке

{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }

Чат с клиентами

Отдельный API для двусторонних сообщений с клиентом — для интеграции с внешними службами поддержки

Если вы хотите вести переписку с клиентом из своей CRM или системы поддержки, у МСБонус есть отдельный набор endpoints для чата. Тот же API-ключ тенанта используется для всех вызовов. Сообщения отправляются клиенту в его подключённый канал — Telegram, MAX или VK, ответ возвращается обратно через webhook на ваш URL.

Что можно делать через API

  • Получить список диалогов и сообщений
  • Отправить текст или изображение клиенту
  • Подписаться на входящие сообщения через webhook
  • Связать диалог с клиентом по номеру телефона

Когда это пригодится

  • Подключить переписку к собственной CRM
  • Отвечать клиентам из единого окна с другими каналами поддержки
  • Автоматизировать ответы или маршрутизацию диалогов

Доступность

API чата доступен на тех же тарифах, что и основной — Профессиональный, Корпоративный и Максимальный. Чат внутри панели управления продолжает работать параллельно.

Примеры интеграции

Готовые примеры кода для разных языков программирования

JavaScript/Node.js

const axios = require('axios'); const API_URL = 'https://api.msbonus.ru/api/v1'; const API_KEY = process.env.MSBONUS_API_KEY; const client = axios.create({ baseURL: API_URL, headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' } }); // Начислить бонусы async function earnBonuses(customerId, orderId, orderSum) { const response = await client.post('/transactions/earn', { customerId, orderId, orderSum, expiresInDays: 365 }); return response.data; } // Получить клиента по externalId async function getCustomerByExternalId(externalId) { const response = await client.get(`/customers/external/${externalId}`); return response.data; }

Python

import os import requests API_URL = 'https://api.msbonus.ru/api/v1' API_KEY = os.getenv('MSBONUS_API_KEY') class MSBonusClient: def __init__(self, api_key): self.session = requests.Session() self.session.headers.update({ 'X-API-Key': api_key, 'Content-Type': 'application/json' }) def get_customer_by_external_id(self, external_id): response = self.session.get( f'{API_URL}/customers/external/{external_id}' ) return response.json() def earn_bonuses(self, customer_id, order_id, order_sum): response = self.session.post( f'{API_URL}/transactions/earn', json={ 'customerId': customer_id, 'orderId': order_id, 'orderSum': order_sum, 'expiresInDays': 365 } ) return response.json() # Использование client = MSBonusClient(API_KEY) customer = client.get_customer_by_external_id('moysklad-id') result = client.earn_bonuses(customer['id'], 'order-123', 10000)

Интерактивная Swagger документация

Для тестирования API в браузере и просмотра всех доступных параметров используйте интерактивную Swagger документацию:

Открыть Swagger документацию

Нужна помощь?

Если у вас возникли вопросы по этой теме, свяжитесь с нашей поддержкой

Написать в Telegram