API документация

Справочник по REST API MSBonus

Введение

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

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

Доступность

API доступен на тарифах Профессиональный (1 990 ₽/мес) и Корпоративный (4 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Откройте панель управления MSBonus из меню приложений в МойСклад
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 для управления клиентами и их балансами

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

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

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

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

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, "earnMultiplier": 1.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

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

Коды ошибок

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" }

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

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

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