REST API для разработчиков
Справочник по REST API МСБонус
Введение
МСБонус предоставляет REST API для интеграции бонусной системы
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Откройте панель управления МСБонус из меню приложений в МойСклад
- 2Перейдите в раздел "Настройки"
- 3Найдите секцию "API-ключ"
- 4Нажмите "Сгенерировать ключ" (если его ещё нет)
- 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 для управления клиентами и их балансами
/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" }/customersПолучает список всех клиентов с пагинацией
Параметры запроса:
page— номер страницы (по умолчанию: 1)limit— количество записей (по умолчанию: 20)search— поиск по имени, телефону или emailloyaltyTierId— фильтр по уровню лояльности
/customers/{id}Получить клиента по ID
/customers/external/{externalId}Получить клиента по externalId из МойСклад. Используется виджетом МойСклад.
/customers/{id}Обновить данные клиента (все поля опциональны)
/customers/{id}/recalculate-balanceПересчитать баланс клиента на основе всех транзакций
Привязка бонусной карты к аккаунту сайта
Подтверждение телефона через МСБонус, без зависимости от CMS
Сайт может сохранить вход покупателя по email и один раз привязать его бонусную карту по телефону. Все запросы выполняет сервер сайта с заголовком X-API-Key. Сервер создаёт случайный bindingId (от 16 до 128 символов), сохраняет его для текущего авторизованного аккаунта и передаёт на всех трёх шагах. Не принимайте bindingId или customerId другого аккаунта из браузера. Включать интеграцию Tilda не требуется.
/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.
/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. Найденный в МойСклад контрагент синхронизируется; новый контрагент на этом шаге не создаётся.
/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. Саморегистрация должна быть включена в настройках магазина.
Срок действия и ошибки
При отсутствии локальной карты выполняется проверка контрагентов МойСклад с нормализацией телефонов, включая дополнительные номера. Проверка ограничена 50 000 контрагентов; если её нельзя завершить, API возвращает 503 и не создаёт новую карту. Для крупных баз предварительно синхронизируйте клиентов. Списание бонусов эти методы не выполняют. Привязку и доступ к балансу своего аккаунта контролирует сервер сайта.
Управление транзакциями
Начисление, списание и управление бонусными транзакциями
/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" }/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" }/transactions/refundОбрабатывает возврат заказа: отменяет начисленные и возвращает списанные бонусы
/transactions/adjustРучная корректировка баланса клиента (положительная или отрицательная)
/transactions/preview/earnРассчитывает сумму начисления без создания транзакции
/transactions/preview/spendРассчитывает максимально возможную сумму списания с учётом ограничений
/transactions/history/{customerId}Получить историю транзакций клиента
Правила начисления и списания
Управление правилами бонусной программы
Правила начисления
/rules/earningСоздать правило начисления
Тело запроса
{ "name": "Начисление 5% на всё", "type": "PERCENTAGE", "value": 5, "validityDays": 365, "priority": 0, "conditions": { "minOrderSum": 1000, "categoryIds": ["category-id-1"] }, "isActive": true }/rules/earningПолучить все правила начисления
/rules/earning/{id}Обновить правило начисления
/rules/earning/{id}Удалить правило начисления
Правила списания
/rules/spendingСоздать правило списания
Тело запроса
{ "name": "Списание до 10% от заказа", "maxPercentOfPurchase": 10, "conversionRate": 1, "minBonusesToSpend": 50, "excludedCategories": [], "conditions": { "minOrderSum": 1000 }, "isActive": true }/rules/spendingПолучить все правила списания
/rules/spending/{id}Обновить правило списания
/rules/spending/{id}Удалить правило списания
Уровни лояльности
Создание и управление уровнями программы лояльности
/loyalty-tiersСоздать уровень лояльности
Тело запроса
{ "name": "Золотой", "slug": "gold", "minLifetimeSpent": 100000, "earnPercent": 5, "benefits": { "freeShipping": true, "prioritySupport": true }, "position": 2, "isActive": true }/loyalty-tiersПолучить все уровни лояльности
/loyalty-tiers/{id}Обновить уровень лояльности
/loyalty-tiers/recalculate-allПересчитать уровни для всех клиентов
Интеграция с МойСклад
API для синхронизации с МойСклад
/moysklad/sync/customersЗагружает всех клиентов из МойСклад
/moysklad/sync/ordersСинхронизирует заказы из МойСклад
/moysklad/check-connectionПроверить подключение к МойСклад
/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. При таймауте учёта повторите тот же запрос.
Кто пересчитывает скидки
Без совмещения промокод заменяет скидку подходящей строки и считается от полной цены. С настройкой Складывать бонусы с текущими скидками он считается после исходной скидки. Минимальные цены и округление могут ограничивать результат. Исходные скидки товаров вне фильтра промокода сохраняются до этапа округления. При включённом 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 ₽ по промокоду" }Сохранение результата
Запись одной позиции в 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 нужна только при отказе от расчёта, это не обязательный третий вызов.
Незавершённый предварительный расчёт
Поле appliedPromo в состоянии заказа показывает использование кода в МСБонус. Поле websitePromo сообщает о распознанной скидке сайта: её нельзя повторно применять или отменять через эти методы. websitePromo: null не гарантирует отсутствия скидки сайта, распознавание зависит от интеграции и связи заказов. Поле externalId клиента содержит UUID контрагента МойСклад; его Внешний код, externalCode, для привязки не используется.
Повторы и ошибки
Полные схемы и примеры запросов и ответов доступны в разделе Интеграция МойСклад в Swagger. Для применения в Swagger заполните JSON-тело code. Встроенный iframe требует контекст МойСклад, для внешней CRM предусмотрите собственный интерфейс и серверные запросы API.
Коды ошибок
HTTP коды состояния и формат сообщений об ошибках
| Код | Название | Описание |
|---|---|---|
| 200 | OK | Запрос успешно обработан |
| 201 | Created | Ресурс успешно создан |
| 204 | No Content | Успешное выполнение без возврата данных |
| 400 | Bad Request | Неверные параметры запроса |
| 401 | Unauthorized | Неверный или отсутствующий токен |
| 403 | Forbidden | Доступ запрещён |
| 404 | Not Found | Ресурс не найден |
| 409 | Conflict | Конфликт (например, клиент уже существует) |
| 500 | Internal Server Error | Внутренняя ошибка сервера |
Формат сообщения об ошибке
{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }Чат с клиентами
Отдельный API для двусторонних сообщений с клиентом — для интеграции с внешними службами поддержки
Если вы хотите вести переписку с клиентом из своей CRM или системы поддержки, у МСБонус есть отдельный набор endpoints для чата. Тот же API-ключ тенанта используется для всех вызовов. Сообщения отправляются клиенту в его подключённый канал — Telegram, MAX или VK, ответ возвращается обратно через webhook на ваш URL.
Что можно делать через API
- Получить список диалогов и сообщений
- Отправить текст или изображение клиенту
- Подписаться на входящие сообщения через webhook
- Связать диалог с клиентом по номеру телефона
Когда это пригодится
- Подключить переписку к собственной CRM
- Отвечать клиентам из единого окна с другими каналами поддержки
- Автоматизировать ответы или маршрутизацию диалогов
Доступность
Примеры интеграции
Готовые примеры кода для разных языков программирования
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