Интеграция по API

Введение

API Factoring Мокка создано того, чтобы предоставить интернет-магазинам возможность простого и быстрого подключения дополнительного способа оплаты заказов – "Мокка – оплата авансом".

Использование API Factoring Мокка на сайте потребует минимальных доработок на стороне вашего интернет-магазина. В составе API уже присутствует клиентская форма ввода данных iFrame, посредством которой будет производиться взаимодействие с сервисом. Вам останется только реализовать способ оплаты, настроить отображение виджета Мокка и разместить на сайте маркетинговые материалы в соответствии с гайдлайнами Мокка.

Бизнес-процессы

Использование API позволяет автоматизировать следующие бизнес-процессы:

• Получение лимита клиентом
• Создание и завершение заказа
• Отмена заказа
• Возврат

Получение лимита

Процесс инициируется клиентом в момент, когда он регистрируется/авторизуется через  виджет Мокка в карточке товара.

1. Клиент нажимает на виджет в карточке товара;
2. Партнёр отправляет в Мокка запрос Registration, передавая в нём все имеющиеся сведения о клиенте;
3. Мокка передает партнёру ссылку на подготовленную форму регистрации;
4. Партнёр отображает на своём сайте форму регистрации/авторизации Мокка;
5. Клиент вводит в форму недостающие данные (текущий пользователь нажимает кнопку Войти и вводит номер телефона) и подтверждает согласие на использование его персональных данных, запуская оформление заявки на получение лимита;
6. Клиент подтверждает оформление заявки вводя код из СМС;
7. Мокка рассчитывает и возвращает доступный клиенту лимит.

Создание и завершение заказа

Процесс инициируется клиентом в момент, когда он оформляет заказ в интернет-магазине.

1. Клиент выбирает способ оплаты "Мокка – Оплата авансом" совершая покупку в интернет-магазине партнёра;
2. Партнёр отправляет в Мокка запрос Checkout, передавая в нём все имеющиеся сведения о клиенте;
3. Мокка передает партнёру ссылку на подготовленную форму оформления заказа;
4. Партнёр отображает на своём сайте форму оформления заказа Мокка;
5. Клиент вводит в форму регистрации недостающие данные (текущий пользователь нажимает кнопку "Войти" и вводит номер телефона) и подтверждает согласие на использование его персональных данных, запуская оформление заявки;
6. Мокка принимает решение о возможности выдачи клиенту аванса, рассчитывает доступные клиенту графики платежей;
7. Клиент выбирает подходящий ему срок погашения аванса, и выражает согласие с предложенным ему графиком платежей, подтверждая покупку;
8. Мокка формирует договор купли-продажи с использованием аванса, и информирует о принятом решении партнёра и клиента;
9. Партнёр оформляет продажу товара клиенту;
10. Клиент получает уведомление об успешной покупке;
11. Партнёр осуществляет доставку заказа и отправляет чек покупки;
12. Клиент принимает заказ;
13. Партнёр отправляет в Мокка запрос Finish, включив в него чек покупки, для передачи договора купли-продажи на обслуживание в Мокка;
14. Мокка отправляет реестр операций на почту партнёра, и переводит на счёт партнёра денежные средства, за переуступку права требования долга с клиента в пользу Мокка.

Отмена заказа
Процесс инициируется клиентом в момент, когда он отменяет сделанный заказ на сайте партнёра его получения.

1. Клиент отменяет оформленный заказ на сайте или через службу поддержки партнёра;
2. Партнёр отправляет в Мокка запрос Cancel;
3. Мокка производит отмену аванса и восстанавливает лимит клиента;
4. Партнёр получает подтверждение отмены аванса и оформляет отмену заказа.

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

1. Клиент оформляет частичный или полный возврат товара;
2. Партнёр отправляет в Мокка запрос Return;
3. Мокка подтверждает возможность отмены аванса;
4. Партнёр получает подтверждение отмены аванса, и возвращает Мокка оплату за товары;
5. Мокка производит действия в зависимости от типа возврата:
   • Частичный возврат:
     • Частичное восстановление лимита клиента в соответствии с суммой возврата;
     • Пересчет графика платежей в соответствии с новой суммой покупки;
   • Полный возврат:
     • Полное восстановление лимита клиента;
     • Возврат клиенту свободного остатка (денежных средств, уже внесенных клиентом в качестве погашения аванса);

