Как мы интегрировались в казахстанский маркетплейс или история о нюансах

Привет! Меня зовут Ваня Крючков, я бэкенд-разработчик в Далее. Сегодня поделюсь опытом интеграции интернет-магазина Haier с маркетплейсом Kaspi. Это история о том, как, несмотря на ограничения и не самое удобное API, нам удалось интегрироваться с самым популярным маркетплейсом в Казахстане и увеличить продажи в 3 раза.

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

Что такое Kaspi

Kaspi — самый популярный маркетплейс в Казахстане. Им пользуются около 11 миллионов человек в месяц. Он входит в структуру Kaspi Group, в которой, в том числе есть одноименная платежная система и банк.

Сайт маркетплейса представляет собой витрину товаров, а все покупки осуществляются через суперапп.

Сайт Haieronline.kz уже интегрирован с внешними системами разными способами и с разными форматами данных. Так что еще одна интеграция казалась задачкой довольно тривиальной.

Связи между системами и зоны ответственности

Процесс онлайн-продаж Haier в Казахстане обеспечивается тремя основными системами:

сайт
система управления заказами (CRM)
система аналитики (СА).

За каждой системой закреплена отдельная команда. Мы работаем с «приемником» заказов, то есть с сайтом.

Основная роль сайта в этой схеме — сохранение заказов в БД и отправка данных в систему аналитики (СА) и систему управления заказами (CRM).
За изменение состояния заказов отвечает CRM. В ней реализованы интеграции с транспортными компаниями и личный кабинет для менеджеров контактного центра.

CRM находится в закрытом контуре, поэтому на стадии разработки сайта мы решили реализовывать обмен через json-файлы (пакеты), которые сайт и CRM помещает на отдельный сервер.

Интеграция с маркетплейсом

Декомпозируем

На старте определим процессы, связанные с маркетплейсом:

Загрузка товаров на маркетплейс.
Обновление цен и остатков по товарам в каспи.
Получение заказов.
Генерация и отправка пакетов заказов в CRM.
Обновление заказов на основе пакетов CRM.
Закрытие заказов.

Рассмотрим каждый их них.

Загрузка товаров

Когда мы взяли задачу в работу, у Kaspi API не было подходящих методов для автоматической загрузки товаров в маркетплейс. Поэтому они загружались руками через ЛК продавца в маркетплейсе.

Обновление цен и остатков по товарам

Здесь все было просто: делаем на сайте фид, указываем ссылку на него в кабинете — profit. Теперь маркетплейс сам может актуализировать цены и остатки на основе данных из фида. Правда, стоит учитывать, что Kaspi ходит в этот фид один раз в час. А цены и остатки на сайте могут меняться в течение часа несколько раз (на практике изменения цен происходят не так часто). Побочный эффект от такого тайминга состоит в том, что на сайте товар может быть в количестве двух единиц, а тем временем на маркетплейсе оформили заказов на пять.

Решение кажется на поверхности: просто менять остатки на маркетплейсе через апишку. Но есть один нюанс — у Kaspi API до сих пор нет метода, который бы позволил менять остаток на складе.

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

Первое нарушение — отключение продаж на 7 дней
Второе нарушение — отключение продаж на 7 дней
Третье — прекращение сотрудничества.

Чтобы исключить подобные отмены, реализовали оповещения для менеджеров. Отправка уведомления происходит, когда значение остатков по товару становится менее трех единиц. При получении оповещения менеджер заходит в ЛК Kaspi и руками деактивирует товар.

Оповещения срабатывают если остатки действительно подходят к концу. Например, если по какому-то товару несколько дней у нас нулевые остатки, или меняются с двух штук до одной — оповещение по ним не шлём.

Получение заказов

Ура, товары есть! Можно создавать заказ и пробовать его получить. Для начала разберем метод GET https://kaspi.kz/shop/api/v2/orders (https://guide.kaspi.kz/partner/ru/shop/api/orders/q3201)

В параметрах запроса нам важны три параметра:

state (string) — состояние заказа
creationDate (array) — временные метки создания заказа «от» и «до»
status (string) — статус заказа

Status, очевидно, должен быть начальный — APPROVED_BY_BANK (одобрен банком).

В качестве CreationDate мы взяли разницу в два часа с момента отправки запроса (в этом параметре передаются временные метки в миллисекундах).

Поскольку изначально доставка осуществлялась партнерами Haier, а не самим маркетплейсом, то state у нас — DELIVERY.

