Использование API для интеграции с Программой лояльности

Скопировать ссылку на статью

Скопировано

Участие в Программе лояльности

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

Используем фильтр по списку участий, чтобы понять, есть ли у клиента Участие в Программе лояльности или его нужно создать. Для этого необходимо передать в параметрах поиска код магазина и идентификатор клиента. Поиск подходящей Программы лояльности происходит по магазину, который указан в настройках.

Активация Участия в Программе лояльности

В зависимости от настроек Программы лояльности - Участие может потребовать дополнительных действий по активации. Активация происходит автоматически при создании Участия и при редактировании клиента/участия, если данных становится достаточно согласно настройкам. Если включена настройка «Подтверждение регистрации по SMS», то необходимо с помощью метода Активация Участия в ПЛ отправить клиенту код подтверждения по SMS на номер телефона, указанный в Участии, и получить информацию об SMS object (SmsVerification).

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

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

Также возможно проверить статус SMS подтверждения в методе Проверка статуса верификации.

Не активированное участие может только накапливать бонусы.

Предварительный расчет заказа с Программой лояльности

Для предварительного расчета заказа, чтобы показать клиенту актуальные цены, скидки и информацию о бонусах, необходимо использовать метод Расчёт максимальной скидки. Метод позволяет определить максимально выгодную привилегию. Сценарий работы можно представить так:

• Вызвать метод Расчет максимальной скидки, получить максимально возможное количество бонусов для списания в этом заказе, информацию по скидкам и бонусам, которые будут начислены. Если не передать значение bonuses, то по умолчанию рассчитывается вариант без списания бонусов в заказе.
• Если необходим расчет с учетом списания бонусов, то вызвать метод с параметром bonuses для перерасчета данных еще раз.

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

bonuses=150&order={ 
  "discountManualAmount": 0,
  "discountManualPercent": 5,
  "customer": {
    "id": 309
  },
  "items": [
    {
      "initialPrice": 10000,
      "quantity": 2,
      "discountManualAmount": 100,
      "offer": {
        "id": 26
      }
    },
    {
      "initialPrice": 20000,
      "quantity": 1,
      "offer": {
        "id": 22
      }-
    }
  ],
  "delivery": {
    "cost": 100
  }
}

...
"calculations": [
    {
        "privilegeType": "loyalty_event",
        "discount": 2340,
        "creditBonuses": 0,
        "loyaltyEventDiscount": {
            "id": 7
        },
        "maxChargeBonuses": 150,
        "maximum": false
    },
    {
        "privilegeType": "loyalty_level",
        "discount": 2340,
        "creditBonuses": 4521,
        "maxChargeBonuses": 150,
        "maximum": true
    },
    {
        "privilegeType": "personal_discount",
        "discount": 6121,
        "creditBonuses": 0,
        "maxChargeBonuses": 150,
        "maximum": false
    },
    {
        "privilegeType": "none",
        "discount": 2340,
        "creditBonuses": 0,
        "maxChargeBonuses": 150,
        "maximum": false
    }
]
...

Создание заказа

При создании заказа с использованием Программы лояльности необходимо в данные запроса добавить следующие поля:

• privilegeType — это значение привилегии из шага с предварительным расчетом заказа;
• customer — у клиента заказа должно быть создано участие в Программе лояльности;
• site — магазин заказа должен входить в список магазинов, указанных в Программе лояльности;
• loyaltyEventDiscountId — ID скидки по событию, если событие применимо. Возвращается в предварительном расчете.

Важно!

При создании заказа не требуется передавать количество бонусов к начислению, так как логика реализована на стороне системы и применяется при передаче соответствующего типа привилегии в заказе. Бонусы на счет участия начислятся, когда заказа перейдет в группу статусов «Выполнен».

Создание заказа без идентификатора клиента

При создании заказа, в котором не передан идентификатор клиента - сущность клиента создается автоматически. Данные по созданному клиенту будут возвращены в ответе на запрос создания заказа. Для того, чтобы применить в созданном заказе Программу лояльности, необходимо сначала создать участие для клиента, после чего, путем редактирования заказа, передать privilegeType.

Списание бонусов в заказе

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

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

Фактическое списание бонусов может быть меньше, чем передано, в случае, если не удается корректно распределить сумму скидки по товарам. Метод отдает в ответе количество списанных бонусов для обработки такой ситуации. Для того, чтобы точно рассчитывать количество, используйте предварительный расчет заказа с ПЛ.

Работа с подтверждением по SMS при списании схожа с активацией, подробности смотрите в описании метода списания бонусов.

Пример ответа на запрос списания бонусов:

{
    "success": true,
    "order": {
        "bonusesCreditTotal": 4521,
        "bonusesChargeTotal": 150,
        "privilegeType": "loyalty_level",
        "totalSumm": 37760,
        "loyaltyAccount": {
            "id": 26,
            "amount": 0
        },
        "loyaltyLevel": {
            "id": 92,
            "name": "Мастер шоппинга"
        },
        "customer": {
            "id": 309,
            "personalDiscount": 10
        },
        "delivery": {
            "cost": 100
        },
        "site": "b12-skillum-ru",
        "items": [
            {
                "bonusesChargeTotal": 74,
                "bonusesCreditTotal": 2250,
                "discounts": [ // массив скидок по типу на строку товара
                    {
                        "type": "manual_product",
                        "amount": 200
                    },
                    {
                        "type": "manual_order",
                        "amount": 990
                    },
                    {
                        "type": "bonus_charge",
                        "amount": 74
                    }
                ],
                "id": 968,
                "initialPrice": 10000,
                "discountTotal": 632,
                "prices": [
                    {
                        "price": 9368,
                        "quantity": 2
                    }
                ],
                "vatRate": "20.00",
                "quantity": 2,
                "offer": {
                    "id": 26,
                    "externalId": "27"
                }
            },
            {
                "bonusesChargeTotal": 76,
                "bonusesCreditTotal": 2271,
                "discounts": [
                    {
                        "type": "manual_order",
                        "amount": 1000
                    },
                    {
                        "type": "bonus_charge",
                        "amount": 76
                    }
                ],
                "id": 969,
                "initialPrice": 20000,
                "discountTotal": 1076,
                "prices": [
                    {
                        "price": 18924,
                        "quantity": 1
                    }
                ],
                "vatRate": "20.00",
                "quantity": 1,
                "offer": {
                    "id": 22,
                    "externalId": "23"
                }
            }
        ]
    }
}