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

Справочник по автономному REST API ДаБонус

Введение

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

Public API позволяет работать с локальными клиентами, заказами, каталогом и магазинами без привязки к МойСклад. Доступ выдаётся отдельными ключами с минимально необходимыми правами (scopes).

Доступность

Public API подключается как отдельный платный модуль независимо от основного тарифа. Владелец аккаунта может купить его в панели DaBonus в разделе «Тариф и оплата», а затем выпустить ключи в настройках интеграций.

Базовый URL

https://api.dabonus.ru/api/v1/public

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

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

Надёжность запросов

Идемпотентность, ограничения частоты и безопасные webhooks

Для каждого POST-запроса обязателен уникальный заголовок Idempotency-Key длиной до 128 символов. Повтор запроса с тем же телом возвращает сохранённый ответ и заголовок Idempotency-Replayed: true.

Idempotency-Key: order-20260901-00042

Стандартный лимит — 300 запросов в минуту на IP-адрес и API-ключ. Текущее состояние передаётся в заголовках X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. При превышении API отвечает кодом 429.

Webhook-адреса управляются через /webhooks. Они должны использовать HTTPS. Подпись находится в заголовке X-DaBonus-Signature и вычисляется как HMAC-SHA256(secret, timestamp + "." + rawBody). Секрет показывается только при создании endpoint или его ротации.

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

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

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

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

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

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

X-API-Key: dabonus_live_YOUR_API_KEY

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

curl -X GET "https://api.dabonus.ru/api/v1/public/customers" \ -H "X-API-Key: dabonus_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, "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

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

Коды ошибок

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 или системы поддержки, у DaBonus есть отдельный набор endpoints для чата. Тот же API-ключ тенанта используется для всех вызовов. Сообщения отправляются клиенту в его подключённый канал — Telegram, MAX или VK, ответ возвращается обратно через webhook на ваш URL.

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

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

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

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

Доступность

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

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

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

JavaScript/Node.js

const axios = require('axios'); const API_URL = 'https://api.dabonus.ru/api/v1/public'; const API_KEY = process.env.DABONUS_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('/orders', { customerId, items: [{ productId: orderId, quantity: 1 }] }, { headers: { 'Idempotency-Key': `order-${orderId}` } }); return response.data; } // Получить клиента по externalId async function getCustomerByExternalId(externalId) { const response = await client.get('/customers', { params: { search: externalId } }); return response.data; }

Python

import os import requests API_URL = 'https://api.dabonus.ru/api/v1/public' API_KEY = os.getenv('DABONUS_API_KEY') class DaBonusClient: 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', params={'search': external_id} ) return response.json() def earn_bonuses(self, customer_id, order_id, order_sum): response = self.session.post( f'{API_URL}/orders', json={ 'customerId': customer_id, 'items': [{'productId': order_id, 'quantity': 1}] }, headers={'Idempotency-Key': f'order-{order_id}'} ) return response.json() # Использование client = DaBonusClient(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