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

Что соединяет интеграция

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

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

Контур устойчивого обмена

Коннектор должен уметь продолжить работу после тайм-аута, лимита и изменения внешнего контракта.

• Адаптер каждой площадки преобразует внешнюю модель в общую внутреннюю, не распространяя её особенности по всей системе.
• Очередь хранит операцию, версию объекта, попытки, следующий запуск и корреляционный идентификатор.
• Webhook считается сигналом к проверке состояния, а не безусловной истиной, если событие может прийти повторно или вне порядка.
• Сверка сравнивает фактическое состояние площадки с master-системой и формирует исправление или задачу оператору.
• Секреты разделены по кабинетам и окружениям, регулярно меняются, а права ограничены нужными методами.

Карта данных и ответственности

До разработки зафиксируйте систему-источник для каждого объекта и допустимую задержку обновления.

• Составьте перечень площадок, кабинетов, юридических лиц, складов и схем исполнения вместе с владельцами доступов.
• Определите master-систему для товара, контента, цены, акции, остатка, заказа, отгрузки и возврата.
• Сопоставьте SKU, GTIN, артикулы площадок, варианты и комплекты; подготовьте правило объединения и запрет неоднозначных соответствий.
• Опишите частоту и SLA обмена, лимиты API, размер пакета, вебхуки, ретраи и приоритет критичных операций.
• Соберите контрольные сценарии: новый товар, изменение цены, нулевой остаток, отмена, частичный возврат и временная недоступность площадки.

Пошаговый план интеграции

Начинайте с одного канала и вертикального сценария от товара до закрытого заказа.

• Нормализуйте каталог и выделите обязательные атрибуты до разработки коннектора; ошибки качества не должны маскироваться преобразованием API.
• Создайте реестр соответствий категорий, характеристик, идентификаторов и правил публикации с версией и владельцем.
• Реализуйте исходящие операции через очередь с устойчивым ключом, ограничением частоты, повтором и отдельным хранилищем окончательных ошибок.
• Принимайте заказы и статусы как события, сохраняйте исходный payload и переводите их в внутреннюю модель с контролем допустимых переходов.
• Настройте резервирование остатка и компенсацию при отмене так, чтобы параллельные каналы не продавали одну единицу дважды.
• Добавьте регулярную сверку товаров, цен, остатков, заказов и финансовых итогов независимо от успешных ответов API.
• Проведите пилот на ограниченном ассортименте и складе, отработайте возвраты и отключение канала, затем масштабируйте площадки.

Как контролировать интеграцию

Панель должна показывать свежесть данных и бизнес-расхождения, а не только доступность сервера.

• Задержка обновления цены и остатка по площадке, складу и критичности товара.
• Расхождения master-системы с опубликованным каталогом и доля непринятых атрибутов.
• Заказы без внутреннего соответствия, недопустимые переходы статусов и дубли событий.
• Очередь ретраев, окончательные ошибки, превышения лимитов и время восстановления.
• Отмены из-за отсутствия товара, просрочка обработки, возвраты и финансовая сверка.

Что приводит к расхождениям

Большинство аварий возникает из-за неопределённой ответственности и отсутствия восстановления.

• Использовать название товара как ключ и терять соответствие при переименовании или появлении варианта.
• Публиковать остаток напрямую из нескольких систем без единого правила резервирования.
• Повторять запрос после тайм-аута без проверки результата и создавать дубль отгрузки или изменения.
• Считать HTTP-успех доказательством бизнес-результата и не проводить последующую сверку.
• Запускать весь ассортимент до отработки отмен, возвратов, лимитов и временного отключения площадки.

Итог

Интеграция с маркетплейсами начинается с master-data и ответственности. Только после устойчивых идентификаторов стоит автоматизировать публикацию, остатки и заказы.

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

Карта сверки маркетплейса

• Объект — товар, цена, остаток, заказ, отгрузка или возврат.
• Ключ — внутренний и внешний идентификаторы, версия и площадка.
• Ожидание — допустимое состояние и срок обновления.
• Исправление — автоматическая компенсация, повтор или задача оператору.