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

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

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

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

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

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

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

При создании заказа площадка может передать параметры мест, а также распределить по местам товары:

{
    ...
    "items":[
        {
            "id":"item-1",
            "name":"Название товара 1",
            "price":1000,
            "quantity":1
        },
        {
            "id":"product2",
            "name":"Название товара 2",
            "price":3000,
            "quantity":2
        },
        {
            "id":"555123",
            "name":"Название товара 3",
            "price":800,
            "quantity":1
        }
    ],
    "delivery": {
      ...
      "packages": [
        {
          "weight": 0.5,
          "height": 11,
          "length": 10,
          "width": 12,
          "itemsIds": [
            "item-1",
            "555123"
          ]
        },
        {
          "weight": 1,
          "height": 6,
          "length": 20,
          "width": 12,
          "itemsIds": [
            "product2"
          ]
        }
      ],
      ...
    },
    ...
}

В интерфейсе настроек продавец должен выбрать способ отправки заказа: со склада или от двери.

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

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