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

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

Мы создали сервис, который делает интеграцию проще. Он работает так: вы передаете через 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: 140

{
    "eventId": "7TSby7y57UZMapj8",
    "eventType": "some-event",
    "initiator": "admin",
    "orderId": "1950021",
    "someData": []
}

В поле initiator структуры события указывается сторона, сделавшая изменения:

• seller - продавец через пользовательские интерфейсы сервиса интеграции;
• buyer - покупатель через пользовательские интерфейсы сервиса интеграции;
• admin - администратор через административные интерфейсы по согласованию с продавцом и/или покупателем;
• system - автоматические процедуры.

# Типы и структура уведомлений

# Уведомление об изменении продавцом настроек

eventType: seller_settings-update

Структура:

{
  "sellerId": "seller49182",
  "data": {
    "id": "seller49182",
    "settings": {
      "default_payment_requisite_id": "1a29sLfVf8o",
      "default_city_id": "430",
      "default_city_name": "Самара, Самарская обл.",
      "first_name": "Сергей",
      "last_name": "Петров",
      "middle_name": "Владимирович",
      "phone": "79876543210",
      "agree_terms": true,
      "company_application_status": null,
      "commission_payer": "buyer",
      "seller_type": "person",
      "company_name": null
    },
    "profile_id": null
  },
  "eventId": "edCOyLwvRL2ny6ST",
  "eventType": "seller_settings-update",
  "initiator": "seller"
}

# Уведомление об изменении заказа

eventType: order-update

Структура:

{
  "orderId": "order49182-1",
  "orderStatus": "payment-in-progress",
  "changeSet": {
    "status": {
      "old": "payment-waiting",
      "new": "payment-in-progress"
    }
  },
  "eventId": "a2COfLw5wL22y6fY",
  "eventType": "order-update",
  "initiator": "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 - url, на который мы перенаправим (внутри iframe) покупателя после попытки (успешной или нет) оплатить заказ.

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

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

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

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

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

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

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