Интеграция, которую можно проверить.

Единый REST API связывает клиента, сотрудника, бизнес и внешнюю кассу. Денежные операции подтверждаются сервером, повторные запросы безопасны.

Быстрый старт

1. Создайте ключ программного интерфейса (API) с минимально нужными областями доступа (scope) и филиалами.
2. Найдите клиента или зарегистрируйте участие.
3. Создайте заказ и вызовите метод calculate.
4. Зарезервируйте бонусы, подтвердите оплату методом complete.

curl -X POST https://api.loyra.ru/api/v1/customers/identify \
  -H "Authorization: Bearer $LOYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+79990000000"}'

Авторизация

Передавайте ключ только сервер-сервер: Authorization: Bearer loyra_live_…. Ключ показывается один раз, хранится как hash, ограничивается scopes и филиалами и может быть отозван.

Организации, филиалы и клиенты

Каждый ресурс принадлежит tenant. API определяет организацию по ключу, поэтому внешний tenant_id не принимается. Филиал дополнительно проверяется по ограничению ключа.

Клиент глобален по нормализованному номеру телефона, а его участие и баланс — отдельный membership каждой организации.

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

Программа лояльности и уровни

Расчёт использует версию настроек, фиксированный порядок стадий и округление организации. Уровень пересчитывается после оплаты и возврата.

Жизненный цикл заказа

draft → calculated → completed → partially_refunded/refunded. Calculate возвращает суммы до и после, применённые акции и объяснение каждой скидки.

Reserve блокирует бонусы на 10 минут и защищает от одновременного списания в разных филиалах.

Complete требует внешнюю ссылку платежа для безналичного метода и не сообщает об успехе до фиксации транзакции.

Refund создаёт обратные проводки. Для частичного возврата передайте позиции и количество; исходный заказ не удаляется.

Записи, акции и аудитория

Запись содержит филиал, специалиста, услуги, время, статусы, предоплату и источник. Акции разделяют условия, награду и клиентский анонс.

Динамические сегменты пересчитываются при отправке, учитывают согласие и не закрепляют устаревший состав.

Кампания создаёт отдельную доставку на адресата и канал, сохраняет статусы «отправлено» (sent), «доставлено» (delivered), «открыто» (opened), «переход выполнен» (clicked) и «ошибка» (failed). Перед отправкой проверяются согласие этой организации и канала, стоп-лист, подтверждение адреса и разрешённый поставщик. Внешний провайдер получает поле unsubscribe_url и обязан включить соответствующий способ отказа в сообщение.

Уведомления и вебхуки (webhook)

В кабинете бизнеса выберите события заказов, клиентов, записей, рассылок или подарков ко дню рождения. Сначала сохраните выданный секрет и отправьте синтетический тест. После технической проверки и административного согласования владелец включает рабочую доставку. Неуспешные рабочие запросы повторяются с увеличивающейся задержкой.

LOYRA отправляет JSON методом POST. Тело подписано HMAC SHA‑256 в X-Webhook-Signature, идентификатор попытки передаётся в X-Loyra-Delivery, тип события — в X-Loyra-Event. Получатель должен вернуть HTTP 2xx не позднее чем через 10 секунд и не использовать перенаправление.

const received = request.headers.get("x-webhook-signature")?.replace(/^sha256=/, "") || "";
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received, "hex"), Buffer.from(expected, "hex"));
if (!valid) throw new Error("Invalid signature");

Идемпотентность

Для каждого изменяющего запроса передайте Idempotency-Key. Повтор с тем же payload возвращает сохранённый ответ; другой payload с тем же ключом — 409 idempotency_conflict.

Ошибки

{"error":{"code":"insufficient_bonus_balance","message":"Доступно 240 бонусов из запрошенных 300","request_id":"0d53…","docs_url":"https://docs.loyra.ru/errors"}}

Ограничения частоты запросов (rate limit)

При превышении лимита API возвращает 429 rate_limited. Не запускайте агрессивный повтор (retry): применяйте увеличивающуюся задержку (exponential backoff) со случайным отклонением (jitter) и повторяйте тот же ключ идемпотентности (Idempotency-Key).

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

HTTPS обязателен. QR-токен живёт две минуты и не содержит телефон или баланс. Финансовые изменения журналируются; секреты webhook и API показываются только при создании.

История изменений (changelog)

2026.07

API v1: возвраты по позициям, промокоды, appointments, scopes ключей, FIFO-сгорание бонусов.

Политика

Обратно несовместимые изменения выпускаются только в новой major-версии.

Комплект разработки (SDK) и 1С

Официальный REST-контракт — OpenAPI 3.1. Генерируйте типизированный клиент своим инструментом; готовые SDK будут версионироваться отдельно от API.

OpenAPI

Открыть схему JSON →. Схема подходит для Postman, Insomnia, Swagger UI и генераторов клиента.