Шаги интеграции

Процесс интеграции c Мокка включает в себя следующие шаги:

1. Реализация: первичное знакомство и интеграция с Мокка.
2. Виджет Мокка: разместить виджет на карточках товаров.
3. Размещение маркетинговых материалов: разместить маркетинговые материалы Мокка согласно гайдлайнам.
4. Тестирование: поиск и устранение ошибок, которые могут возникнуть в ходе отправки и обработки запросов.
5. Запуск: получение боевых настроек от менеджера по интеграции Мокка и старт приёма платежей.

Реализация
На данном шаге необходимо ознакомиться с порядком использования API Factoring Мокка, правилами формирования и отправки запросов к сервису и подготовить тексты запросов для проведения отладочного тестирования.

Тестирование и отладка запросов в ходе интеграции производятся на тестовом сервере 

https://demo.revoup.ru

Тестовые параметры
Для формирования тестовых запросов вам необходимо заранее получить от менеджера по интеграции Мокка тестовые параметры: идентификатор магазина – store_id и секретный ключ - secret_key.

Методы API
API Factoring реализовано на протоколе HTTPS на основе json-запросов. Запросы отправляются методом POST.

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

• https://demo.revoup.ru - базовый URL сервиса (тестовый);
• store_id - уникальный идентификатор магазина, полученного от Мокка;
• signature - цифровую подпись, сформированную на основании текста json-запроса и ключа secret_key.

Порядок формирования цифровой подписи

1. Подготовить корректный json-запрос.
2. К полученному результату добавить secret_key, полученный от Мокка.
3. К итоговой строке применить алгоритм шифрования SHA1.

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

1. В переменную data вводится тело json запроса:

   data = {
         "callback_url": "https://shop.ru/revo/decision",
         "redirect_url": "https://shop.ru/revo/redirect",
         "primary_phone": "9267654321",
         "primary_email": "LOGIN@MAIL.com",
         "current_order":
         {
             "order_id": "R001234"
         }
     }
   
     {:callback_url=>"https://shop.ru/revo/decision", :redirect_url=>"https://shop.ru/revo/redirect", :primary_phone=>"9267654321", :primary_email=>"LOGIN@MAIL.com", :current_order=>{:order_id=>"R001234"}}

2. data переводится в json формат:

   data = data.to_json
   
     "{"callback_url":"https://shop.ru/revo/decision","redirect_url":"https://shop.ru/revo/redirect","primary_phone":"9267654321","primary_email":"LOGIN@MAIL.com","current_order":{"order_id":"R001234"}}"

3. В переменную secret_key вводится наименование ключа:

   secret_key = "wkeo0iNv8iZHXCFLEzu2NQzz97nLn0"

4. В переменную signature формируется подпись:

   signature = Digest::SHA1.hexdigest(secret_key + data)
   
     "347e8cff27d30b5200c8b32def4365ebbf4270d0"

5. Тело json запроса выводится через команду puts для отправки запроса через API CLIENT:

   puts data
   
     {"callback_url":"https://shop.ru/revo/decision","redirect_url":"https://shop.ru/revo/redirect","primary_phone":"9267654321","primary_email":"LOGIN@MAIL.com","current_order":{"order_id":"R001234"}}

Пример отправки запроса через API CLIENT

1. В поле Request URL вводится заголовок запроса, с цифровой подписью, полученной на шаге 4 предыдущего раздела:

   POST https://demo.revoup.ru/{URL_API}? store_id=72&signature=347e8cff27d30b5200c8b32def4365ebbf4270d0

2. В поле Body вводится текст запроса, полученный на шаге 5 предыдущего раздела:

   {
         "callback_url": "https://shop.ru/revo/decision",
         "redirect_url": "https://shop.ru/revo/redirect",
         "primary_phone": "9267654321",
         "primary_email": "LOGIN@MAIL.com",
         "current_order":
         {
             "order_id": "R001234"
         }
     }

