Marketplace Catalog Sync

• Создание коннектора продавца, которому необходимо передавать новые SKU на маркетплейс VTEX и управлять жизненным циклом предложений (отправка → ожидание → одобрение/отклонение).
• Реализация потока Change Notification для определения того, существует ли SKU в маркетплейсе (200 OK) или требуется новое предложение (404 Not Found).
• Синхронизация изменений цен и остатков через эндпоинты /notificator/{sellerId}/changenotification/{sellerSkuId}/price и /inventory.
• Реализация эндпоинта симуляции выполнения заказа на стороне продавца (POST /pvt/orderForms/simulation), который должен отвечать в течение 2,5 секунды.

• Вы выполняете операции каталога на стороне маркетплейса, такие как прямые записи POST /api/catalog/pvt/product или POST /api/catalog/pvt/stockkeepingunit — это не потоки seller-connector.
• Вам нужна логика выполнения заказов или обработки счетов (см. навык marketplace-fulfillment).
• Вам нужны паттерны ограничения частоты запросов в изоляции, независимо от потоков уведомлений каталога (см. навык marketplace-rate-limiting).

Коннекторы продавцов должны использовать POST .../changenotification/{sellerId}/{sellerSkuId} — а не односегментный маршрут changenotification/{skuId}, который ожидает идентификатор SKU VTEX маркетплейса. Этот навык документирует различие между ними, объясняет, почему официальная документация иногда смешивает эти два маршрута, и предоставляет конкретные примеры на TypeScript для обоих путей ответа: 200 (обновление) и 404 (новое предложение).

Новые SKU должны проходить через процесс предложения/утверждения с помощью PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — прямые запросы на запись в Catalog API запрещены для внешних продавцов и возвращают ошибку 403 Forbidden. Навык выполняет проверку статуса перед любым обновлением предложения, поскольку предложения можно изменять только в состоянии Pending; утверждённые или отклонённые предложения изменить невозможно.

Обновления цен и остатков отправляются через отдельные эндпоинты POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price и .../inventory, где сегмент пути — это SKU ID продавца (а не SKU ID VTEX на маркетплейсе). После получения этих уведомлений маркетплейс обращается к эндпоинту симуляции выполнения заказа продавца для получения актуальных данных.

Маркетплейс вызывает эндпоинт продавца POST /pvt/orderForms/simulation после каждого уведомления об изменении цены или остатков. VTEX ожидает ответа максимум 2,5 секунды; при превышении этого лимита товар помечается как недоступный в витрине. Данный навык предоставляет паттерн реализации с приоритетом кэша (in-memory или Redis), благодаря которому эндпоинт отвечает менее чем за 50 мс.

Отправка массовых запросов Change Notification без ограничения частоты вызывает ответы 429, которые блокируют доступ продавца ко всему API. Этот навык обеспечивает цикл уведомлений с пакетной обработкой и контролем параллелизма, включая задержки между пакетами, разбор заголовка retry-after и экспоненциальную выдержку при ошибках 429.

Маршруты системы каталога (например, changenotification) используют имя хоста магазина ({account}.vtexcommercestable.com.br), тогда как маршруты предложений SKU используют https://api.vtex.com/{accountName}. Оба интерфейса выполняют аутентификацию с использованием одних и тех же заголовков X-VTEX-API-AppKey и X-VTEX-API-AppToken. Навык предоставляет типизированный SellerConnectorConfig и фабрику клиентов Axios, охватывающую оба базовых URL.

Продавец впервые подключается к маркетплейсу VTEX и должен зарегистрировать весь свой каталог SKU. Интеграция вызывает changenotification/{sellerId}/{sellerSkuId} для каждого SKU; каждый ответ 404 инициирует запрос PUT SKU Suggestion, помещая каждый SKU в очередь маркетплейса на проверку и ожидание подтверждения оператором.

Складская система продавца генерирует события изменения цен или остатков. Коннектор отправляет пакетные уведомления о ценах и остатках через эндпоинты /notificator/, а эндпоинт симуляции фулфилмента продавца — опирающийся на предварительно прогретый кэш — отвечает на запросы маркетплейса в рамках дедлайна 2,5 секунды.

Оператору необходимо обновить данные о продукте в предложении, которое было отправлено, но ещё не рассмотрено. Интеграция сначала вызывает GET /suggestions/{sellerId}/{sellerSkuId}, чтобы убедиться, что предложение всё ещё находится в состоянии Pending, затем выполняет запрос PUT с исправленными данными. Предложения, которые уже были одобрены или отклонены, пропускаются с выводом предупреждения.

После миграции данных о продуктах сотни артикулов (SKU) требуют повторного уведомления. Интеграция использует паттерн пакетной отправки уведомлений — обрабатывая артикулы группами по пять с задержкой 200 мс между пакетами и логикой повторных попыток с учётом ошибки 429 — для повторного уведомления маркетплейса без срабатывания блокировок по лимиту запросов.