Интеграции

← Оглавление

Раздел «Интеграции» — точка подключения внешних систем к платформе. Интеграция — это касса, сайт или мобильное приложение, которые проводят заказы, начисляют бонусы, читают данные клиентов и узнают акции для гостя через API. Каждая интеграция получает свои API-ключи — «пропуска» с настраиваемыми правами, привязкой к филиалам и сроком действия. Заказы в разделе «Заказы» появляются именно отсюда: их создают системы, подключённые через интеграции.

Зачем это бизнесу#

• Контроль доступа по принципу минимума. Кассе — только проведение заказов и работа с бонусами, витрине сайта — только чтение. Каждая внешняя система получает ровно те права, что ей нужны, и ни правом больше.
• Мгновенное отключение. Сменился подрядчик, утёк ключ, закрылся канал — отключение интеграции одной кнопкой немедленно отзывает доступ по всем её ключам.
• Ключ на филиал. Кассовый ключ можно привязать к конкретной точке продаж — касса одного филиала не проведёт заказ от имени другого.
• Прозрачность. По каждому ключу видно, когда он создан, когда истекает и когда использовался в последний раз — «мёртвые» ключи находятся и отзываются за минуту.

Список интеграций#

Заголовок страницы — «Интеграции», подзаголовок — «Управление интеграциями и API-ключами». В правом верхнем углу — кнопка «Создать интеграцию», над таблицей — поиск и фильтры по статусу, типу и каналу (см. ограничения ниже).

В таблице — колонки Название (ссылка на карточку), Тип, Каналы, Статус, Ключей и Создана. На скриншоте — интеграция демо-организации «Demo POS»: серверная, активная, с каналами pos, web, mobile и двумя ключами.

Два типа интеграций#

Правило простое: если ключ будет лежать на вашем сервере — интеграция серверная; если ключ окажется в коде сайта или приложения, куда может заглянуть любой пользователь, — клиентская, с ограничением по доменам.

Клиентская интеграция: приложение и сайт#

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

• Только API приложения. С клиентским ключом приложение или сайт регистрирует устройство, проводит вход клиента по SMS-коду и показывает клиенту его профиль, бонусы, карты лояльности, акции, личные промокоды, подарочные карты и историю покупок, а также отправляет события приложения (открытие, просмотр экрана или товара). Каждый клиент видит только свои данные — после входа по коду из SMS. Проводить заказы, начислять и списывать бонусы, искать клиентов по телефону такой ключ не может: запросы кассового API с ним отклоняются. Кассе, 1С и серверу сайта нужен ключ серверной интеграции.
• Права — фиксированный набор. Клиентский ключ получает только права приложения: устройства, вход, профиль (просмотр и изменение), бонусы, карты лояльности (просмотр и выпуск виртуальной карты), акции, личные промокоды, подарочные карты, история заказов и события — всего 12 прав. Форма создания ключа клиентской интеграции предлагает только их и «Полный доступ («*»)», причём «Полный доступ» уже выбран — его и оставьте: платформа заменит его всем набором, и в колонке «Доступ» будут видны конкретные права кодами (devices:write, auth:write, profile:read и т. д.). Под списком прав — подсказка, что кассовые права (клиенты, запись заказов и бонусов) клиентскому ключу не выдаются: в форме их нет. Поля «Филиалы» у клиентского ключа тоже нет — приложение работает от имени клиента, а не точки продаж. Отдельные права выбрать можно, но одних «История заказов» или «Акции: чтение» приложению мало: без прав «Устройства: регистрация» и «Вход по SMS-коду» оно не заработает. Если платформа всё же отклонит какое-то право, ключ не создаётся, а под полем «Права доступа» появится строка «Недоступно клиентскому ключу: …» с кодами отклонённых прав.
• «Разрешённые домены» проверяются. Когда ключ работает на сайте, браузер сообщает адрес сайта, и платформа пропускает запрос, только если этот адрес есть в «Разрешённых доменах» интеграции. Записывайте адрес полностью, со схемой и без пути: https://shop.example.com, а не shop.example.com и не https://shop.example.com/catalog. Поддомен и другой порт — отдельные записи. Сайт у интеграции с пустым списком доменов работать не будет. Нативным мобильным приложениям домены не нужны: они адрес не сообщают. Приложения в веб-оболочке (Capacitor, Cordova) сообщают адрес вида capacitor://localhost или http://localhost — добавьте его в список.
• Если у клиентского ключа в колонке «Доступ» стоит «*», платформа всё равно учитывает у него только права приложения — кассовые запросы с ним не пройдут.
• Не встраивайте серверный ключ в приложение. Приложение с серверным ключом получит отказ, а сам ключ после публикации приложения нужно считать раскрытым и отозвать.
• Для Android есть готовая библиотека — Loyalty SDK (dev.relen.loyalty:loyalty-sdk). Она сама регистрирует устройство, проводит вход по SMS-коду, продлевает сессию клиента и отправляет события приложения; разработчику достаточно подключить её и передать адрес платформы и ключ клиентской интеграции. Руководство по подключению библиотеки разработчики приложения получают вместе с ней. Такие же библиотеки есть для приложений на Flutter и для нативных приложений iOS на Swift; iOS-библиотека пока не проверена на iPhone. Как приложение подключается к платформе и что в нём видит клиент — в разделе «Мобильное приложение и SDK».

