Список запросов в SailPlay
Общие положения по обмену с SP
https://ru.sailplay.dev/reference/ogranicheniya-api
Время ожидания ответа от SP указывается в карточке компании. Касса отправляет запрос и ждёт ответа указанное время. Если SP не отвечает, то данная ситуация считается ошибкой ‘Сервер лояльности недоступен’. Касса продолжает работу без обмена с SP.
Если в ответе на запрос приходит код 200, то ответ положительный. Любые другие значения кода ответа и отсутствие ответа трактуются как отрицательный ответ. Действия при получении отрицательного ответа зависят от запроса и места вызова.
Запрос |
Место |
Действие при ошибке |
users/info |
Открытие смены |
Выставить состояние ‘связь отсутствует’ |
|
Начало чека при отсутствии связи |
Ничего не делать |
users/info |
Форма идентификации покупателя |
Отобразить ответ в информационной строке |
send/sms-code |
Форма идентификации покупателя |
Отобразить ответ в информационной строке |
users/add |
Форма идентификации покупателя |
Отобразить ответ в информационной строке |
users/update |
Форма идентификации покупателя |
Отобразить ответ в информационной строке |
Calc |
При изменении чека |
Выставить состояние ‘связь отсутствует’ |
|
В конце чека |
Выставить состояние ‘связь отсутствует’ |
purchases/new |
После оплаты |
Выставить состояние ‘связь отсутствует’ Поместить чек в список неотправленных чеков |
returns/create |
После денежных расчётов |
Ничего не делать |
Тексты запросов и подробные ответы протоколируются в логах кассы.
Действия в случае отсутствия связи с SP
В карточке компании указывается время ожидания ответа на запрос к SP. По истечении указанного времени считается, что связь с SP отсутствует. На экране появляется сообщение для кассира об отсутствии связи с программой лояльности. Соответствующий сигнальный символ в левом верхнем углу экрана загорается красным цветом. Сообщение о потере связи отображается только один раз – при первом неудачном запросе. Для последующих запросов сообщение не выводится. После восстановления связи лампочка загорается зелёным цветом.
Связь с SP проверяется в начале чека запросом users/info для телефона 70000000000. Если связь отсутствует, то при работе с данным чеком запросы в SP не посылаются.
Если связь с SP пропала при создании покупки (был успешно выполнен calc, но неудача при purchases/new), то чек (параметры запроса) сохраняется в отдельном списке для последующей отправки.
Передача неотправленных чеков выполняется при закрытии смены и в специальном пункте меню.
Информация об участниках (клиентах) программы лояльности
https://ru.sailplay.dev/docs/registracia-klienta
Запись клиента имеет три уникальных идентификатора: внутренний id, номер телефона, адрес почты. Для старых клиентов внутренний id будет заполнен номером дисконтной карты. Чем SP будет заполнять внутренний id для новых клиентов, для нас не имеет значения.
Ввод адреса электронной почты, объединение клиентов будут выполняться только в SP.
Запрос ‘Получить информацию о клиенте’ users/info
https://ru.sailplay.dev/reference/users-info
параметр |
описание |
token |
Токен |
store_department_id |
Код из глобальных настроек |
origin_user_id |
Номер телефона или дисконтной карты |
Ответ:
Параметр |
описание |
status |
Код ответа |
id |
Идентификатор клиента |
|
|
phone |
телефон |
first_name |
Имя |
middle_name |
Отчество |
last_name |
Фамилия |
birth_date |
Дата рождения |
origin_user_id |
Номер дисконтной карты |
points |
|
confirmed |
Подтверждённое количество баллов |
Запрос ‘Отправить sms на любой номер’ send/sms-code
https://ru.sailplay.dev/reference/sender-messages-send-sms-code
Параметр |
Описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
user_phone |
Номер телефона |
text |
Константа: Код подтверждения: $[sms_code] |
Ответ:
Параметр |
описание |
status |
Код ответа |
sms-code |
Код подтверждения |
Запрос ‘Регистрация клиента’ users/add
https://ru.sailplay.dev/reference/users-add
Параметр |
описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
target_dep_origin_id |
Код магазина без ведущих 0 |
user_phone |
Номер телефона |
first_name |
Имя |
middle_name |
Отчество |
last_name |
Фамилия |
birth_date |
Дата рождения |
Ответ:
Параметр |
описание |
status |
Код ответа |
id |
Идентификатор клиента |
Запрос ‘Изменить телефон клиента’ users/update
https://ru.sailplay.dev/reference/users-update
Параметр |
описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
new_phone |
Номер телефона |
user_id |
Идентификатор клиента |
Идентификатор клиента можно получить запросами users-info или users-add.
Ответ:
Параметр |
описание |
status |
Код ответа |
Расчёт скидок
https://ru.sailplay.dev/docs/raschet-akcii-dlya-korzini
Для промежуточных расчётов применяется запрос calc. Непосредственно перед оплатой запрашивается число баллов и отправляется финальный запрос calc для учёта баллов.
https://ru.sailplay.dev/docs/sozdanie-pokupki
Подтверждение покупки в SP выполняется двумя запросами: создание покупки и её подтверждение. Для создания выполняется запрос purchases/new, который регистрирует покупку в базе. Подтверждение выполнит SP самостоятельно.
Запрос ‘Рассчитать скидку’ marketing-actions/calc
https://ru.sailplay.dev/docs/raschet-akcii-dlya-korzini
Параметр |
описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
target_dep_origin_id |
Код магазина без ведущих 0 |
user_phone |
Номер телефона |
promocodes |
промокод |
discount_points_writeoff |
Число баллов для списания |
cart |
Json-строка с данными о товарах |
1,2 и т.д. |
Номер позиции |
sku |
Код товара в Домино |
price |
Цена |
quantity |
Количество |
discount_type |
Тип цены |
Пример строки cart:
{"1":{"sku":"5011921150014","price":1600,"quantity":1,”discount_type”:” Regular” }}
discount_type принимает значения:
- Regular – розничная цена
- Sale – распродажная цена
- Red – последняя цена. Если розничная и распродажная цена совпадают.
Если покупатель не идентифицирован, то параметры user_phone и discount_points_writeoff не передаются.
Ответ:
Параметр |
Описание |
status |
Статус ответа |
cart |
|
Id |
Уникальный ID расчёта чека |
positions |
|
product |
|
sku |
Код товара |
price |
Цена |
new_price |
Новая цена |
total_discount_points_max_for_user |
Максимально возможное количество баллов для списания по данному чеку |
num |
Номер позиции |
Максимальное число баллов для списания по этому чеку SP передаёт именно в теге total_discount_points_max_for_user.
Запрос ‘Создать покупку’ purchases/new
https://ru.sailplay.dev/reference/purchases-new
Параметр |
Описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
target_dep_origin_id |
Код магазина без ведущих 0 |
user_phone |
Номер телефона |
order_num |
Уникальный номер чека |
cart_ID |
id расчёта чека |
id расчёта чека – ссылка на ранее выполненный расчёт по запросу Рассчитать скидку.
Order_num потребуется для возврата и он должен быть уникальным. Формируется из трёх параметров: <код магазина>-<номер кассы>-<номер чека в Домино>. Длина: 10 символов -3 символа-3символа= 18
Ответ:
Параметр |
Описание |
status |
Статус ответа |
Никакие другие параметры из ответа не рассматриваются, поскольку все расчёты были сделаны раньше в запросе calc. Создание покупки лишь оформляет чек в SP.
Запрос ‘Подтвердить покупку’ confirm
https://ru.sailplay.dev/reference/purchases-confirm
Обычная схема обмена SP предполагает, что в SP должен быть отправлен запрос purchases/confirm для подтверждения только что созданной покупки. Но в рамках данной задачи отправлять запрос на подтверждение не следует. SP в автоматическом режиме, через заданное время подтвердит покупку.
Возврат товаров
Для оформления возврата у покупателя запрашиваются реквизиты чека продажи. По этим реквизитам выполняется поиск чека продажи. Если продажа была произведена на этой кассе, то чек считывается из базы кассы. В противном случае выполняется запрос чека продажи в SP. После выбора позиций для возврата, чек возврата посылается в SP.
Реализован только частичный возврат, полный возврат по чеку (отмена покупки) в данной версии обмена не предусмотрен.
Запрос ‘Создать возврат’ purchases/returns/create/
https://ru.sailplay.dev/reference/purchases-returns-create
Это запрос для частичного возврата товара, когда покупатель отказался от некоторых позиций, новые позиции не добавлялись.
Параметр |
Описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
target_dep_origin_id |
Код магазина без ведущих 0 |
user_phone |
Номер телефона |
order_num |
уникальный номер чека |
return_cart |
|
1, 2 и т.д. |
Номер позиции в чеке покупки |
quantity |
Количество штук возврата |
reason |
Причина возврата |
Уникальный номер чека был передан в SP в запросе ‘Создать покупку’.
Пример заполнения return_cart: "1": {"quantity": 3, "reason": "Брак"},"3": {"quantity": 1, "reason": "Не подошёл размер"}}'
Ответ:
Параметр |
Описание |
status |
Статус ответа |
Запрос ‘Получить покупку’ purchases/get
https://ru.sailplay.dev/reference/purchases-get
Параметр |
Описание |
token |
Токен |
store_department_id |
код из глобальных настроек |
order_num |
Уникальный номер чека |
Ответ:
Параметр |
Описание |
status |
Статус ответа |
cart |
|
positions |
|
product |
|
sku |
Код товара |
price |
Цена |
new_price |
Новая цена |
num |
Номер позиции |
quantity |
количество |
No Comments