Код написан, но есть третий нюанс — у Kaspi нет никакой тестовой среды. Тестировать предлагают на боевых заказах.

Есть же документация, можно по ней написать код и обернуть тестами, нет?

Документация есть, но Kaspi API работает не всегда очевидно. Например, если в параметре status передать APPROVED_BY_BANK, то в выборку попадут и заказы со статусом ACCEPTED_BY_MERCHANT.

Так что тестировали заказ через покупку за реальные деньги и отмену на стороне клиента.

Диалог во время тестирования:

Разработчик: «Мы готовы протестировать заказ».

Бизнес: «Хорошо, активируйте товар».

Аналитик активирует товар

Бизнес: «Заказ оформил, номер 999».

Разработчик запускает скрипт

Разработчик: «Данные получил, пакет сгенерировался отправился в CRM.

CRM: «Пакет приняли, обработали, высылаем пакет с подтверждением заказа».

Разработчик: «Пакет приняли, отправили подтверждение в Kaspi».

Бизнес: «Отменяю заказ»?

Разработчик: «Да»

Бизнес: «Заказ отменил, скрывайте товар. Получается можно в релиз»?

Аналитик деактивирует товар и понимает что еще не проверено 5 разных кейсов. CRM списывается с разработчиком и обсуждают как пофиксить баги

Разработчик: «Давайте чуть позднее еще проверим другой кейс».

Бизнес идет на следующий созвон…

Генерация и отправка пакета заказа в CRM

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

{   "ID": "HOKZ-0000065603",   "CreateDate": "2024-03-27T16:10:39",   "MarketPlace": null,   "Contact": {     "FirstName": "Локаль",     "LastName": "Тестов",     "Email": "local.test@test.kz",     "PhoneNumber": "+77991112233"   },   "TotalSum": 1319980,   "ProductList": [     {       "ID": "579694",       "Key": 12452,       "ProductID": "SKU579694",       "ProductName": "Игровой компьютер Thunderobot Black Warrior IV Max D",       "Quantity": 2,       "BasePrice": 849990,       "DiscountSum": 380000,       "Sum": 1319980     }   ],   "DeliveryAddress": {     "ID": "750000000",     "Address": "Алматы, Ленина, 12",     "Region": "г Алматы",     "City": "Алматы",     "Street": "Ленина",     "Building": "12",     "FlatOffice": "",     "Entrance": "",     "Floor": "",     "Intercom": "",     "Elevator": false,     "DateTimeFrom": "2024-03-28T09:00:00",     "DateTimeTo": "2024-03-28T20:00:00",     "TransitTime": 1   },   "TransportCompany": {     "ID": "0004",     "UnitName": "Beta Express",     "DeliveryComment": "123"   } }

По объекту MarketPlace CRM понимает, что на их стороне нужно запустить отдельный процесс под заказы с маркетплейсов. Для Kaspi в этом объекте описаны:

id и название маркетплейса
способ доставки (нашей ТК либо силами Kaspi)
код заказа на стороне маркетплейса
дата доставки (которую выставляет сам маркетплейс).

Посмотрим, что возвращает Kaspi и хватит ли нам данных для генерации полного пакета заказа:

{   "data": [     {       "type": "orders",       "id": "MjAwMTMwMDQ=",       "attributes": {         "customer": {           "firstName": "Иван Иваныч",           "lastName": "Иванов",           "cellPhone": "7xx0xxxxxx"         },         "code": "20013004",         "totalPrice": 96045,         "deliveryMode": "DELIVERY_PICKUP",         "paymentMode": "PAY_WITH_CREDIT",         "signatureRequired": false,         "state": "PICKUP",         "creationDate": 1479470446241,         "approvedByBankDate":1479470451108,         "status": "ACCEPTED_BY_MERCHANT",         "deliveryCost": 1000       },       "relationships": {         "entries": {           "links": {             "self": "/v2/orders/MjAwMTMwMDQ=/relationships/entries",             "related": "/v2/orders/MjAwMTMwMDQ=/entries"           }         },         "user": {           "links": {             "self": "/v2/orders/MjAwMTMwMDQ=/relationships/user",             "related": "/v2/orders/MjAwMTMwMDQ=/user"           },           "data": {             "type": "customers",             "id": "Nzc3MDAwMDAwMA=="           }         }       },       "links": {         "self": "/v2/orders/MjAwMTMwMDQ="       }     }   ],   "included": [     {       "type": "customers",       "id":"Nzc3MDAwMDAwMA==",       "attributes": {         "firstName": "Иван",         "lastName": "Иваныч",         "cellPhone": "7xx0xxxxxx"       },       "relationships": {},       "links": {         "self":"/v2/customers/Nzc3MDAwMDAwMA=="       }     }   ],   "meta": {     "pageCount": 1,     "totalCount": 1   } }