Клиентам, впервые открывшим приложение, платформа заводит анонимный профиль без телефона — он не виден в списке клиентов и в выгрузках. После входа по SMS-коду анонимный профиль объединяется с клиентом, у которого этот телефон, или сам становится клиентом с этим телефоном, если такого клиента ещё нет. Объединение записывается в журнал объединений с инициатором «Вход в приложении» (см. «Журнал объединений»), а сам анонимный профиль в карточке отмечен меткой «Аноним приложения». Текст SMS с кодом задаётся системным шаблоном system.app-login-code в разделе шаблонов сообщений: он создаётся сам при первом запросе кода, текст можно менять, название — нельзя. SMS с кодом уходят через аккаунт организации у SMS-провайдера (сейчас — Eskiz.uz): без подключения SMS в разделе «Каналы» и, если провайдер модерирует тексты, утверждённого у него текста кода клиенты не смогут войти. Поэтому форма ключа клиентской интеграции с правом «Вход по SMS-коду» или «Полный доступ» предупреждает, если SMS организации не подключены («SMS не подключены — вход в приложение по SMS-коду не работает»), провайдер отклонил настройки («Eskiz.uz отклонил настройки — коды входа не отправляются»), на балансе у провайдера нет средств («коды входа не приходят») или аккаунт не в рабочем статусе («коды входа не уходят»); справкой — если средств мало. Администратору организации предупреждение даёт ссылку «Открыть «Каналы»». Коды входа уходят только SMS: бот организации в Telegram для них не используется, даже если клиент подключил Telegram (см. «Telegram»).

У каждой интеграции задаются каналы продаж — они ограничивают, какие заказы система может проводить: интеграция с каналом «POS» не сможет прислать заказ с пометкой «Website». Канал заказа всегда должен входить в каналы интеграции.

Что касса передаёт и получает при расчёте. Для каждой позиции чека достаточно артикула, названия, цены и количества. Пределы длины: артикул — до 100 символов, название, категория и бренд — до 255; позиция с более длинным значением отклоняется ошибкой проверки (400 VALIDATION_ERROR с путём к полю, например items[0].name) и в расчёте, и в подтверждении. Точка продаж и касса описаны ниже, в «Точка продаж и касса в заказе». Категорию передавать не обязательно: платформа сама находит товар в «Каталоге» по артикулу и берёт оттуда категорию (вместе с родительскими), бренд и теги, поэтому акции по категории работают и на кассе, которая категорию не присылает. Но передавать категорию рекомендуется: подтверждённые заказы синхронизируют каталог с кассой — новые артикулы заводятся товарами с названием и категорией из чека, у существующих товаров обновляются название и переданная категория, недостающие категории создаются сами. Без категории новые товары появятся в каталоге без неё, и раскладывать их придётся вручную. Ручные правки названий в каталоге следующий чек перезапишет — правьте их в учётной системе кассы. Цена всегда берётся из чека. Если сработала акция «Подарок к покупке», в ответе придёт артикул, название и количество подарочного товара, идентификатор (promotionId) и название акции; цены у подарка нет — касса подставляет её сама по артикулу. Подарок — зона платформы: она решает, положен ли он, и при подтверждении сама сохраняет его в заказе. Касса подарок не передаёт ни в расчёт, ни в подтверждение: в items только позиции, которые клиент покупает; строка подарка в чеке нужна лишь для показа клиенту и печати. Добавляйте её с нулевой ценой и не включайте в подытог и в процент скидки: если поставить подарку каталожную цену и скидку 100%, скидка в чеке разойдётся с платформой ровно на цену подарка (платформа подарок скидкой не считает, он учитывается как «подарок × N»).

