Доступ к API

Отдельный модуль для собственных касс, CRM, сайтов и автоматизаций

Самостоятельный API

Работает напрямую с ядром ДАБонус

API работает с клиентами, заказами, каталогом и точками продаж конкретной компании. Для него не требуется МойСклад, CRM или другой внешний сервис. Каждый ключ принадлежит только одной компании и получает только выбранные владельцем права.

Основной адрес

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

Авторизация

X-API-Key

Формат

JSON · UTF-8 · HTTPS

Проверка ключа

curl "https://api.dabonus.ru/api/v1/public/me" \ -H "X-API-Key: $DABONUS_API_KEY"

Подключение модуля

Владелец компании подключает доступ к API в разделе «Биллинг», а ключи создаёт в «Настройки → API». Для каждой системы и среды используйте отдельный ключ.

Права доступа

Минимальный набор разрешений для каждого ключа

Разрешение	Что разрешает
`customers:read`	Список и поиск клиентов
`customers:write`	Создание и изменение клиентов
`orders:read`	Список заказов
`orders:write`	Создание заказов
`catalog:read`	Чтение каталога
`catalog:write`	Создание и изменение товаров
`stores:read`	Чтение точек продаж
`stores:write`	Создание точек продаж
`webhooks:manage`	Endpoints, события и ротация секрета

Запрос без необходимого разрешения завершается ошибкой 403.

Надёжная запись

Идемпотентность и ограничение частоты

Idempotency-Key

Передавайте уникальный ключ во всех изменяющих POST-запросах. Повтор с тем же телом вернёт сохранённый результат, а другое тело с тем же ключом будет отклонено как конфликт.

Idempotency-Key: order-20260902-000042

300 запросов в минуту

Лимит действует на пару IP + API-ключ. Остаток и время сброса приходят в заголовках X-RateLimit-*; при превышении API отвечает 429.

Ресурсы

Основные запросы к API

Клиенты

GET/customers?page=1&limit=50&search=7999Список и поиск

POST/customersСоздать клиента

PATCH/customers/:idИзменить клиента

Заказы

GET/orders?page=1&limit=50Список заказов

POST/ordersСоздать заказ

Каталог

GET/catalog/products?page=1&limit=50&search=кофеСписок товаров

POST/catalog/productsСоздать товар

PATCH/catalog/products/:idИзменить товар

Точки продаж

GET/storesСписок точек

POST/storesСоздать точку

Создание заказа

{ "customerId": "customer-uuid", "storeId": "store-uuid", "comment": "Заказ из собственной кассы", "items": [ { "productId": "product-uuid", "quantity": 2 } ] }

Внешние идентификаторы товаров

Вместо productId можно передать productExternalId и provider. Поддерживаемые провайдеры: MOYSKLAD, AMOCRM, BITRIX24, ONE_C, WORDPRESS, OPENCART, TILDA и PUBLIC_API.

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

Подтверждение телефона через сервер вашего сайта

Создайте случайный bindingId на сервере и свяжите его с авторизованным аккаунтом покупателя. На всех шагах используйте один bindingId и один API-ключ. Для запроса и проверки кода нужны права customers:read, для регистрации customers:write.

Отправить код

POST /customer-verification/request-code { "phone": "+79991234567", "bindingId": "website-account-random-binding", "channel": "auto" }

Ответ содержит challengeId. В режиме auto код доставляется через подключённый бот Telegram, MAX или ВКонтакте, затем через SMS магазина. Можно указать bot или sms. Код действует 10 минут; повторная отправка доступна через 60 секунд.

Проверить код

POST /customer-verification/verify-code { "challengeId": "ID_FROM_REQUEST_CODE", "bindingId": "website-account-random-binding", "code": "123456" }

При status=verified сохраните customerId в аккаунте покупателя на сервере. Поиск выполняется в общем реестре ДАБонус. Существующая карта сохраняет баланс, профиль и историю, повторный приветственный бонус не начисляется. Если карта не найдена, ответ registration_required содержит registrationToken и требования к анкете.

Зарегистрировать нового участника

POST /customer-verification/register { "registrationToken": "TOKEN_FROM_VERIFY_CODE", "bindingId": "website-account-random-binding", "name": "Иван Иванов", "consentAccepted": true }

Регистрация доступна при включённой саморегистрации. Дополнительные поля анкеты зависят от настроек компании. Телефон берётся из подтверждённого токена. Новая карта использует обычные правила веб-регистрации и лимит клиентов.

Одноразовые данные

Код допускает пять попыток, registrationToken действует 10 минут и используется один раз. Не помещайте API-ключ, код или токен в URL и логи. После ошибки регистрации запросите новый код. Эти методы используют одноразовые токены; Idempotency-Key для них не требуется.

Webhooks

События ДАБонус в вашей системе

Создайте HTTPS endpoint, выберите события и сохраните выданный секрет. Секрет показывается только при создании получателя или после ротации.

Управление получателями

GET /webhooks/events GET /webhooks POST /webhooks PATCH /webhooks/:id DELETE /webhooks/:id POST /webhooks/:id/rotate-secret

Проверка подписи

X-DaBonus-Signature: v1=... HMAC-SHA256(secret, timestamp + "." + rawBody)

Проверяйте исходное тело

Вычисляйте подпись по исходным байтам запроса и отклоняйте сообщения с устаревшим timestamp. Не пересобирайте JSON перед проверкой HMAC.

Безопасность

Правила для production-интеграции

• Храните ключи в secrets manager или переменных окружения.
• Не размещайте API-ключ в браузере, Mini App или мобильном приложении.
• Выдавайте минимальный набор scopes и отдельный ключ каждой системе.
• Сразу ротируйте скомпрометированный ключ и webhook-секрет.
• Сохраняйте собственный идентификатор операции в Idempotency-Key.

Интерактивная схема API

Полный список параметров и ответов доступен в Swagger.

Открыть Swagger

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

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

Написать в поддержку в Telegram