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

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

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

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

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

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

1. В учётной системе клиента произошло изменение цены или стока.

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

3. XWAY API доставляет данные до маркетплейсов.

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

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

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

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

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

3. XWAY API доставляет данные до маркетплейсов.

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

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

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

1. Раз в N минут (параметр целиком и полностью зависит от конкретной системы) запускается обмен по всем товарам, которые есть у клиента.

2. Для всех товаров формируются соответствующие запросы на обновление цен или стоков и передаются в XWAY API.

3. XWAY API доставляет данные до маркетплейсов.

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

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

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

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

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

1. В запросе продавец передаёт 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
		}
	]
}

2. После обработки запроса на указанный эндпоинт продавца придёт request_id.

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

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

1. В запросе продавец не передаёт параметр 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
		}
	]
}

2. В ответе на запрос продавец сразу получает request_id

3. Используя метод 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:

1. Подтверждаем или отменяем товары в заказе.

2. Собираем заказ.

3. Получаем наклейку на упакованное отправление.

4. Создаём поставку.

5. Получаем документы на поставку.

ВСЁ! ????

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

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

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

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

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