Интеграция с торговыми площадками
Чтобы подключить Безопасную Сделку к площадке, необходимо реализовать взаимодействие с сервисом Безопасных Сделок и Агрегатором Служб Доставки, а также реализовать интерфейсы оплаты, расчета доставки, создания накладной, трекинга и т.п. Это многие часы работы разработчиков, аналитиков и тестировщиков.
Мы создали сервис, который делает интеграцию проще. Он работает так: вы передаете через API этого сервиса данные заказа и встраиваете в свою площадку готовые интерфейсы оплаты, управления доставкой, трекинга (через IFRAME или открывая в новой вкладке, с дальнейшим возвратом на страницы площадки).
API сервиса позволяет создавать, обновлять и получать данные о заказах. На все изменения которые происходят с заказами, мы отправляем вебхук уведомления.
Все, что необходимо для предоставления вашим пользователям Безопасной Сделки и доставки уже готово, нужно лишь встроить решение в свои интерфейсы.
Подключение площадки
Для получения тестового доступа к сервису интеграции необходимо запросить в техподдержке Наложки развертывание тестовой версии (песочницы). Для этого можно написать письмо на адрес contact@наложка.рф или сообщение нашему телеграм-боту поддержки.
Адрес боевого сервера и секрет для подписи запросов можно получить после заключения договора с Наложкой.
Аутентификация запросов
Аутентификация запросов производится путем проверки полученной в месте с запросом подписи, вычисляемой по следующему алгоритму:
- конкатенируем:
- путь и параметры URL запроса (например
/some/url?param1=1¶m2=val
), из списка исключаем параметр с именемs
; - тело запроса (с точностью до байта, т.е. пробельные символы в начале и в конце тела имеют значение);
- секрет (выдается администрацией сервиса Наложка).
- путь и параметры URL запроса (например
- от полученной строки вычисляем дайджест по алгоритму sha256.
Подпись передается в hex-представлении в заголовке
X-Nalogka-Signature
(предпочтительно для API-запросов) или в параметре
запроса с именем s
(используется при открытии страниц пользовательских
интерфейсов, должен добавляться последним параметром).
Адреса пользовательских интерфейсов
Страница настроек продавца
🔗/manage/settings/{seller_id}
Страница оплаты заказа покупателем
🔗/order/{order_id}?back_url={back_url}
где back_url – адрес страницы на которую пользователь будет
перенаправляться после завершения процесса оплаты. К этому адресу
перед перенаправлением будет добавляться параметр result
со
значением payment_succeeded
(в случае успешного завершения
оплаты) или payment_failed
(в случае возникновения проблем с
оплатой).
Страница управления заказа продавцом
🔗/manage/{order_id}
Страница просмотра заказа покупателем после оплаты
🔗/order/{order_id}/info
REST API
Данный REST-API предназначен для работы с данными заказов площадки, хранящимися в сервисе Наложка.
В рамках данного API данные передаются в JSON формате. Методы API, а также структуры передаваемых данных и возвращаемых ошибок описаны ниже.
Уведомление об изменениях
При изменении данных заказа, вследствие выполнения пользователем действий в интерфейсах Наложки или при получении Наложкой данных от сторонних систем, Наложка уведомляет площадку посредством отправки HTTP-запроса на адрес, указанный при подключении площадки к Наложке.
В строку запроса добавляется параметр s
, содержащий подпись.
Подпись рассчитывается по алгоритму, описанному в разделе
Аутентификация запросов.
Пример такого HTTP-запроса:
POST /nalozhka-event?s=cd253ea0d7b1654639887e63df6a554794ea97a9529ea9f6bb39299aefd248ff
Host: some.marketplace.com
Content-Type: application/json
Content-Length: 323
{
"eventId": "7TSby7y57UZMapj8",
"eventType": "OrderUpdatedEvent",
"initiator": "admin",
"orderId": "1950021",
"changeSet": {
"status": {
"old": "payment-waiting",
"new": "payment-in-progress"
},
"statusName": {
"old": "Ожидается оплата",
"new": "В процессе оплаты"
}
}
}
В поле initiator
структуры события указывается сторона,
сделавшая изменения:
seller
- продавец через пользовательские интерфейсы сервиса интеграции;buyer
- покупатель через пользовательские интерфейсы сервиса интеграции;admin
- администратор через административные интерфейсы по согласованию с продавцом и/или покупателем;system
- автоматические процедуры.