Предварительная оценка заказа

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

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

Пайплайн расчета заказа следующий:

Подбор акций, подходящих клиенту и текущей корзине.
Расчет лимитов скидок для каждого товара.
Применение скидочных акций.
Расчет вознаграждения покупателя по реферальной программе, если тип вознаграждения "скидка". Работает, в том числе для покупателей, не являющихся участниками ПЛ. Но не работает для анонимных заказов.
Применение скидок по скидочной программе лояльности с учетом уровня клиента.
Применение бонусов.
Применение сертификатов и депозитов.
Расчет вознаграждения по бонусной программе лояльности.
Расчет вознаграждения покупателя бонусами по реферальной программе, если тип вознаграждения "бонусы".
Расчет бонусного вознаграждения реферера (партнера).

POST https://api.rees46.ru/loyalty/checkout/estimate

Параметры

Параметр	Обязателен?	Описание
shop_id	Да	API-ключ
shop_secret	Да	Секретный ключ API
identifier	Нет	Номер телефона клиента, идентификатор участника ПЛ. Обязательно для списания бонусов, реферальной программы и некоторых акций, иначе можно не указывать
order_id	Нет	Номер заказа. Обычно на данном этапе равен `null` и является обязательным только в `checkout/apply`
cart_items[]	Да	Массив товаров или услуг в корзине покупателя. Не может быть пустым
cart_items[].product_id	Да	Артикул товара или услуги
cart_items[].price	Да	Исходная цена товара до применения скидок и акций
cart_items[].quantity	Да	Количество единиц данного товара в корзине
cart_items[].discountable	Нет	Можно указать `false`, если требуется принудительно запретить скидки и скидочные акции
cart_items[].bonusable	Нет	Можно указать `false`, если требуется принудительно запретить списание бонусов
cart_items[].rewardable	Нет	Можно указать `false`, если требуется принудительно запретить вознаграждение бонусами
payment_type	Нет	Способ оплаты. Может влиять на применяемые инструменты. Например, акция работает только при оплате наличными. Значением может быть любая строка. Например: `cash`, `card`, `sbp`
promo_codes	Нет	Список промокодов (массив строк)
certificates	Нет	Список кодов предоплаченных сертификатов (массив строк)
charge_bonuses	Нет	Булевый флаг, списывать бонусы или нет. По-умолчанию `false`. Если указан в `true`, то в поле `identifier` обязательно должен быть идентификатор участника ПЛ. Если `identifier` отсутствует или участника ПЛ с таким идентификатором нет, метод вернет ошибку с кодом `400`
bonuses_amount	Нет	Лимит списания бонусами, если покупатель по какой-то причине хочет списать меньше бонусов, чем возможно. В большинстве случаев не требуется, т.к. алгоритм считает максимальную скидку из всех возможных инструментов и покупателю не нужно думать, сколько бонусов стоит списать для получения максимальной скидки
use_personal_certificates	Нет	Булевый флаг, использовать ли именные сертификаты без их передачи в запросе. Если `true`, то процессинг найдет все активные именные сертификаты клиента и попытается применить их автоматически
stream	Нет	Идентификатор стрима, позволяющий отделять заказы из розницы, сайта и мобильных приложений, если у вас есть акции, которые могут работать только в одном канале
current_time	Нет	Локальное время в точке продаж в формате `HH:MM`, если есть акции, которые работают в определенное время (например, "счастливые часы"). Если время не указано, берется текущее время на сервере в таймзоне магазина
subscription	Нет	Код подписки клиента, если есть

Важно про cart_items

Массив не может быть пустым.
В корзине не может быть двух строк с одинаковым артикулом.
Поле price не может отсутствовать или быть ≤ 0.
Поле quantity не может отсутствовать или быть ≤ 0.
Поле product_id не может отсутствовать.
Если в поле product_id содержится артикул, которого нет в товарной базе, товар не будет участвовать в скидках и вознаграждениях.

Запрос

Пример запроса:

shell

curl --header "Content-Type: application/json" \
  --request POST \
  --data-binary "@payload.json" \
  https://api.rees46.ru/loyalty/checkout/estimate

Пример JSON-тела:

json

{
  "shop_id":        "...",
  "shop_secret":    "...",
  "identifier":     "...",
  "payment_type":   "...",
  "promo_codes":    ["...", "..."],
  "certificates":   ["...", "..."],
  "charge_bonuses": true,
  "bonuses_amount": 500, 
  "stream":         "pos",
  "current_time":   "17:31",
  "cart_items": [
    {"product_id": "...", "price": 1000, "quantity": 4},
    {"product_id": "...", "price": 2000, "quantity": 1, "discountable": false, "bonusable": false, "rewardable": false }
  ]
}

