Расчет корзины, скидок, баллов
IMSHOP Retail Protocol (IRP) является объектом интеллектуальной собственности ООО «АЙ ЭМ СОЛЮШНЗ» (IMSHOP) и защищён как объект авторского права. Свидетельство о депонировании произведения № 023-014461 от 16 января 2023 г. подтверждает исключительные права ООО «АЙ ЭМ СОЛЮШНЗ» на данные технологии.
IMSHOP Retail Protocol создан по заказу ООО «АЙ ЭМ СОЛЮШНЗ». Использование IMSHOP Retail Protocol допустимо только при взаимодействии с ООО "АЙ ЭМ СОЛЮШНЗ" и наличии действующего лицензионного договора. Более подробно можно ознакомиться здесь.
Дополнительные интеграции вводятся в эксплуатацию после завершения основных интеграций:
Для подключения дополнительных интеграций обратитесь к вашему менеджеру в IMSHOP.IO
IMSHOP.IO позволяет при помощи webhook подключить уже существующую на вашей стороне систему пересчета корзины с учетом акций, предложений, бонусных баллов итд.
Пересчет корзины через webhook означает, что для каждого изменения состава корзины IMSHOP.IO будет отправлять данные о заказе в систему клиента и ожидать в ответ данные об итоговой стоимости заказа и примененных маркетинговых акциях.
Формат запроса и примеры
Пример запроса
Описание формата запроса
city
- Стандартизированное название города из системы ФИАСcityKladr
- КЛАДР городаfiasCode
- ФИАС кодdeliveryId
- идентификатор выбранной службы доставки в IMSHOP.IO (null
если доставка еще не выбрана)paymentId
- идентификатор выбранной службы оплаты в IMSHOP.IO (null
если оплата еще не выбрана)deliveryPickupId
- (опционально) выбранный желаемый пункт выдачи / магазин для получения заказаpreferredPickupId
- (опционально) id любимого пункта самовывоза (если есть), выбранный в списке любимых магазинов, например на этапе корзины
Если на корзине используется механика "любимого" магазина/аптеки, идентификатор точки самовывоза будет приходить в этом поле вместо deliveryPickupId
items
- состав корзиныname
- наименованиеid
- идентификатор товара в системе клиента (group_id
)privateId
- идентификатор товарного предложения в системе клиента (offer ID в фиде)configurationId
- идентификатор товарного предложения (offer ID в фиде)price
- цена товара на момент добавления в корзину (если товар - это подарок на выбор, то тут передается0
)quantity
- количествоsubtotal
- итого по позиции (subtotal
=price
*quantity
)appliedDiscounts
- если предыдущий расчет показал наличие маркетинговой акции, или это - подарок на выбор, то передаем идентификатор акции из прошлого ответа от APIdeliveryGroup
- (опционально) выбранная группа доставки товара, при разбиениии корзиныaddons
- (опционально, в разработке) доп. товары, например "Основание для кровати"configurationId
- идентификатор товарного предложения из фида
itemKitId
- string, id товарного набора, передается только если товар был добавлен из товарного набораselected
- boolean, если true, то означает, что товар отмечен галочкой и покупатель берет его. если false, то товар либо недоступен для выбора либо покупатель хочет отложить его
externalUserId
- идентификатор покупателя в системе клиента, если известенpromocode
- промокод, введенный покупателемgiftCards
- подарочные карты, по однойnumber
- номер картыpin
– пин-код карты
earlyAccess
-параметр определяющий что заказ из раннего доступаtrue
installId
- идентификатор установки приложенияgroupId
- если вы разделяете корзину пользователя на несколько отправлений, используйте groupId, чтобы корректно рассчитывать итоговую стоимость каждого отправления с учетом скидок на всю корзину целиком. У исходной корзины и у каждой части корзины приходит одинаковое значение groupIdloyaltyCard
- номер карты лояльности (обычно карта лояльности передаваться не будет, так как она часто уже прикреплена к аккаунту покупателя. используется для анонимных заказов, или если клиент не имеет привязки карт лояльности к профилям пользователей)customSectionValues
- индивидуальные секции в оформлении заказа (к примеру добавить открытку, если пользователь приобретает товар в подарок)
В полях запроса могут быть переданы идентификаторы даты/времени интервала доставки (в разработке)
deliveryDateIntervalId
- (опционально) идентификатор, привязанный к датам, полученный в полеdateIntervals[<index>].id
ендпоинта доставокdeliveryTimeIntervalId
- (опционально) идентификатор, привязанный ко времени, полученный в полеdateIntervals[<index>].timeIntervals[<index>].id
ендпоинта доставок
Маркетинговые акции, активированные в корзине
Ритейлер имеет возможность обновить логику подсчёта полной стоимости и доступных услуг, учитывая добавленные акционные подарки и/или скидки.
Доп. поле promoGroup
передаётся в запрос пересчета корзины. Описание формата приведено в разделе Список "Маркетинговые акции"
Для маркетплейсов.
В полях запроса для каждого товара могут быть переданы идентификаторы магазина/ООО (в разработке).
warehouseId
— (опционально) идентификатор склада/магазина/аутлета/ООО из фида наличия для маркетплейсов
extraServices
- дополнительные услуги, как реализовать *клик
Формат ответа и примеры
Описание формата
Бекенд клиента должен ответить на запрос с application/json
в следующем формате:
totalPrice
- итоговая цена корзины с учетом всех скидок и МА, без учета бонусов (Покупатель сам решает сколько потратить бонусов. Максимальное количество бонусов для списание контроллируется полемbonuses.canSpend
)appliedPromocode
- примененный промокод (null
если промокод не применен, или если введенный промокод невозможно применить)notice
- вне объекта items передается когда нужно вывести общее сообщение на всю корзинуpromocodeStatus -статусы раннего доступа:
success
-Код прикреплёнnotFound
-Неверный кодalreadyRedeemed
-Код уже использованенnotRedeemable
-Условия применения кода не выполнены
discount
- суммарная скидка на заказshowDoNotCallMeCheckbox
- показывать чекбокс Не перезваниватьskipPayment - пропустить этап оплаты при оформлении заказа (опционально)
items
- новый состав корзины (со скидками и подарками)id
- идентификатор товарного предложения в системе клиента (configurationID
)price
- изначальная цена одного товара до скидокdiscount
- примененная скидка на всю позицию (на всё количество)quantity
- количествоsubtotal
- итого (subtotal
= (price
*quantity
) -discount
)gift
- (опционально) количество товаров данной позиции в подарокappliedDiscounts
- (опционально) JSON список идентификаторов примененных акций (например[
"a1123767", "a98723677"]
)bonuses
- (опционально) информация по бонусам для данной позиции:canSpend
- максимальное число баллов для списания на данную позициюwillEarn
- максимальное число баллов для накопления на данную позицию
itemKitId
- string, id товарного набора, передается только если товар был добавлен из товарного набораerror
- (опционально). Текст ошибки, если есть. Если есть хотя бы одна позиция с ошибкой, оформить такой заказ будет невозможно. Ошибка выводится в корзине напротив товара. Пример: "Товар недоступен для заказа"notice
- (опционально). Текст сообщения, выводится в корзине около товара, например, если есть акция 1+1 = 3 на данный товар, чтобы уведомить покупателя.unavailableDeliveryMessage - (опционально,). Текст сообщения о проблеме с доставкой для этого товара, выводится в корзине около товара, например, если для товара недоступен самовывоз, чтобы покупатель понял почему у него он не доступен.
deliveryGroups
- (опционально; значения:default
,express
,large
) группы доступных доставок, массив; значение по умолчанию:["default", "express", "large"]
. Каждому из товаров можно назначить одну или несколько групп. По умолчанию будет принадлежать той группе, которая передана первой в списке. Пользователь сможет перемещать товар между группами, если их передано несколько (например, если доставка у одного из двух товаров недоступна, отказаться от доставки и забрать оба товара самовывозом).canBePurchased
- boolean, флаг, разрешающий покупателю ометить товар галочкой, делает товар доступным для выбора в корзине (опциональный, по умолчанию имеет значение true)selected
- boolean, флаг, задающий состояние галочки у товара, если true, то товар будет отмечен для оформления в заказ, если false, то товар будет отложен и останется в корзине (опциональный, по умолчанию имеет значение true)
Список поддерживаемых групп отправлений и их порядок отображения в корзине настраивается менеджером
addons
- (опционально,) Доп. товары, например "Основание для кровати"configurationId
- ид товарного предложения из фида
warehouseId
- (опционально) идентификатор склада/магазина/аутлета/ООО из фида наличия для маркетплейсовbonuses
- информация по бонусам для данного заказаcanSpend
- можно списать бонусов на весь заказ суммарноwillEarn
- будет накоплено баллов после заказа
deliveryGroupsBonuses
- (опционально) информация по бонусам для разделенной корзины (см. пример)deliveryGroupId
- id группы доставок, представленной сейчас в корзинеcanSpend
- можно списать бонусов для заказов из группы deliveryGroupId
giftCards
- подарочные карты, по однойnumber
- номер картыpin
– пин-код картыsuccess
– возможность привязки карты, booleanstatus
– комментарий (отображение привязки подарочной карты в корзине, либо сообщение с причиной ошибки)
availablePromocodes
– доступные промокодыpromocode
– значение промокода, который добавится в корзину при выборе (до 30 символов, включая пробелы)title
– заголовок / название акции (до 20 символов, включая пробелы); напр. "Скидка 15%", "Доставка бесплатно"description
– краткое описание / призыв к действию / срок действия в свободном формате (до 35 символов, включая пробелы); напр. "На заказ от 8000р", "Только сегодня!", "Доступно до 31 декабря"availableUntil
– крайний срок возможности активации промокода; поле опционально (timestamp, отображается вместоdescription
)longDescription
– подробное описание (до 100 символов, включая пробелы); текст доступен по нажатию на информер рядом с заголовком (поле опционально; при отсутствии значения, информер не отображается)backgroundImage
– фоновая картинка на промокодеappliedImage
– картинка, которая будет отображена после применения промокодаapplyImageAnimation
– тип анимации на применение промокода. Поддерживаются два формата: stamp и fade. По умолчанию fadebackgroundColor
– цвет заливкиtextAppearance
– стиль отображения текста. Поддерживаются два формата: light и dark. По умолчанию dark
Подробнее в разделе #karusel-promokodov
Пользователь может выбрать один из перечисленных промокодов. Одновременный выбор в рамках одного заказа недоступен. Если вас интересует такой сценарий - обсудите возможность его реализации с продакт-менеджером IMSHOP.IO
extraServices
- дополнительные услуги, как реализовать *кликeula
– (опционально) договоры/пользовательские соглашения, которые должен принять пользователь для оформления заказа
Маркетинговые акции
Пользователь имеет возможность получить подарки, дополнительную скидку, или другую выгоду при оформлении заказа.
Формат ответа при пересчете корзины
Описание формата приведено в разделе Список "Маркетинговые акции"
Синхронизация корзины с сайтом и наоборот
Добавляется в запрос и в ответ расчета корзины:
lastSyncDate
- (опционально) это timestamp, время последней синхронизации (в миллисекундах) корзины
Это поле отправляется в запросе только тогда, когда пользователь авторизован. Если приходит 0 (ноль) в запросе, то это означает что пользователь ничего не добавлял в корзину пока был неавторизован.
При реализации этой фичи мы ожидаем что вы:
Добавите новое поле к примеру тоже lastSyncDate в базу данных с корзинами пользователей и изначальное значение этого поля для всех текущих и будущих корзин должно быть 0.
При любом изменении корзины пользователя в базе данных, должны будете обновить поле lastSyncDate на текущий timestamp (время в миллисекундах).
Добавите это поле в ответ, которое будет передавать его.
При запросе от нас вы должны будете сравнивать две даты, которая пришла в запросе и которая хранится у вас в базе данных, в случае если дата в запросе свежее, то необходимо заменить весь состав корзины в вашей базе данных из нашего запроса и обновить поле lastSyncDate на то которое пришло из нашего запроса, а если же дата из вашей базы данных окажется свежее, то вы должны будете отправить то состояние корзины которое в вашей базе данных и отправить тот lastSyncDate которое у вас. Если же даты равные, то все отлично и запрос можно обработать как обычно. Если мы отправили 0 и у вас 0, то вам необходимо провести слияние (merge) нашего и вашего состава корзины и обновить поле lastSyncDate на текущий timestamp (время в миллисекундах).
Если в запросе нет поля lastSyncDate значит юзер не залогинен в приложении и его корзину синхронизировать не надо.
Карусель промокодов(В разработке)
Пример формата передачи прокодов в корзине:
Описание формата изображений:
Рекомендуемый размер изображений 1150x450
backgroundImage и appliedImage должны быть одинаковыми размерами.
Если вы используете тип промокодов со штампиками, то рекомедуется использовать анимацию stamp
Last updated