Идентификатор строки чека. Для каждой позиции касса может передать необязательное поле:

Пробелы по краям обрезаются, пустое значение равносильно непереданному. Повтор идентификатора в одном чеке или значение длиннее 64 символов отклоняются ошибкой проверки 400 VALIDATION_ERROR; для повтора в ответе указаны обе строки, например items[2].positionId — duplicates items[1].positionId. В разных чеках идентификаторы могут совпадать. В ответах расчёта и первого подтверждения строки идут в порядке запроса, но при чтении сохранённого заказа и при повторе подтверждения порядок строк не гарантирован — сопоставляйте строки по positionId, а не по номеру строки или артикулу. У подарков (giftItems) этого поля нет.

"items": [
  { "sku": "PIZZA", "name": "Пицца", "price": 500, "quantity": 1, "positionId": "line-1" },
  { "sku": "PEPPERONI", "name": "Пепперони", "price": 100, "quantity": 1, "positionId": "line-2" },
  { "sku": "PIZZA", "name": "Пицца", "price": 500, "quantity": 1, "positionId": "line-3" },
  { "sku": "PEPPERONI", "name": "Пепперони", "price": 150, "quantity": 2, "positionId": "line-4" }
]

Точка продаж и касса в заказе. Касса передаёт три необязательных поля:

Рекомендуем всегда передавать storeName вместе с storeId и выдавать кассовому ключу право orders:write: тогда открытие новой точки не потребует заранее заводить её в админке. Автоматически созданная точка помечена в разделе «Филиалы» тегом «Создан кассой» — администратор дополняет её адрес. В ответах и вебхуках точка заказа приходит уже внутренним идентификатором платформы.

{
  "channel": "pos",
  "storeId": "NAMANGAN-01",
  "storeName": "Наманган, ул. Навои 12",
  "salePointName": "POS-2",
  "orderNumber": "674",
  "items": [{ "sku": "LAT-001", "name": "Латте", "price": 550.00, "quantity": 1 }]
}

Точка влияет и на акции: акция, ограниченная филиалами (см. «Промо-акции» → «Где действует»), применяется, только если storeId указывает на точку из её списка.

В списке применённых акций ответа (appliedPromotions) только акции, которые что-то дали: скидку больше нуля, подарок, бесплатную единицу или бонусы. Акция, подошедшая по условиям, но не давшая выгоды, в список не попадает.

Что приходит в ответе подтверждения и при чтении заказа. Подтверждённый заказ хранит сработавшие акции и подарки. Ответ подтверждения, чтение заказа по идентификатору или внешнему номеру и ответ возврата содержат appliedPromotions — по объекту на акцию: идентификатор, название, скидка на позициях, начисленные бонусы, число бесплатных единиц и подарки этой акции, — и общий список подарков giftItems в том же формате, что и в расчёте. Обратите внимание: в ответе расчёта appliedPromotions — это список идентификаторов акций, а в ответе подтверждения и чтения заказа — список объектов. Если касса разбирает оба ответа одним кодом, учтите разницу.

Подтверждение заказа: передавайте суммы из расчёта. При подтверждении платформа всегда пересчитывает заказ заново. Между расчётом и подтверждением суммы могут измениться — например, акция закончилась или её приостановили. Чтобы гость не оплатил сумму, отличную от показанной на кассе, передавайте в подтверждении итоговую сумму и сумму скидки из ответа расчёта (expectedFinalTotal, expectedDiscountTotal). Если они разошлись с пересчётом, заказ не подтверждается: касса получает ошибку 409 ORDER_CALCULATION_DRIFT с актуальными суммами, показывает гостю новую сумму и подтверждает заказ повторно. Без этих полей заказ подтверждается молча с новыми суммами.