Ответ

Пример ответа сервера:

json

{
  "status": "success",
  "payload": {
    "order_id": null,
    "identifier": "...",
    "payment_type": "...",
    "products_total": 5,
    "order_total": 6000,
    "saved_total": 1100,
    "saved_by_discounts": 400,
    "saved_by_bonuses": 600,
    "saved_by_offers": 0,
    "saved_by_certificates": 100,
    "order_to_pay": 4900,
    "order_bonuses_to_charge": 500,
    "bonuses_balance": 1000,
    "bonuses_reward": 500,
    "bonuses_referrer_reward": 0,
    "referrer_identifier": "...",
    "referral_program": 21,
    "applied_promotions": [],
    "rewarded_stickers": {},
    "used_stickers": {},
    "stickers_balance": {},
    "promo_codes": [],
    "promo_codes_failed": [],
    "certificates": [],
    "certificates_failed": [],
    "items": [
      {
        "uniqid": "...",
        "quantity": 4,
        "price": 1000,
        "total": 4000,
        "discountable": true,
        "bonusable": true,
        "rewardable": true,
        "paid_with_offers": 0,
        "paid_with_offers_per_product": 0,
        "paid_with_referral_discounts": 0,
        "paid_with_referral_discounts_per_product": 0,
        "paid_with_discounts": 500,
        "paid_with_discounts_per_product": 100,
        "paid_with_bonuses": 500,
        "paid_with_bonuses_per_product": 100,
        "paid_with_certificates": 100,
        "paid_with_certificates_per_product": 25,
        "bonuses_reward": 400,
        "bonuses_reward_per_product": 100,
        "bonuses_reward_loyalty_program": {
          "total": 40,
          "per_product": 10
        },
        "bonuses_reward_referral_program": {
          "total": 80,
          "per_product": 20
        },
        "bonuses_reward_promotions": {
          "33": { "total": 100, "per_product": 25 },
          "17": { "total": 180, "per_product": 45 }
        },
        "certificates": {
          "14": { "id": 14, "code": "...", "pool_id": 11, "amount": 100, "amount_per_product": 25 },
          "32": { "id": 31, "code": "...", "pool_id": 19, "amount": 160, "amount_per_product": 40 }
        },
        "bonuses_used": 500,
        "bonuses_used_per_product": 125,
        "total_after_discounts": 3500,
        "total_after_discounts_per_product": 875
      }
    ]
  }
}

Расшифровка ответа:

Параметр	Описание
success	Запрос выполнен успешно или нет
payload.message	Сообщение с результатом обработки запроса
payload.order_id	Идентификатор заказа, в `estimate` равен `null`, если явно не передан в запросе
payload.identifier	Идентификатор участника программы лояльности в формате `7XXXXXXXXXX`
payload.payment_type	Способ оплаты, переданный в запросе
payload.products_total	Количество штук товаров в корзине (сумма `quantity` всех SKU)
payload.order_total	Полная стоимость заказа (сумма `price * quantity` всех SKU)
payload.saved_total	Суммарная скидка текущей корзины по всем инструментам
payload.saved_by_discounts	Суммарная скидка заказа по скидочной программе лояльности
payload.saved_by_bonuses	Суммарная скидка заказа по бонусной программе лояльности
payload.saved_by_offers	Суммарная скидка заказа по акциям
payload.saved_by_certificates	Сколько будет сэкономлено при оплате сертификатами
payload.order_to_pay	Конечная сумма денег к оплате заказа
payload.order_bonuses_to_charge	Максимально доступная сумма оплаты бонусами по заказу
payload.bonuses_balance	Текущий бонусный баланс покупателя до списания бонусов
payload.bonuses_reward	Расчетное вознаграждение покупателя бонусами
payload.bonuses_referrer_reward	Расчетное вознаграждение реферера (партнера) бонусами
payload.referrer_identifier	Идентификатор реферера (партнера)
payload.referral_program	Идентификатор реферальной программы, если передан реферальный промокод
payload.applied_promotions	Массив идентификаторов примененных акций
payload.rewarded_stickers	Объект со служебной информацией о вознаграждении стикерами
payload.used_stickers	Объект со служебной информацией по списанным стикерам
payload.stickers_balance	Объект со служебной информацией по текущему балансу стикеров
payload.promo_codes[]	Список примененных промокодов (массив строк)
payload.promo_codes_failed[]	Список не примененных промокодов (массив объектов)
payload.promo_codes_failed[].code	Промокод
payload.promo_codes_failed[].message	Причина, почему промокод не применен
payload.certificates[]	Список примененных сертификатов (массив строк)
payload.certificates_failed[]	Список не примененных сертификатов (массив объектов)
payload.certificates_failed[].code	Код сертификата
payload.certificates_failed[].message	Причина, почему сертификат не применен
payload.items[]	Список товаров в корзине

