2 этап. Изменения интеграции заказов с процессингом лояльности

С сентября 2024 года мы меняем схему интеграции заказов с процессингом лояльности.

Как было раньше:

Для того, чтобы передать успешно совершенный заказ, необходимо было сделать два последовательных вызова: начало создания заказа (begin) в момент старта проведения заказа и коммит создания заказа (commit) в момент успешного проведения заказа. Если проведение заказа по каким-то причинам прерывалось - нужно было вызвать откат заказа (rollback).

При вызове begin mindbox блокировал баллы, промокоды и применение скидки для клиента, чтобы их нельзя было использовать в параллельном заказе. С вызовом commit заблокированные баллы списывались, применялись окончательно промокоды и скидки, начислялись баллы за заказ. Кроме того, после вызова commit срабатывали сценарии на событие, связанное с заказом, так как заказ внутри mindbox считался успешно совершенным только в этот момент.

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

Как будет со 2 сентября:

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

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

Если по каким-либо причинам проведение заказа будет невозможно, то mindbox будет ожидать явной передачи статуса заказа Отменен через шаг обновить статус позиций заказа.
После успешной оплаты проведенного заказа mindbox будет ожидать явной передачи статуса заказа Оплачен через шаг обновить статус позиций заказа.

Что нужно сделать для перехода на новую интеграцию:

1.

Вместо операции begin вызываем операцию createOrder с шагом создать или обновить заказ.

Контракт этого шага отличается от begin двумя пунктами:

• Из тела операции исключается поле order/transaction/id/externalid
• URL запроса дополняется параметром: &transactionId={Ключ идемпотентности (Guid)}. Подробнее про ключ идемпотентности.

https://api.mindbox.ru/v3/operations/{sync/async}?endpointId={Идентификатор точки интеграции}&operation={Системное имя операции}&transactionId={Ключ идемпотентности (Guid)}

{
"order": {
    "totalPrice": "<Итоговая сумма, полученная от клиента. Должна учитывать возвраты и отмены. Используется для подсчета среднего чека.>",
    "email": "<Email>",
    "mobilePhone": "<Номер мобильного телефона без форматирования>",
    "ids": {
           "externalId": "<Идентификатор заказа из внешней системы>"
    }
    ...
}

2.

Убираем вызов rollback

3.

Добавляем статусы Оплачен и Отменен.

4.

Добавляем вызов с шагом обновить статус позиций заказа со статусом Отменен при отмене заказа и со статусом Оплачен при успешном оформлении и оплате заказа.

{
  "order": {
    "ids": {
      "externalId": "<Идентификатор заказа из внешней системы>"
    }
  },
  "orderLinesStatus": "<Новый статус для всех линий заказа>",
  "executionDateTimeUtc": "<Дата и время выполнения (можно использовать для выполнения запроса задним числом)>"
}

Для чего это нужно:

• Практически у всех клиентов из-за сложной логики интеграции остаются незакрытые транзакции (неподтвержденные чеки). По таким чекам не уходит никакая коммуникация и зависают баллы.
• В некоторых ситуациях теряются новые данные по заказу, передаваемые в mindbox, а так же вся коммуникация по ним. При наличии постоянного большого числа синхронных и асинхронных вызовов (бегин-роллбэк/коммит-бегин) такие вызовы накладываются друг на друга и в итоге в незавершенную транзакцию не могут записаться новые данные по заказу.
• Сама логика транзакций приводит к дублям заказов и испорченной статистике. Каждый ретрай создания заказа требует нового transactionID, что воспринимается mindbox. как новый заказ, если нет никаких идентификаторов заказа. Дубли учитываются в отчете по выручке и программе лояльности как отмененные заказы.
• Разработка модуля лояльности mindbox не может быстро тестировать продуктовые гипотезы и дорабатывать продукт, так как поддержка текущей логики интеграции в разы увеличивает срок разработки.

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