Виджет Мокка

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

Для интеграции виджета Мокка на ваш сайт, выполните следующие шаги:

Добавление контейнера для кнопки
Вставьте следующий HTML-код в футер вашего сайта или в другое подходящее место на странице, где должна появиться кнопка:

<!-- Контейнер, в который будет добавлена кнопка -->
<div id="container-id"></div>

Обратите внимание на следующие параметры:

• containerId - Укажите id контейнера, в который будет добавлена кнопка.

Подключение и инициализация
Добавьте следующий скрипт на страницу после контейнера:

<!-- Подключаем виджет Мокка -->
<script src="https://storage.yandexcloud.net/mb-prod-ru-public/data/attachment/file/split_price_widget_code/451770d6494e5511750a5081b1e037bfd31b466a.js"></script>
<script>
document.addEventListener("DOMContentLoaded", () => {
// После загрузки скрипта вызываем метод init с параметрами
revoPriceWidget.init({
months: [X, XX], // Период
overpaymentAmount: xxx, // Сумма переплаты
orderAmount: XXX, // Минимальная сумма заказа
button: {
containerId: "container-id", // ID элемента, в который добавляется кнопка
payment: XXX, // Минимальный размер платежа
theme: "orange", // Тема кнопки: "white" | "black" | "orange"
onClick: () => { // Обработчик клика по кнопке
console.log('click');
}
}
});
});
</script>

Обратите внимание на следующие параметры:

• containerId - Укажите id контейнера, в который будет добавлена кнопка.
• months - Задайте период, в течение которого применяются условия (например, [1, 10]).
• overpaymentAmount - Укажите сумму переплаты.
• orderAmount - Укажите минимальную сумму заказа.
• payment - Укажите минимальный размер платежа.
• theme - Выберите тему кнопки (возможные значения: "white", "black", "orange").

Реализация события onClick
В обработчике события onClick вам необходимо реализовать вызов метода Registration через бекенд вашего сайта. Это обеспечит открытие iframe после нажатия на кнопку.
Пример обработчика:

onClick: () => {
// Вызов метода Registration через бекенд вашего сайта
// Пример кода вызова API
fetch('/your-backend-endpoint',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Параметры для метода Registration
}),
})
.then(response => response.json())
.then(data => {
// Открываем iframe с данными
console.log(data);
})
.catch(error => console.error('Ошибка:', error));
}

На данном шаге выполняется размещение маркетинговых материалов Мокка на сайте. Существуют определённые требования к визуализации сервиса Мокка на стороне партнёра. В ходе интеграции необходимо:

1. Разместить на главной странице баннер, при нажатии на который клиент будет перенаправлен на лендинг Мокка. На лендинг клиент может зарегистрироваться и узнать сумму доступного ему аванса.

   

   Настройка: отправка запроса Registration при щелчке по баннеру.

2. Настроить отображение виджета Мокка в карточке каждого товара. Виджет покажет клиенту размер ежемесячного платежа при покупке товара с использованием аванса.

   

   Настройка: отправка запроса Registration при нажатии по виджету Мокка.

3. Разместить способ оплаты "Мокка – оплата авансом" в корзине. Покупатели получают возможность моментально получить аванс Мокка и оформить заказ.

   

   Настройка: отправка запроса Checkout после оформления заказа.

4. Добавить на поддомен вашего сайта лендинг Мокка. На лендинге клиент может ознакомиться с подробными условиями, зарегистрироваться и узнать размер доступного его аванса, а также получить ответы на часто задаваемые вопросы. Содержание лендинга предоставляется в виде iframe.

   
5. Добавить информацию о возможности использования сервиса Мокка в разделе "Способы оплата"
   

Запуск

• После тестирования и настройки методов можно перейти к созданию реальных заявок.
• Для создания реальных заявок используйте метод Checkout.
• Для работы с методом Checkout, используйте боевые ключи store_id и secret_key, а также боевой URL, полученные от персонального менеджера.
• Расскажите своим клиентам о новом способе оплаты Мокка, используя маркетинговые материалы.