Интеграция с маркетплейсами или как я научился не волноваться и полюбил API-интеграцию

В нашей компании принято устраивать звонки-знакомства — на них клиенты могут напрямую пообщаться с командами, которые будут им помогать или сопровождать. Во время таких встреч поднимается множество вопросов, в том числе связанных с интеграцией. Чаще всего вопросы одни и те же, поэтому я даже имею заготовленный спич, который позволяет на пальцах объяснить принцип работы нашей интеграции и быстро оценить сложность её реализации на своей стороне. Спич долго был только в моей голове, но для Хабра я решил изложить его в письменном виде и поделиться с вами.

? Сначала материал не разрешили публиковать — сочли его рекламным. Но когда узнали все детали — что через наш API можно формировать до 500 запросов в сутки бесплатно (а этого по опыту хватает в среднем на обработку 50 заказов), — «дали зеленый свет» и попросили указать все это в начале материала. Что я и делаю ? Заявку на подключение доступа можно оформить на сайте компании через форму обратной связи.

Шаг 1. Обновление цен и стоков

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

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

Мгновенное обновление при событии

В учётной системе клиента произошло изменение цены или стока.
Учётная система клиента отслеживает это событие и в тот же момент вызывает методы передачи цены или стока (в зависимости от того, что изменилось) и отправляет новые значения в XWAY API.
XWAY API доставляет данные до маркетплейсов.

Таким образом, время, прошедшее с момента изменения данных в учётной системе клиента до обновления данных на маркетплейсе, составляет сотни миллисекунд, максимум 1-2 секунды. Это самый правильный сценарий, к которому стоит стремиться. Так сказать, идеальный мир интеграции ?

Запуск рекуррентного обновления по времени

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

Раз в N минут (параметр целиком и полностью зависит от конкретной системы) запускается сборщик, который пробегает по всей базе и выделяет массив товаров, где изменилась цена или сток за последние N минут.
Для найденных массивов товаров формируются соответствующие запросы на обновление цен или стоков и передаются в XWAY API.
XWAY API доставляет данные до маркетплейсов.

Очевидным минусом такого подхода является его дискретность. По опыту, наши клиенты, использующие данную схему, осуществляют отправку данных раз в 5 минут и реже. Если сделать чаще, то появляется высокая нагрузка на учётную систему клиента. Если сделать реже — увеличится вероятность продажи большего количества товаров, чем есть на складе.

Запуск полного обновления по времени

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

Раз в N минут (параметр целиком и полностью зависит от конкретной системы) запускается обмен по всем товарам, которые есть у клиента.
Для всех товаров формируются соответствующие запросы на обновление цен или стоков и передаются в XWAY API.
XWAY API доставляет данные до маркетплейсов.

Конечно же, дикие объемы передаваемых данных. Естественно, такой обмен невозможно сделать быстрым, хотя бы потому, что тут же начинаем упираться в лимиты по запросам маркетплейсов. Но если по другому нельзя, то можно и так сделать ?

Примеры методов

Обновление цен

Возможны 2 модели асинхронного взаимодействия, с использованием Webhook и без него.

Если используется Webhook:

В запросе продавец передаёт URL своего эндпоинта в параметре request_url.

{ "request_url": "https://seller.com/webhook/", "shop_id": 2145, "items": [ { "external_id": "204245576795", "price": 99987, "discount_price": 95000, "available": true, "batch_count": 1 }, { "external_id": "204245576797", "price": 39342, "discount_price": 30999, "available": false, "batch_count": 1 } ] }

После обработки запроса на указанный эндпоинт продавца придёт request_id.
Используя метод https://seller-api.xway.ru/api/v2/requests/{request_id} продавец получает результат выполнения запроса.

Если не используется Webhook:

В запросе продавец не передаёт параметр request_url.

{ "shop_id": 2145, "items": [ { "external_id": "204245576795", "price": 99987, "discount_price": 95000, "available": true, "batch_count": 1 }, { "external_id": "204245576797", "price": 39342, "discount_price": 30999, "available": false, "batch_count": 1 } ] }

В ответе на запрос продавец сразу получает request_id
Используя метод https://seller-api.xway.ru/api/v2/requests/{request_id} продавец получает результат выполнения запроса.

