Список запросов в 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	Идентификатор клиента
email	email
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	количество