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