? В одном запросе нельзя передавать цену на один и тот же товар более одного раза.

? В одном запросе нельзя передавать массив более чем из 500 элементов.

Шаг 2. Получение заказов

Следующий поток данных, который нам нужно организовать для полноценной работы с маркетплейсами по схеме FBS — обмен информацией о заказах. Чем быстрее продавец получит заказ с маркетплейса и его обработает (зарезервирует товар под этот заказ), тем быстрее он сможет протранслировать новые значения остатков для товаров, которые были в заказе. И тем меньше вероятность оверсейла (продажи большего числа товара, чем есть на складе).

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

Продавец запрашивает новые заказы по расписанию

Продавец при разработке интеграции реализует в своей учётной системе метод, который с определённой периодичностью обращается к XWAY API и получает список новых заказов. То есть в качестве инициатора обмена выступает система продавца.

Понятно, что такая схема приводит к задержкам, напрямую зависящим от частоты запросов.

Если сделать частоту запросов слишком большой, то задержка уменьшится, но при этом увеличится нагрузка как на учётную систему продавца, так и на сервер XWAY API.
Если сделать частоту запросов слишком низкой, то задержка увеличится, что приведёт к оверсейлам.

Запрос на получение списка заказов достаточно простой. Это GET запрос, в котором можно с помощью параметров добавить дополнительную фильтрацию, например, по дате создания, дате изменения, статусу заказа и так далее.

Пример запроса на получение списка заказов для магазина с id 6414 и статусом delivered:

curl --request GET \   --url 'https://seller-api.xway.ru/api/v2/orders/?shop_id=6414&status=delivered' \   --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci587IUzI1NiJ9.eyJ1c2VyX2lkIjo2MDQ1LCJ1c2VyX2d1aWQiOiI2ZWQzNDE2Yy03YmQzLTQyNTctYmQzYi1hZjRlNTYzNzE2OGEiLCJleHAiOjE2OTI4MDQyNTgsImF1dGhfbWV0aG9kX3R5cGUiOiJFTUFJTCIsImFjY291bnRzIjp7IlBBU1NQT1JUIjo2MDQ1LCJVTklDT1JOIjo1NTY2fSwicGVybWlzc2lvbnMiOnt9LCJpc194d2F5X2VtcGxveWVlIjpmYWxzZX0.Qf63EQ_kF-ZwIzJYIdC_izro1uTsh6q1zJslxsGcpuc' \   --header 'content-type: application/json

В ответ на подобный запрос XWAY API выдаст список заказов для данного магазина:

{ "meta": { "request_id": "a4a17610-9ee9-48f5-a33d-e888eb1846d2", "message": null }, "result": { "orders": [ { "id": 34511146, "shop_id": 6414, "order_id": "107586281", "marketplace_code": "beru", "created_at": "2022-04-27T03:00:00.000000Z", "modified_at": "2022-05-01T13:24:01.165000Z", "status": "delivered" }, { "id": 34511144, "shop_id": 6414, "order_id": "107857757", "marketplace_code": "beru", "created_at": "2022-04-29T03:00:00.000000Z", "modified_at": "2022-05-01T13:10:49.838000Z", "status": "delivered" } ] }, "pagination": { "limit": 100, "offset": 0, "total": 482 } }

Продавец получает информацию о новых заказах на webhook

Продавец при разработке интеграции реализует в своей учётной системе дополнительный эндпойнт (урл, webhook), адрес которого прописывается в XWAY API. Как только в XWAY API появляется информация о том, что у продавца на любом из маркетплейсов появился новый заказ, в тот же момент XWAY API отправляет уведомления на webhook продавца и селлер тут же вызывает метод получения нового заказа.

Такая схема работы чуть более сложна в реализации для продавца (ему нужно делать отдельный webhook и писать дополнительный обработчик), но обладает рядом важных преимуществ:

Оптимизация трафика между двумя системами. Обмен начинается только в том случае, если поступил заказ.
Ускорение обмена между двумя системами. Как только пришёл новый заказ, в тот же момент XWAY API отправляет соответствующее уведомление учётной системе продавца и запускается обмен информацией по заказу. Задержка между появлением заказа в XWAY API и в системе продавца уменьшается до 1 секунды.