Подтверждение заказа: номер с чека и внешний ID заказа. В подтверждении касса может передать два разных номера заказа, оба необязательные:

Интеграторам rPos: в externalOrderId по-прежнему передаётся внутренний id заказа rPos, номер с чека — в orderNumber. Пробелы по краям номера обрезаются, пустой номер не сохраняется. Номер записывается только при подтверждении (в расчёте его нет); при повторе подтверждения с тем же ключом идемпотентности остаётся номер, сохранённый первым запросом. В ответах подтверждения, чтения и возврата заказа номер приходит в поле orderNumber.

Статус интеграции — Активна или Отключена. Отключение действует мгновенно и отзывает доступ по всем ключам сразу — это аварийный рубильник на случай инцидента. Кроме того, промо-акции можно ограничивать конкретными интеграциями — акция «только для мобильного приложения» настраивается в разделе «Промо-акции».

Карточка интеграции и API-ключи#

Карточка показывает таблицу «API-ключи» и блок «Сведения» (количество ключей, каналы, разрешённые домены, даты создания и изменения, идентификатор); тип и статус интеграции — в шапке. На скриншоте — карточка «Demo POS» с двумя показательными ключами:

• Глобальный ключ «Demo POS Key» — права «*» (полный доступ), филиалы «Все филиалы», без срока действия;
• Филиальный ключ «Касса — Кофейня в Magic City» — гранулярные права orders:write, customers:read, bonuses:write, привязка к филиалу «Кофейня в Magic City» и срок действия до 1 июля 2027 года.

Колонки таблицы ключей:

Последняя колонка — действия, она закреплена у правого края таблицы. У активных ключей в ней кнопки «Показать ключ» (иконка глаза) и «Отозвать», у отозванных и истёкших она пустая. Если у интеграции ещё нет ключей, вместо таблицы — надпись «Ключей пока нет».

При создании ключа настраиваются:

Сразу после создания ключ показывается целиком — с предупреждением, что его нужно сохранить. В таблице ключи всегда маскируются: видны только первые символы. Кнопка «Показать ключ» (иконка глаза) позволяет администратору посмотреть ключ повторно — каждый такой просмотр фиксируется платформой.

Кнопка «Отозвать» прекращает действие ключа необратимо — восстановить отозванный ключ нельзя, только выпустить новый. Это осознанно: при малейшем подозрении на утечку ключ отзывается без колебаний.

Сколько ключей выдавать кассам#

Выдавайте отдельный ключ каждой точке продаж (или даже каждой кассе), а не один ключ на всю сеть. Платформа ограничивает частоту запросов по одному ключу: не больше 600 в минуту, то есть 10 в секунду. Магазину с шестью кассами в час пик нужно около 0,3 запроса в секунду, в праздники — около 0,6, так что ключа на точку хватает с большим запасом. Один ключ на сеть из десятков магазинов упирается в предел уже в обычный час пик: часть запросов касс отклоняется, и чек, по которому не прошёл расчёт, не проводится.

Отдельная интеграция на каждую точку не нужна — достаточно нескольких ключей в карточке одной интеграции. Ключ точки сразу привяжите к ней в поле «Филиалы»: тогда касса этого филиала не проведёт заказ от имени другого.

Есть и второй предел — 1 200 запросов в минуту с одного сетевого адреса, со всех ключей вместе. Если все кассы сети выходят в интернет через один адрес — общий канал сети, VPN или центральный сервер (1С, ERP, шлюз интегратора), — сообщите об этом администратору платформы до подключения: для такой сети предел по адресу поднимают. Центральному серверу при этом тоже нужен отдельный ключ на каждую точку.

Как понять, что предел достигнут. Касса получает ответ 429 с кодом RATE_LIMIT_EXCEEDED и заголовком Retry-After — через сколько секунд можно повторить запрос. Повторять раньше бесполезно, а повтор подтверждения заказа нужно отправлять с прежним ключом идемпотентности, чтобы не провести заказ дважды. В «Журнале запросов» такие отказы не видны: платформа отклоняет запрос ещё до того, как записывает его в журнал.