Как видим, в ответе совсем нет информации о товарах и адресе доставки. Поэтому придется запрашивать еще один метод на получение товаров — GET https://kaspi.kz/shop/api/v2/orders/{kaspi_order_id}/entries (https://guide.kaspi.kz/partner/ru/shop/api/orders/q3203)

{   "data": [     {       "type": "orderentries",       "id": "MTQwMjYzNjcwIyMw",       "attributes": {         "quantity": 1,         "totalPrice": 1390.0,         "entryNumber": 0,         "deliveryCost": 0.0,         "basePrice": 1390.0       },       "relationships": {         "product": {           "links": {             "self": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMw/relationships/product",             "related": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMw/product"           },           "data": {             "type": "masterproducts",             "id": "MjYwMDExMTQ="           }         },         "deliveryPointOfService": {           "links": {             "self": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMw/relationships/deliveryPointOfService",             "related": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMw/deliveryPointOfService"           },           "data": {             "type": "pointofservices",             "id": "TUhvbWVWaWRlb19BQVIxODY="           }         }       },       "links": {         "self": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMw"       }     },     {       "type": "orderentries",       "id": "MTQwMjYzNjcwIyMx",       "attributes": {         "quantity": 2,         "totalPrice": 2690.0,         "entryNumber": 1,         "deliveryCost": 0.0,         "basePrice": 1345.0       },       "relationships": {         "product": {           "links": {             "self": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMx/relationships/product",             "related": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMx/product"           },           "data": {             "type": "masterproducts",             "id": "MTAwMDIwNzM4"           }         },         "deliveryPointOfService": {           "links": {             "self": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMx/relationships/deliveryPointOfService",             "related": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMx/deliveryPointOfService"           },           "data": {             "type": "pointofservices",             "id": "TUhvbWVWaWRlb19XTVI="           }         }       },       "links": {         "self": "https://kaspi.kz/shop/api/v2/orderentries/MTQwMjYzNjcwIyMx"       }     }   ],   "included": [] }

Теперь данные по товарам в заказе есть, но есть четвертый нюанс. В пакете для CRM нам нужно передавать артикул товаров и id в БД на сайте. Эмпирическим путем выяснили, что ни один из методов Kaspi API не возвращает артикул товара (сейчас этот момент Kaspi уже поправили). Ладно, но мы же можем как-то связать наши артикулы с внутренними кодами товаров Kaspi? Конечно. Осталось понять, по какому полю.

У товаров на маркетплейсе есть две подходящие для этого характеристики: id и числовой код товара (назовем его kaspi_product_code). Идентификатор можно получить, используя запросы, а kaspi_product_code можно увидеть на самом сайте после того как завели карточку товара в ЛК.

Поэтому менеджеры, которые добавляли товары на маркетплейс, сразу готовили нам сводную таблицу SKU-kaspiProductCode, под которую мы сделали отдельную таблицу kaspi_products. Но числовых кодов в ответе на запрос получения товаров мы не видим. Чтобы их получить, отправляем еще по одному запросу на каждый товар в заказе: GET https://kaspi.kz/shop/api/v2/orderentries/{kaspi_subitem_id}/product, где kaspi_subitem_id — это строковый идентификатор товара в заказе (https://guide.kaspi.kz/partner/ru/shop/api/orders/q3207)

А что там с доставкой? Поскольку Kaspi-заказы доставляла только одна ТК, то проблем с ее описанием в пакете не возникало. Но для определения адреса доставки приходится отправлять еще один запрос — GET https://kaspi.kz/shop/api/v2/orders?filter[orders][code]=ordercode, где ordercode — это числовой код заказа (https://guide.kaspi.kz/partner/ru/shop/api/orders/q3202).

Итого на один заказ, в котором один товар, получается 4 запроса. Если товаров больше — то и запросов будет больше. Логично возникает вопрос — а что там с лимитами на запросы к Kaspi API? Задав вопрос получили интересный ответ: 100 запросов в час.

Переспросили на всякий случай — нам ответили, что ошибки нет, 100 в час. В будущем этот момент Kaspi поправили, лимит стал 100 запросов в секунду.

Модель заказа Kaspi

Здесь стоит немного остановиться и добавить небольшое описание модели заказа в БД на сайте. Итоговая версия следующая:

id
date_created
date_updated
type — тип заказа (KASPI_DELIVERY, DELIVERY)
id_kaspi — строковый id заказа в Kaspi
code_kaspi — числовой код заказа в Kaspi
id_crm — строковый идентификатор заказа в CRM (не uuid)
status_kaspi — статус заказа в Kaspi
status_crm — статус заказа в CRM
receipt — ссылка на чек
waybill — ссылка на накладную
order_data — сериализованный ответ на запрос получения заказов
delivery_data — сериализованный ответ на запрос получения доставки
products_data — сериализованный ответ на запрос получения товаров
products_codes — сериализованный массив числовых кодов товаров

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

Обновление заказов на основе пакетов CRM

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

С маркетплейсом на этом этапе мы общаемся в двух случаях: подтверждение заказа (установка статуса ACCEPTED_BY_MERCHANT) и отмена заказа (запрос https://guide.kaspi.kz/partner/ru/shop/api/orders/q3213).

Закрытие заказов

«Мы практически дошли до конца и, кажется, можем полностью протестировать процесс!», — говорили мы на дейликах тогда.
«Но есть еще пятый нюанс», — говорю я сейчас.

Проблема доставки заказов силами партнерской транспортной компании (ТК), а не самого маркетплейса заключается в том, что факт доставки нужно подтвердить.

У Kaspi для таких случаев есть подтверждение через смс. Схема следующая:

ТК доставляет заказ клиенту.
Нам нужно как-то связаться с клиентом и получить от него смс с кодом, который имеет ограниченный срок активности.
С помощью данного кода закрываем заказ на стороне Kaspi.

ТК у нас партнерская, поэтому напрямую интегрировать курьеров в наши системы мы не можем. Но у нас есть Контактный центр (КЦ). Его менеджеры общаются с клиентом и сопровождают покупку. Так что в теории они могут звонить, чтобы подтвердить и закрыть заказ. Данную реализацию логично было бы разместить в CRM, но их команда в тот момент была нарасхват, поэтому мы реализовали это на стороне сайта.

Когда статус заказа в CRM — «Завершен», а в Kaspi — еще нет, выводим кнопку «Начать закрытие заказа». По кнопке срабатывает триггер для отправки смс. Смс отправляем через Kaspi API. Менеджер КЦ вводит код от клиента в появившееся поле, и мы успешно закрываем заказ. После этого генерируем чек и отправляем его клиенту.

Минус такого процесса — зависимость от смс-провайдера Kaspi.

Переход на доставку маркетплейса

В скором времени был инициирован переход на доставку средствами маркетплейса. Главное преимущество такой доставки в том, что заказ закрывается автоматически на стороне Kaspi (они сами его доставляют). Поэтому табличка для КЦ теперь используется в качестве быстрого доступа «а что там с заказами».

В связи с новым порядком доставки в процессах произошли изменения:

Type в заказе теперь KASPI_DELIVERY (но осталась поддержка и доставки силами нашей ТК).
После подтверждения заказа нужно отправить еще один запрос на сборку заказа (изменение статуса на ASSEMBLE). После того как заказ в Kaspi оказался в этом статусе, автоматически формируется накладная, доступная по ссылке. Эту ссылку мы передаем в CRM отдельным пакетом, чтобы с их стороны она отправилась на склад. Накладная представляет собой этикетку на упакованном товаре, по которой сотрудники Kaspi понимают, что это за заказ и сколько места он займет в их транспорте.
Поскольку ручное закрытие заказа больше нам не требуется, чек генерируем в момент получения от CRM финального статуса заказа

Отмененные клиентами заказы

Дополнительный кейс: заказ в работе, а клиент отменяет заказ в маркетплейсе. По хорошему, мониторинг заказов должен быть реализован на стороне CRM (это мастер система), либо с использованием сайта в качестве адаптера. Но тогда нужно было бы реализовывать дополнительный функционал для обработки новых пакетов на стороне CRM, а свободных ресурсов у их команды не было.

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

One more nuance

Период распродаж В Kaspi называется просто «Жұма». В переводе на русский тоже пятница. Такие распродажи проходят три раза в год: в феврале, в июле и в ноябре. Во время последней Жумы Kaspi API не очень хорошо справлялся и приходилось увеличивать таймаут ответа аж до 20 секунд.

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

Всем рахмет!

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