Реализованы 39 путей индексированного каталога и отдельно документированный PUT /retail/giftCard. PARTIAL означает, что отдельные закрытые поля, CRM/RFM-фильтры или внутренние правила BonusPlus ещё требуют сверки на реальном аккаунте. Документация не выдаёт HTTP-паритет за проверенную идентичность бизнес-логики.
01 · Быстрый старт
Рабочая интеграция за четыре шага
Компания определяется API‑ключом. Передавать tenant ID в пользовательских запросах не нужно и нельзя — это защищает данные разных компаний от смешивания.
1
Создайте компанию
Зарегистрируйтесь в кабинете. Компания, программа, подписка и первый безопасный ключ создаются транзакционно.
2
Настройте программу
В разделе «Программа» задайте начисление, скидку и списание. Сохранение создаёт новую неизменяемую версию.
3
Добавьте точку и ЭВОТОР
Создайте магазин, привяжите терминал и выпустите для него отдельный ключ с preset «ЭВОТОР».
4
Проведите тестовый чек
Найдите подтверждённого клиента, запросите quote, примените скидку на кассе, затем hold и commit.
Проверка доступаHTTP
GET /v1/company HTTP/1.1
Host: api.landlancer.online
Authorization: Bearer loy_live_••••••
Accept: application/json
02 · Модель данных
Как связаны компания, клиент и покупка
Компания
Отдельная клиентская база, программа и подписка. У компании может быть несколько торговых точек и касс.
Клиент
Профиль связан с программой лояльности. Если включено подтверждение номера, регистрация завершается после верного кода из SMS.
Баланс
Рассчитывается по журналу операций. Партии бонусов сохраняют сроки активации и сгорания, а возврат связан с исходной покупкой.
Версия правил
Каждый quote хранит policyVersionId. Новая настройка влияет только на новые расчёты и не переписывает старые чеки.
Телефон + OTP→Клиент и карта→Quote→Hold→Продажа / возврат
03 · Правила программы
Настройки и расчёт бонусов
Кабинет не хранит отдельную копию настроек: он создаёт активную policy version, которую читают checkout API и приложение ЭВОТОР.
Процент начисленияrewardRate
Для PERCENT: база × ставка. 5% хранится как 0.05.
Режим начисленияaccrualMode
NONE отключает начисление; PERCENT использует ставку; SPEND_STEP начисляет фиксированное число баллов за полный шаг суммы.
Максимум списанияmaxDebitPercent
Ограничивает долю суммы после внешней и внутренней скидки, которую можно оплатить баллами.
Автоматическая скидкаdiscountPercent
Применяется к каждой строке до списания баллов.
Минимум списанияminimumRewardDebit
Если доступный или запрошенный объём ниже порога, списание равно нулю.
Кратность списанияrewardDebitMultiplicity
Максимум и запрос округляются вниз до заданного шага, например до 25 баллов.
База начисленияrewardCreditBase
GROSS — исходная сумма; PAYABLE — итог после скидок и списания.
ОкруглениеrewardRoundingMode
NONE — до копеек; MATHEMATICAL — до целого по правилам математики; DOWN — вниз до целого.
Совмещение механикcombination flags
Пять отдельных флагов запрещают скидку, начисление или списание при внешней скидке и/или списании баллов.
Активация и срокactivation / lifetime
Новые баллы могут стать доступными позже и сгореть через заданное число дней.
04 · Только ЭВОТОР
От расчёта на кассе до закрытого чека
До установки
Создайте торговую точку и терминал с sourceSystem EVOTOR.
Подтвердите публикацию текущей версии в ЭВОТОР.Маркет, затем откройте карточку 12K Loyalty и выберите кассу.
Получите в кабинете одноразовый код привязки и введите его в приложении.
Во время продажи
Приложение ищет клиента по телефону или QR‑карте.
Quote возвращает построчную скидку, доступное списание и начисление.
После применения скидки создаётся hold; закрытый фискальный чек подтверждается commit.
Повтор запроса безопасен благодаря Idempotency-Key.
Что нельзя подтвердить без оборудования: совместимость конкретной прошивки, сканер, печать extras и поведение после аппаратного обрыва сети требуют финальной проверки на физическом ЭВОТОР.
05 · Клиентские каналы
Регистрация по коду и цифровые карты
SMS OTPПодтверждение номера
Если подтверждение включено в правилах, клиент регистрируется после верного кода. Провайдер настраивается владельцем компании; код хранится в защищённом виде.
Номер карты и QR-код выдаются через API карты участника. Баланс запрашивается отдельно для актуального отображения.
06 · Доступ и безопасность
Ключи по назначению, правила под усиленным контролем
Bearer‑ключ
Секрет показывается один раз, в базе остаётся HMAC digest. Один ключ — одно приложение или одна касса.
Scopes
Ключ получает только нужные права. Preset ЭВОТОР не управляет webhooks или настройками компании.
Изменение процентов
Обычный и бессрочный ключ не получает policies:write. Для миграции нужен отдельный ключ максимум на 24 часа.
Подписка
Истёкшая подписка блокирует операционный API и приложение ЭВОТОР. Незавершённые hold, commit и возвраты можно безопасно завершить.
Коды и персональные данные
Коды подтверждения, Authorization, API-ключи и пароли не должны попадать в журналы приложения.
07 · Запуск
Подготовка к запуску
Настройте в кабинете
Программу и правила бонусов
Торговые точки и кассы
Права сотрудников и API-ключи
Подтверждение номера и согласия
Акции и оформление карт
Проверьте подключения
Назначение тарифа администратором
Настройки SMS-провайдера
Публикацию приложения и тест на вашем ЭВОТОР
Нужные операции при переносе с BonusPlus
Онлайн-оплата пока не подключена. Тариф, срок и лимит касс администратор назначает после согласования. Отправка SMS требует отдельного подключения провайдера.
Состояние сервиса
2
GET/health
12K
Проверить доступность API
READY
Возвращает короткий ответ процесса без обращения к базе данных.
Возвращает безопасный каталог авторизованных пользователей касс ЭВОТОР текущей компании. PIN, телефон и ИНН пользователя ЭВОТОР не принимаются и не сохраняются.
Атомарно сверяет полный снимок товаров одной зарегистрированной точки ЭВОТОР: обновляет переданные позиции и удаляет отсутствующие. Требует Idempotency-Key; пустой снимок принимается только с явным allowEmpty=true.
Создаёт набор импортированных товаров, групп и/или productLabels глобально либо для выбранных storeIds; группа охватывает потомков по pid, метка — товары из любых веток.
Версионно изменяет набор через If-Match: отсутствие storeIds сохраняет область, явный [] включает все точки; checkout доверяет только terminal credential.
Возвращает tenant-scoped правила временного процентного кешбэка, включая расписание, активацию и срок бонусов, товары, исключения, списки клиентов, точки и типы карт.
Создаёт временный процентный кешбэк со стратегией MAXIMUM, отдельной активацией и сроком бонусов, расписанием и tenant-scoped областью товаров, списков клиентов, точек и типов карт.
Версионно изменяет правило через If-Match; checkout применяет его только когда начисление выгоднее базового, а результат и условия бонусного lot сохраняет в quote.
Создаёт серверное правило скидки для счастливых часов: дни недели, локальный интервал, период дат, товары/группы/метки и точки; пустая товарная область означает весь чек.
Возвращает операции бонусного ledger с устойчивыми person/purchase/store/cashier ID, историческим контекстом чека и карты, пагинацией и фильтрами phone, PersonsId, cardNumber, transactionType, creationDate и validUntil.
По исходной feedback capability до её срока действия возвращает доставленный ответ компании или явный статус ожидания без раскрытия других обращений клиента.
Возвращает последнюю утверждённую версию российского юридического документа, дата вступления в силу которой уже наступила; черновики и будущие версии не раскрываются.
Отдаёт PDF последней утверждённой и уже действующей версии как application/pdf с проверяемым SHA-256; для текстовой версии и неопубликованной страницы возвращается 404.
Возвращает единый read-only каталог STANDARD, PROFI и PROFI_PLUS: цены на 1, 6 и 12 месяцев, стоимость дополнительной кассы и список возможностей. Оплату не запускает; тариф выдаётся вручную.
По активной публичной ссылке возвращает бренд программы, тип карты, обязательные поля и актуальные версии документов согласия без раскрытия внутренних идентификаторов компании.
Проверяет одноразовый код и обязательные согласия, атомарно создаёт либо находит клиента, выпускает карту, начисляет настроенный приветственный бонус и возвращает баланс, QR и короткоживущую ссылку электронной карты.
Нормализует российский номер телефона, применяет лимиты по компании, ссылке, номеру и клиентскому адресу и отправляет одноразовый SMS-код; клиент до подтверждения не создаётся.