Свойства каждого элемента в payload.items[]:

Параметр	Описание
product_id	Идентификатор (артикул) товара
quantity	Количество единиц конкретного товара в корзине
price	Исходная цена товара из запроса
total	Общая стоимость артикула в корзине (`price * quantity`) до применения скидок
discountable	Можно ли применять скидки к данному товару
discountable_reason	Причина, по которой нельзя применить скидку к данному товару
bonusable	Можно ли списать бонусы за данный товар
bonusable_reason	Причина, по которой нельзя списать бонусы за данный товар
rewardable	Будет ли вознаграждение бонусами за данный товар
rewardable_reason	Причина, по которой не будет вознаграждение бонусами за данный товар
paid_with_offers	Сколько сэкономлено на акциях за этот товар
paid_with_offers_per_product	Сколько сэкономлено на акциях за одну единицу этого товара
paid_with_referral_discounts	Сколько сэкономлено по реферальной программе за этот товар
paid_with_referral_discounts_per_product	Сколько сэкономлено по реферальной программе за одну единицу этого товара
paid_with_discounts	Сколько сэкономлено по скидочной программе лояльности за этот товар
paid_with_discounts_per_product	Сколько сэкономлено по скидочной программе лояльности за одну единицу этого товара
paid_with_bonuses	Сколько сэкономлено бонусами за этот товар
paid_with_bonuses_per_product	Сколько сэкономлено бонусами за одну единицу этого товара
paid_with_certificates	Сколько оплачено сертификатами за этот товар
paid_with_certificates_per_product	Сколько оплачено сертификатами за одну единицу этого товара
bonuses_used	Сколько будет списано бонусов за данную позицию
bonuses_used_per_product	Сколько будет списано бонусов за данную позицию на одну единицу товара
bonuses_reward	Какое будет вознаграждение бонусами за данных позицию
bonuses_reward_per_product	Какое будет вознаграждение бонусами за данных позицию за одну единицу товара
bonuses_reward_loyalty_program	Объект с информацией о бонусном вознаграждении
bonuses_reward_loyalty_program.total	То же самое, что и `payload.items[].bonuses_reward`
bonuses_reward_loyalty_program.per_product	То же самое, что и `payload.items[].bonuses_reward_per_product`
bonuses_reward_referral_program	Объект с информацией о вознаграждении реферера бонусами
bonuses_reward_referral_program.referral_program_id	Идентификатор реферальной программы
bonuses_reward_referral_program.total	Сумма вознаграждения реферера за данный товар
bonuses_reward_referral_program.per_product	Сумма вознаграждения реферера за одну единицу данного товара
bonuses_reward_promotions	Служебный объект с информацией о бонусном вознаграждении акциями, где ключом является идентификатор акции
bonuses_reward_promotions[].total	Сумма вознаграждения по акции за данный товар
bonuses_reward_promotions[].per_product	Сумма вознаграждения по акции за одну единицу товара
certificates	Объект с распределением использованных сертификатов, где ключ объекта – идентификатор сертификата
certificates[].id	Идентификатор сертификата
certificates[].code	Код сертификата
certificates[].pool_id	Идентификатор пула сертификатов, которому принадлежит сертификат
certificates[].amount	Сколько было оплачено сертификатом за данный товар
certificates[].amount_per_product	Сколько было оплачено сертификатом за одну единицу товар
max_discountable_amount	Служебное свойство: максимально допустимая скидка по товару с учетом ограничений ПЛ, акций и пр
max_discountable_amount_left	Служебное свойство: остаток от `max_discountable_amount` после применения скидок, бонусов и пр
max_payable_by_bonuses	Служебное свойство: максимальная сумма, которую можно списать бонусами
total_after_discounts	Финальная стоимость к оплате за данный товар
total_after_discounts_per_product	Финальная стоимость к оплате за одну единицу товара

Несмотря на сложную структуру, для кассира или клиента полезной будет только следующая информация:

payload.order_total
payload.saved_total
payload.order_to_pay
payload.bonuses_reward
payload.items[].product_id
payload.items[].total
payload.items[].total_after_discounts

В случае ошибки данных вернет подобную структуру:

json

{
  "status": "error",
  "payload": {
    "message": "Cart contains line items with the same product ID",
    "identifier": "..."
  }
}

Предварительная оценка заказа ​

Параметры ​

Запрос ​

Ответ ​

Предварительная оценка заказа

Параметры

Запрос

Ответ