Право «Акции: чтение»#

На скриншоте — окно «Создать API-ключ» интеграции «Demo POS»: в списке прав выбраны «Клиенты: чтение» и «Акции: чтение». В форме ключа у права «Акции: чтение» подсказка «Список актуальных акций для клиента по телефону». Оно нужно кассе, серверу сайта или приложения, которые показывают гостю его акции ещё до оформления покупки. Приложение и сайт на клиентском ключе получают акции через API приложения: там клиент определяется по входу, а не по названному телефону. Гость называет телефон, и система возвращает акции, которые действуют прямо сейчас. Каждая акция в списке отмечена одним из двух способов:

• Персональная — действует именно на этого гостя: он состоит в сегменте, на который нацелена акция; или подходит под условия акции по своему профилю (уровень, возраст, день рождения, число заказов); или цепочка выдала ему личный промокод. Такие акции касса видит первыми, вместе с личными промокодами гостя.
• Публичная — работает для всех. Если для неё нужен промокод (например, общий WELCOME10), это тоже видно в списке.

Акции, которые гостю заведомо не подходят, в список не попадают: например, акция для сегмента «VIP» не покажется гостю вне этого сегмента. Также учитываются ограничения акции по интеграциям: акция «только для мобильного приложения» кассе не покажется.

Передавайте код своей точки (storeId). Касса может добавить в запрос акций тот же storeId, что и в расчёте заказа. Тогда в списке только акции, которые действуют в этой точке: акции с условием «Точка продаж» на другую точку и акции, ограниченные другими филиалами, не придут, а промокод такой акции получит ответ «акция гостю сейчас недоступна». Без storeId условие «Точка продаж» список не сужает, а акции, ограниченные полем «Филиалы», не показываются вовсе — поэтому касса, работающая в конкретной точке, должна передавать storeId всегда. Точку этот запрос не создаёт: неизвестный код даёт 404 LOCATION_NOT_FOUND, storeName здесь не передаётся. Пример анонимного запроса: GET /v1/api/promotions/available?storeId=NAMANGAN-01; с телефоном: POST с телом {"phone": "+998 90 100-00-01", "storeId": "NAMANGAN-01"}.

Незнакомый номер — не ошибка, касса получит только публичные акции. Список можно запросить и без телефона, например для витрины сайта, пока гость не вошёл: тогда тоже придут только публичные акции. Условия на сумму чека, товары и время на этом шаге не проверяются, поэтому окончательную скидку показывает только расчёт заказа.

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

Как проверить на демо-данных. В организации, заполненной демо-данными (см. «Настройки» → «Демо-данные»), есть интеграция «Demo POS» с ключом полного доступа, право «Акции: чтение» в него входит. Подключите кассу или приложение этим ключом и запросите акции для нескольких гостей:

• +998 90 100-00-03, Тимур Рахимов — VIP-гость: первой придёт персональная акция «VIP: +5% бонусов».
• +998 90 100-00-01, Алишер Каримов — у него есть личный промокод: персональной придёт «−15% по промокоду из письма» вместе с кодом вида GIFT-XXXXXX.
• +998 90 100-00-19, Азиз Хакимов — у него один заказ: персональной придёт «Второй визит: 10 000 бонусов».
• +998 90 999-99-99 — такого гостя в базе нет: придут только публичные акции, ошибки не будет.

Кроме персональных, все четверо получат одни и те же публичные акции, например «Базовый кешбэк 5%» и «Каждый третий кофе — бесплатно». Сам промокод Алишера при каждом заполнении новый, постоянно только то, что он есть. Если в разделе «Промо-акции» нет акции «Второй визит: 10 000 бонусов», демо-данные заполнены более ранней версией. Чтобы результат совпал с описанным, удалите данные демонстрационной организации и заполните её заново.

Кто что может#

API-ключи — самый чувствительный элемент безопасности организации, поэтому доступ максимально узкий: раздел видит только Администратор организации.

← Оглавление