Получения полной информации о заказе

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

curl --request GET \ --url 'https://seller-api.xway.ru/api/v2/orders/34511146?shop_id=6414' \ --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJ589GciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo2MDQ1LCJ1c2VyX2d1aWQiOiI2ZWQzNDE2Yy03YmQzLTQyNTctYmQzYi1hZjRlNTYzNzE2OGEiLCJleHAiOjE2OTI4MDQyNTgsImF1dGhfbWV0aG9kX3R5cGUiOiJFTUFJTCIsImFjY291bnRzIjp7IlBBU1NQT1JUIjo2MDQ1LCJVTklDT1JOIjo1NTY2fSwicGVybWlzc2lvbnMiOnt9LCJpc194d2F5X2VtcGxveWVlIjpmYWxzZX0.Qf63EQ_kF-ZwIzJYIdC_izro1uTsh6q1zJslxsGcpuc' \ --header 'content-type: application/json'

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

{ "meta": { "request_id": "d1268645-be96-4634-b814-07933c2dc819" }, "result": { "id": "42486407", "shop_id": 2848, "marketplace_code": "SMM", "order_id": "747378127", "created_at": "2022-08-01T11:56:45.000000Z", "modified_at": "2022-08-01T11:59:10.670598Z", "status": "delivered", "antifraud_status": null, "total_amount": 95.0, "memo": null, "order_items": [ { "id": 43273407, "xway_offer_id": 22763052, "external_id": "84.140", "sku_code": "22763052", "seller_price": 718.0, "buyer_price": 95.0, "subsidy": 623.0, "currency_code": "RUB", "name": "Антимоскитная сетка \"Герберы\" для дверного проема 2,1х1,0м", "quantity": 1, "is_cancel": false, "memo": null, "properties": [] } ], "buyer_info": { "name": null, "phone": null }, "delivery": { "delivery_status": null, "service_type": "fbs", "shipment_date": "2022-08-04T15:00:00+00:00", "warehouse_id": null, "delivery_price": 0.0, "delivery_type": null, "delivery_service": "delivery_by_goods", "customer": { "name": "Мина Мария", "phone": null, "address_full": "г Киров, ул Пушкина, д 15А", "address_detail": null }, "delivery_interval": { "from_date": "2022-08-07", "to_date": "2022-08-07", "from_time": "21:00", "to_time": "21:00", "timezone": "UTC+0" }, "shipments": [] }, "requirements": { "gtd": [], "country": [], "mandatory_mark": [], "rnpt": [] } } }

Шаг 3. Обработка заказа

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

Забудьте как страшный сон!

Мы всё уже сделали: свели все методы к единому набору, а все статусы — к единой статусной модели.

Вам без разницы, заказ с какого маркетплейса вы хотите обрабатывать. Просто всегда делайте одну и ту же последовательность шагов на складе и одну и ту же последовательность вызовов XWAY API:

Подтверждаем или отменяем товары в заказе.
Собираем заказ.
Получаем наклейку на упакованное отправление.
Создаём поставку.
Получаем документы на поставку.

ВСЁ! ?

Всего пять шагов, всегда стандартные пять шагов ?

Конечно, я мог бы далее расписать каждый из шагов, привести примеры кода…но мне кажется, это уже лишнее. Если вам действительно интересны технические детали, вы можете ознакомиться с ними в нашей документации https://seller-api.xway.ru/redoc

В заключении хочется выразить простую мысль, которую я хотел донести в этой статье:

Интеграция может быть простой и понятной.

Забудьте об особенностях каждого маркетплейса, о куче методов, механизмов авторизации, множестве ключей и кредов для каждого маркетплейса, о разных айди, каждый из которых называется по-своему и каждый из которых надо передавать в свои методы и в свои параметры. Просто сделайте одну интеграцию — и работайте спокойно, а всю эту головную боль можно делегировать экспертам 🙂 Если у вас есть вопросы, буду рад ответить на них в комментариях или в Телеграм @anton_batashov

ссылка на оригинал статьи https://habr.com/ru/articles/686904/