Интеграция с сервисами Наложка

Интеграция с торговыми площадками

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

Мы создали сервис, который делает интеграцию проще. Он работает так: вы передаете через API этого сервиса данные заказа и встраиваете в свою площадку готовые интерфейсы оплаты, управления доставкой, трекинга (через IFRAME или открывая в новой вкладке, с дальнейшим возвратом на страницы площадки).

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

Все, что необходимо для предоставления вашим пользователям Безопасной Сделки и доставки уже готово, нужно лишь встроить решение в свои интерфейсы.

Подключение площадки

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

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

Аутентификация запросов

Аутентификация запросов производится путем проверки полученной в месте с запросом подписи, вычисляемой по следующему алгоритму:

  1. конкатенируем:
    • путь и параметры URL запроса (например /some/url?param1=1&param2=val), из списка исключаем параметр с именем s;
    • тело запроса (с точностью до байта, т.е. пробельные символы в начале и в конце тела имеют значение);
    • секрет (выдается администрацией сервиса Наложка).
  2. от полученной строки вычисляем дайджест по алгоритму 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 - автоматические процедуры.

Пример процесса взаимодействия с сервисом

Указание настроек продавца

В интерфейсах площадки, на странице, доступной только продавцу, встраивается iframe настройки продавца:

{base_url}/manage/settings/{seller_id}?back_url={callback_url}&s={signature}

  • base_url - адрес сервиса, предоставленный тех. поддержкой
  • seller_id - id продавца на стороне площадки
  • signature - вычисленная подпись запроса
  • callback_url - url, на который мы перенаправим (внутри iframe) продавца после успешного указания необходимых данных. Параметр не обязятельный, можно использовать для установки признака, что у продавца на площадке доступны безопасные сделки.

На встроенной странице продавец указывает карту и необходимые персональные данные. После этого можно создавать заказы с id этого продавца.

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

Площадка отправляет запрос на создание заказа:

POST {base_url}/api/order?s={signature}

В теле запросы необходимо передать данные заказа в формате json, пример минимально необходимых данных:

{
    "id":"order-1",
    "items":[
        {
            "id":"item-1",
            "name":"Название товара",
            "price":1000,
            "quantity":1
        }
    ],
    "seller": {
        "id":"seller-1",
        "email":"seller@example.com"
    },
    "buyer": {
        "id":"buyer-1",
        "email":"buyer@example.com",
        "phone":"79019876543",
        "person":{
            "lastName":"Тестовый",
            "firstName":"Покупатель"
        }
    }
}
  • id - id заказа на стороне площадки
  • seller.id - id продавца на стороне площадки
  • buyer.id - id покупателя на стороне площадки

В ответ на запрос будет отдана информация о заказе, пример:

{
    "id": "order-3",
    "status": "payment-waiting",
    ...
}

Оплата заказа покупателем

После успешного создания заказа площадка показывает покупателю iframe с формой оплаты заказа:

{base_url}/order/{order_id}?back_url={callback_url}&s={signature}

  • order_id - id заказа на стороне площадки

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

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

Подтверждение заказа продавцов

После успешной оплаты заказа площадка показывает продавцу iframe с формой подтверждения заказа:

{base_url}/manage/{order_id}?back_url={callback_url}&s={signature}

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

На этой-же странице продавец, в дальнейшем, сможет отслеживать процесс доставки.

← Хранилище Файлов →