Топ-100

Внешние скидки

Доступность функционала зависит от тарифа. Подробнее о тарифах

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

Внешняя скидка позволяет рассчитывать скидку на сервере вашего приложения. inSales отправляет POST-запрос с JSON заказа на указанный URL, а обработчик возвращает сумму и название скидки либо список ошибок.

Запрос выполняется при открытии корзины или изменении данных, от которых зависит скидка. Повторные запросы зависят от настроек скидки и версии оформления заказа.

Как перейти к настройкам внешних скидок

Чтобы перейти в раздел, нажмите Клиенты → Скидки → Внешние скидки:

Общий вид раздела настроек

1. Кнопка "+" — кнопка создания новой скидки.

2. Описание — название скидки.

3. URL — адрес, на который идет запрос в формате JSON.

4. Крестик — удаляет скидку. После удаления ее восстановить нельзя, придется создавать заново.

Создание внешней скидки

Если нажать кнопку "+", появляется следующее окно:

1. URL — обязательное поле, в нем указывается адрес скрипта (http или https), на который идет запрос в формате JSON. По этому URL должен располагаться файл, который сможет обработать полученные данные и вернуть ответ.

Адрес из частной сети сохранить нельзя: и панель администратора, и POST /admin/external_discounts.json отвечают 422 с {"url":["Недопустимый URL"]}. Повтор того же URL даёт 422 и {"url":["уже существует"]}.

2. Описание (description) — название скидки панели администратора. Оно также используется на витрине, если обработчик не вернул название скидки. Максимальная длина — 200 символов. При превышении API возвращает 422, {"description":["Описание слишком большой длины (не может быть больше, чем 200 символов)"]}.

3. Зависит от дополнительных полей (order_lines_depend) — если в разделе "Настройки → Оформление заказа" были добавлены поля для заказа, от которых зависит скидка, то настройка заставляет систему делать новый запрос при изменении значения поля.

Если вы создали поле для ввода номера скидочной карты и отметили данную галочку, то в случае изменения значения поля получение скидки произведется повторно.

observed_fields — id дополнительных полей заказа. Пока выбранное поле пустое, магазин не отправляет запрос. После заполнения значение передаётся в fields_values. При изменении значения магазин отправляет новый запрос.

4. Зависит от состава корзины (order_lines_depend) — галочка указывает, нужно ли отсылать повторный запрос на получение скидки, если содержимое корзины изменилось. 

5. Включено (active) — активирует скидку. Выключенная запись запрос не отправляет.

Если зависимость от состава корзины выключена и ни одно выбранное дополнительное поле не заполнено, магазин не запрашивает расчёт скидки. Сумма корзины не меняется.

Обработка запроса

1. В запросе  GET /admin/orders/:order_id.json передается вся информация о заказе.

2. В ответ на запрос нужно вернуть один из следующих объектов:

1) Если скидку можно применить:

{
"discount": 10, // Величина скидки, если discount_type == PERCENT, то это 10% иначе 10 рублей
"discount_type": "PERCENT", // Может быть MONEY
"title": "Вам скидка по карте XXXXX", //Текстовое описание скидки, которое сохранится в заказе и будет выведено пользователю
}

2) Если скидку по какой-то причине нельзя применить:

{
"errors": ["Карта не найдена"] // Массив ошибок
}

3. Далее нужно модифицировать страницу корзины для работы с внешними скидками.

Нужно добавить форму, отсылающую данные на URL /cart_items методом PUT.

В форму необходимо добавить input, в который пользователь будет вводить номер карты. К примеру:

<form action="/cart_items" method="PUT">
<input name="order[fields_values_attributes][XXXX][field_id]" value="XXXX" type="hidden">
<input name="order[fields_values_attributes][XXXX][value]" type="text">
.....
</form>

, где XXXX — это ID дополнительного поля заказа.

ID дополнительного поля указан в адресной строке браузера при редактировании дополнительного поля: 

4. Далее нужно добавить на страницу корзины вывод ошибок.

Ошибки доступны в Liquid-шаблоне через метод discount_errors у переменной cart. Пример:

{% for error in cart.discount_errors %}
<p class="error">{{error}}</p> 
{% endfor %}

API

Авторизация та же, что у остального Admin API: HTTP Basic, логин — идентификатор приложения, пароль — пароль приложения в этом магазине.

GET    /admin/external_discounts.json
GET    /admin/external_discounts/:id.json
POST   /admin/external_discounts.json
PUT    /admin/external_discounts/:id.json
DELETE /admin/external_discounts/:id.json

Создание:

{
  "external_discount": {
    "url": "https://discount.example/calculate",
    "description": "Скидка по карте",
    "order_lines_depend": true,
    "observed_fields": [185],
    "active": true
  }
}

Ответ 201 возвращает запись с id. Обновление отвечает 200 и той же записью. Удаление отвечает 200 и {"status":"ok"}, следующий GET этой записи — 404.

