# Работа с заказом

При оплате заказа покупатель может снизить стоимость к оплате за счет акций, персональных скидок и бонусов.

В этом документе рассматривается жизненный цикл заказа и способ интеграции с сайтом и кассовыми системами.

Важно

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

# Статусы заказов в программе лояльности

Заказ может быть в следующих статусах:

оформлен (pending);
оплачен и исполнен (confirmed);
отменен (cancelled);
частично изменен (pending или confirmed).

Когда заказ оформлен (pending), происходит списание бонусов со счета покупателя для снижения стоимости заказа.

Когда заказ оплачен и исполнен (confirmed) дополнительно происходит начисление бонусов за заказ, если включена бонусная программа.

Когда заказ отменен (cancelled), то отменяются начисленные бонусы (если включена бонусная программа лояльности) и возмещаются списанные бонусы (если не отключена настройка "возвращать бонусы, использованные при оформлении заказа").

Статус частично изменен не имеет отдельного кода статуса. При изменении состава оформленного (pending) или оплаченного и исполненного (confirmed) заказа, покупателю возмещается часть списанных бонусов и снижается сумма начисленных бонусов. Это происходит, например, при возврате части товаров заказа.

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

# Требования к участию в программе лояльности

Работа с бонусами и персональными скидками требует наличие у покупателя идентификатора участника программы лояльности. Подробнее о том, как стать участником.

Работа с акциями не требует от покупателя быть участником программы лояльности.

# API-методы

Для работы с заказом имеются следующие методы:

Метод	Описание
loyalty/checkout/estimate (opens new window)	оценка стоимости текущей корзины с учетом бонусов и скидок
loyalty/checkout/apply (opens new window)	применить бонусы и скидки к корзине (создает заказ в статусе `pending`, списывает бонусы)
loyalty/checkout/cancel (opens new window)	отменить заказ (возвращает использованные бонусы, переводит заказ в статус `cancelled`)
loyalty/checkout/confirm (opens new window)	потвердить заказ после оплаты (начисляет бонусы за заказ, переводит в статус `confirmed`)
loyalty/checkout/change (opens new window)	изменить состав заказа (уменьшает начисленные и восстанавливает часть списанных бонусов для заказов в статусе `pending` и `confirmed`)
loyalty/checkout/details (opens new window)	получить детали заказа: сколько бонусов и скидок было применено к заказу и каждому товару в отдельности

# Интеграция

Общая схема для интеграции на кассе и для сайта выглядит почти одинаково. С разницей, что на кассе может потребоваться подтверждение владельца идентификатора программы лояльности по СМС (опционально).

# Оценка корзины

Сначала необходимо оценить стоимость корзины с учетом скидок, акций и бонусов. Это делается методом API loyalty/checkout/estimate (opens new window).

Если покупатель не является участником ПЛ (идентификатор не передан или передан, но не зарегистрирован в программе), в расчете будут учтены только акции.

Если покупатель является участником ПЛ, то будут применены (строго в указанном порядке):

акции, если есть активные;
скидки, если скидочная программа включена и у товаров в корзине нет запрета к применению скидок;
бонусы, если бонусная программа включена, в запросе передан флаг use_bonuses, у покупателя есть активные бонусы и у товаров в корзине нет запрета к применению бонусов.

На результат расчета могут повлиять такие настройки программы лояльности, как:

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

Метод API отдает состав заказа, а также информацию о скидках и бонусах. Из важных свойств стоит отметить:

order_total – исходная стоимость заказа
order_discount – полная скидка заказа
order_to_pay – сумма к оплате
order_bonuses_to_charge – кол-во бонусов к списанию.

Если покупатель не хочет использовать бонусы (нет возможности верифицировать себя по СМС или просто не хочет), то в запросе необходимо передать флаг use_bonuses=false. Расчет будет произведен без учета бонусов.

# Оформление заказа и списание бонусов

Когда вся корзина посчитана, клиент решил, что делать с бонусами и готов к оплате, необходимо:

Создать на своей стороне номер заказа.
Выполнить метод loyalty/checkout/apply (opens new window), передав ту же структуру, что и в loyalty/checkout/estimate (opens new window), но дополнительно с полем order_id, которое содержит номер заказа.
Получить сумму к оплате и провести ее.

Не делать лишнего

Если покупатель не является участником программы лояльности и вы не используете акции/офферы, то эту операцию и все последующие можно не выполнять.

Что происходит при выполнении этого метода:

К текущей корзине применяются (в этом же порядке):
- акции;
- скидки участника программы лояльности;
- бонусы участника программы лояльности.
Списываются бонусы, если передан флаг use_bonuses.
Рассчитывается конечная сумма к оплате.

# Подтверждение оплаты

Когда оплата успешно проведена, необходимо выполнить запрос на loyalty/checkout/confirm (opens new window) с теми же данными, что и в loyalty/checkout/apply (opens new window).

Что происходит при выполнении этого метода:

Заказ программы лояльности отмечается как оплаченный (не имеет отношения к синхронизации статусов заказов).
Покупателю начисляются бонусы за заказ, если он является участником программы лояльности и выполнено одно из условий:
- в заказе не были использованы бонусы для снижения цены;
- в заказе были использованы бонусы, но в программе лояльности активирована настройка Можно одновременно получать и тратить бонусы в одном заказе.

Бонусы начисляются с учетом срока активации бонусов в настройках программы лояльности. Рекомендуется ставить срок активации не менее 14 дней, чтобы избежать сложностей с пересчетом бонусов при частичном возврате заказа.

# Отмена заказа

Отмена может потребоваться в одном из следующих случаях:

У клиента не хватило денег, чтобы оплатить заказ на кассе или он просто отказался от оплаты.
Заказ на сайте оформлен, но клиент так и не оплатил его.
Клиент оплатил и получил заказ, но вернул его полностью.

В этом случае необходимо использовать метод loyalty/checkout/cancel (opens new window), чтобы:

отменить заказ в программе лояльности;
вернуть потраченные бонусы;
отменить начисленные бонусы, если заказ ранее был подтвержден.

Что происходит при выполнении этого метода:

Заказ отмечается как отмененный (не имеет отношения к синхронизации статусов заказов).
Списанные бонусы создаются заново с датой активации текущим днем, если не отключена настройка Возвращать клиенту потраченные бонусы при отмене заказа.
Бонусы, начисленные за оформление заказа отменяются.

# Изменение заказа

Если клиент вернул часть товаров, но не отменил весь заказ, необходимо:

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

Для этого используется метод loyalty/checkout/change (opens new window). Набор передаваемых данных такой же, как и в loyalty/checkout/apply (opens new window), но передавать нужно новый состав корзины с актуальными товарами, ценами и их количеством.

В ответе API-метода будет отображена сумма денег к возврату.

Важно

Важно передавать именно ту цену товара, за которую клиент его покупал. Даже если она отличается от текущей.

# Как обрабатываются товары при изменении

Если в запросе есть товар, который зафиксирован в заказе программы лояльности, то:
- если его кол-во равно, то ничего не меняется;
- если его больше, чем было в программе лояльности, баллы не меняются, но кол-во затраченных баллов на товар будет пересчитано;
- если его меньше, чем было в программе лояльности, часть бонусов будет восстановлена и сумма компенсации увеличена на цену этого товара.
Если в запросе отсутствует товар, который зафиксирован в заказе программы лояльности, то считается, что клиент полностью отказался от этого товара, поэтому будет произведена полная компенсация бонусов и денег по этой позиции.
Если в запросе есть товар, который отсутствует в заказе программы лояльности, то этот товар будет добавлен в общую корзину, но баллы и скидки к нему не будут применены.

# Информация о заказе

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

Для этого используется метод loyalty/checkout/details (opens new window).

← Участие в программе лояльности Товары в программе лояльности →