Запрос

inSales отправляет на url POST-запрос с заголовком Content-Type: application/json, без отдельной авторизации. Тело содержит данные заказа, даже если покупатель ещё работает с корзиной и заказ не создан.

До создания заказа поля id, number и key пустые. Товары передаются в массиве order_lines. Для расчёта суммы товаров умножьте sale_price на quantity в каждой строке и сложите результаты. В повторном запросе items_price, total_price заказа и массив discounts уже могут содержать ранее применённую внешнюю скидку, а sale_price строки остаётся ценой до неё.

Ниже приведены поля запроса, относящиеся к расчёту скидки для корзины из двух позиций.

{
  "id": null,
  "number": null,
  "key": null,
  "currency_code": "RUR",
  "locale": "ru",
  "items_price": 266.0,
  "total_price": 266.0,
  "discount": null,
  "discounts": [],
  "fields_values": [],
  "client": {
    "id": null,
    "email": null,
    "phone": null,
    "registered": false
  },
  "order_lines": [
    {
      "title": "товар 2",
      "product_id": 569,
      "variant_id": 2176487162,
      "sku": null,
      "quantity": 1,
      "sale_price": 200.0,
      "full_sale_price": 200.0,
      "total_price": 200.0,
      "full_total_price": 200.0,
      "discounts_amount": 0.0,
      "vat": -1,
      "weight": null,
      "barcode": null,
      "unit": "pce"
    },
    {
      "title": "товар 6",
      "product_id": 601,
      "variant_id": 2176487170,
      "sku": null,
      "quantity": 1,
      "sale_price": 66.0,
      "full_sale_price": 66.0,
      "total_price": 66.0,
      "full_total_price": 66.0,
      "discounts_amount": 0.0,
      "vat": -1,
      "weight": null,
      "barcode": null,
      "unit": "pce"
    }
  ]
}

Полное тело запроса также содержит сведения о доставке, оплате, адресе, shipping_address, источнике визита и cookies. В приведённом расчёте скидки эти данные не используются. cookies в расчёт не берите и у себя не сохраняйте.

Если покупатель заполнил дополнительное поле заказа, массив fields_values содержит его значение:

"fields_values": [
  {
    "field_id": 185,
    "name": "Номер карты",
    "type": "Текст",
    "value": "CARD-77",
    "handle": null
  }
]

При оформлении заказа объект client содержит имя, почту и телефон, которые ввёл покупатель. У корзины до создания заказа client.id может быть пустым.

Ответ

Обработчик должен вернуть HTTP-статус 200 и JSON-объект со скидкой или ошибками.

Сумма в валюте магазина:

{
  "discount": 100,
  "discount_type": "MONEY",
  "title": "Скидка по карте"
}

На корзине из товаров на 200 ₽ и 66 ₽ эта скидка даёт строку «Скидка по карте» на 100 ₽ и итог 166 ₽.

Процент считается от суммы товаров и показывается в рублях, без копеек. Десять процентов на корзине 200 ₽ и две штуки по 66 ₽ (332 ₽) дают 33 ₽, итог 299 ₽:

{
  "discount": 10,
  "discount_type": "PERCENT",
  "title": "Десять процентов"
}

Если title не передать, на витрине показывается description из настройки скидки. Ответ {"discount": 20, "discount_type": "MONEY"} при описании «Самый дешёвый товар» даёт строку с этим названием и суммой 20 ₽.

Если сумма скидки превышает стоимость товаров, inSales ограничивает её стоимостью товаров. Денежная скидка 10000 ₽ на корзину 332 ₽ оставляет итог 0 ₽.

Если вернуть нулевую скидку с названием, inSales покажет строку скидки, но не изменит итоговую сумму. Покупатель видит «Название» и «0 ₽», сумма товаров не меняется:

{
  "discount": 0,
  "discount_type": "MONEY",
  "title": "Карта принята"
}

Если вернуть нулевую скидку с пустым title, строка скидки не отображается.

Если скидку нельзя применить, верните массив строк errors. inSales не применит скидку и покажет сообщения рядом с полем промокода:

{
  "errors": ["Карта не найдена"]
}

В стандартной корзине тот же текст доступен как cart.discount_errors:

{% for error in cart.discount_errors %}
  <div class="discount-error">{{ error }}</div>
{% endfor %}

Пример: самый дешёвый товар

При двух и более позициях скидка равна стоимости самой дешёвой строки, sale_price * quantity. На одной позиции скидки нет.

import json


def discount_for(order):
    lines = order.get("order_lines") or []
    if len(lines) < 2:
        return {"discount": 0, "discount_type": "MONEY", "title": ""}
    cheapest = min(
        float(line["sale_price"]) * float(line["quantity"])
        for line in lines
    )
    return {
        "discount": cheapest,
        "discount_type": "MONEY",
        "title": "Самый дешёвый товар",
    }

Для корзины из товаров 200 ₽ и 66 ₽ ответ такой:

{
  "discount": 66.0,
  "discount_type": "MONEY",
  "title": "Самый дешёвый товар"
}

В корзине строка «Самый дешёвый товар» на 66 ₽, итог 200 ₽.

Когда уходит новый запрос

inSales сохраняет результат расчёта. При повторном открытии той же корзины магазин использует сохранённый ответ и не отправляет новый POST-запрос.

Если включена настройка «Зависит от состава корзины», магазин запрашивает расчёт при изменении количества, варианта или набора товаров. Если настройка выключена, изменение количества не вызывает пересчёт: применяется сумма из предыдущего ответа.

Настройка «Зависит от дополнительных полей заказа» вызывает новый запрос при изменении значения выбранного поля. Пустое поле не вызывает запрос.

Для выключенной скидки (active: false) магазин не отправляет запросы, даже если состав корзины изменился.

При оформлении заказа момент запроса зависит от версии чекаута.

Пока обработчик не ответил, корзина не открывается. Если он возвращает статус, отличный от 200, магазин открывает страницу без этой скидки. При пустом теле или невалидном JSON вместо корзины отображается ошибка разбора JSON. Возвращайте описанный выше JSON-объект со статусом 200.

Дополнительное поле

Поле заказа создаётся в бэк-офисе и отмечается в «Зависит от дополнительных полей заказа». На витрине его значение уходит вместе с корзиной. Для сохранения значения отправьте POST на /cart_items с параметром _method=put: HTML-форма с method="put" не отправляет PUT-запрос. У поля «Номер карты» с id 185 тело такое:

_method=put
order[fields_values_attributes][185][field_id]=185
order[fields_values_attributes][185][value]=CARD-42

Нужен и CSRF-токен страницы. После сохранения уходит новый POST на URL скидки, и в fields_values приходит введённое значение. Новое значение того же поля вызывает ещё один запрос и новую сумму.

На оформлении то же поле показывается покупателю. Смена значения и сохранение контактов снова вызывают скрипт. В созданном заказе значение поля остаётся. Его видно в бэк-офисе и в GET /admin/orders/:id.json, в fields_values.

Версия чекаута

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

Третья версия — /gocheckout. Открытие и повторная загрузка этой страницы новый POST не отправляют, пока не изменились состав корзины и наблюдаемые поля. На странице остаётся скидка, уже посчитанная в корзине. Новый запрос уходит при смене состава корзины или значения наблюдаемого поля, в том числе при сохранении контактов.

Вторая версия — /new_order. Каждый заход на страницу отправляет POST заново, даже если корзина не менялась. В сводке видна скидка из этого запроса. Смена способа доставки на этой странице новый запрос не вызывает. Кнопка «Подтвердить заказ» отправляет POST ещё раз, уже с контактами и выбранной доставкой.

Заказ хранит скидку одинаково на обеих версиях. Доставка в скидку не входит: товар 200 ₽ со скидкой 40 ₽ и доставкой 300 ₽ даёт товар 160 ₽, доставку 300 ₽ и сумму заказа 460 ₽. В GET /admin/orders/:id.json в discounts лежат description, amount и type_id 2. items_price и total_price уже с учётом скидки.

Корзина, оформление и заказ

Денежная скидка 100 ₽ на товарах 200 ₽ и 66 ₽ даёт название и итог 166 ₽. Десять процентов на товарах 332 ₽ дают строку 33 ₽ и итог 299 ₽. Текст из errors показывается под полем промокода. Нулевая скидка с названием остаётся строкой «0 ₽».

На оформлении видны та же строка и дополнительное поле. В заказе сохраняются название из title и итог с учётом скидки. Для товаров на 398 ₽ и ответа discount: 25, discount_type: "MONEY" итог заказа — 373 ₽. В личном кабинете у заказа есть строка скидки и значение дополнительного поля.

GET /admin/orders/:id.json возвращает скидку в discounts: description — название из title, discount и amount — сумма, type_id 2 — денежная скидка. type_id 1 — процент.

Несколько скидок

Если доступны несколько внешних скидок или внешняя скидка и купон, inSales применяет одну скидку с наибольшей суммой. Скидки не складываются.

Если включены две внешние скидки, запрос уходит на оба URL. В корзине остаётся одна, с большей суммой.

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

Если одна скидка возвращает errors, а другая — сумму, применяется сумма. Текст ошибки при этом виден у промокода.

Оставить оценку

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

Количество отзывов: 0

Недавно просмотренные статьи
Остались вопросы?
Отправьте обращение в техподдержку!
Для улучшения работы сайта, ООО «Инсейлс Рус» обрабатывает файлы Cookie, а также использует сервисы веб-аналитики. Для получения дополнительной информации, пожалуйста, ознакомьтесь с Политикой использования Cookie-файлов.