Интеграция с Monomarket: подготовка фидов, API заказов и прохождение валидации

Команда CiFrame сопровождала подключение клиента к Monomarket. Проект включал не только техническую интеграцию API, но и полный цикл подготовки к запуску на маркетплейсе: формирование контент-фида, подготовку фида офферов, реализацию методов для обработки заказов, прохождение API-валидации, исправление замечаний по структуре данных и координацию договорного процесса.

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

Клиент и задача

Платформа: Monomarket
Подрядчик: CiFrame
Тип работ: интеграция маркетплейса через фиды и API

Что нужно было реализовать

В рамках проекта требовалось:

• подготовить контент-фид товаров;
• собрать и передать фид офферов с ценами, остатками и условиями доставки;
• реализовать API для создания и обработки заказов;
• пройти валидацию Monomarket по базовым бизнес-сценариям;
• согласовать договорную, организационную и финансовую модель работы.

С какими сложностями столкнулся проект

1. Контент-фид не прошел проверку с первой попытки

После передачи XML-фида на проверку команда получила критические замечания: в фиде были обнаружены дубли и русскоязычные значения. В процессе уточнения выяснилось, что система Monomarket считает дублями не похожие товары и не совпадения по артикулу, а именно дубли штрихкодов.

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

Чтобы упростить запуск, на первом этапе было решено сузить ассортимент в фиде и оставить только наиболее релевантные товарные группы. Такой подход позволил быстрее перейти к технической части интеграции.

2. Часть “необязательных” полей оказалась фактически критичной

Во время проверки фида офферов платформа вернула дополнительные замечания. В частности, отсутствовали поля:

• warranty_period
• max_pay_in_parts
• days_to_dispatch

Отдельно был уточнен формат передачи доставки: методы нужно было передавать отдельными объектами, а не одной строкой через запятую.

Это типичная ситуация для интеграций с маркетплейсами: формально поле может выглядеть второстепенным, но фактически без него фид или API-проверка не проходят.

3. API-валидация выявила не только технические, но и процессные расхождения

После подготовки endpoint для заказов команда CiFrame открыла тестовую точку приема запросов и включила расширенное логирование, чтобы видеть, как именно Monomarket обращается к API.

Уже на первых этапах проверки возникли вопросы по:

• HTTP status code;
• формату JSON-ответов;
• сценарию обработки несуществующих товаров;
• отменам заказов;
• повторным обращениям по уже созданным заказам.

Особенно важным оказался тот факт, что Monomarket проверял не только стандартный сценарий создания заказа, но и негативные кейсы. Например, если в заказе передается товар, которого нет в фиде, система ожидала ответ со статусом 409 и кодом ITEM_NOT_FOUND. Также были уточнены ожидания по 201 для нового заказа и 200 для повторного запроса по уже существующему заказу.

Именно на таких деталях интеграции часто ломаются, если ориентироваться только на документацию без реального тестирования.

4. Нужно было разобраться с логикой дальнейших GET-запросов

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

• статус заказа;
• номер ТТН.

Это было критично для понимания того, как строить дальнейший обмен: какие данные возвращать, как обновлять статусы и по какому принципу Monomarket инициирует эти запросы.

Что сделала команда CiFrame

Проанализировала требования и разложила интеграцию по этапам

На первом этапе команда CiFrame разбила проект на отдельные блоки:

• контент-фид;
• фид офферов;
• API-методы;
• статусы и ТТН;
• обработка отмен;
• валидация;
• договорный и организационный блок.

Это позволило не смешивать все в один поток и двигаться по проекту последовательно.

Подготовила и доработала контент-фид

После получения первого отчета по фиду были уточнены правила по:

• дублирующимся штрихкодам;
• ролям полей id, code, vendor_code, barcode;
• русскоязычным значениям;
• наличию фотографий у товаров.

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

Собрала тестовый фид офферов и адаптировала его под требования платформы

CiFrame подготовил и передал тестовый JSON-фид офферов. После обратной связи от платформы в него были добавлены отсутствующие параметры, а формат доставки был приведен к ожидаемому виду.

В результате фид офферов удалось довести до корректного состояния для дальнейшей работы.

Реализовала API-методы и прошла поэтапную валидацию

Команда CiFrame реализовала endpoint для приема заказов и организовала поэтапное тестирование по реальным сценариям.

В процессе пришлось:

• дорабатывать логирование;
• уточнять структуру ответов;
• проверять статусы и сценарии повторных вызовов;
• разбирать отрицательные бизнес-кейсы;
• синхронизировать поведение методов с фактическими ожиданиями Monomarket.

По мере тестирования количество ошибок снижалось, а затем API прошло успешную валидацию.

Результат

На этом этапе команда CiFrame помогла клиенту:

• подготовить и передать контент-фид;
• выявить реальную причину дублей и сфокусировать исправления на штрихкодах;
• адаптировать стартовый ассортимент для первого запуска;
• подготовить и доработать фид офферов;
• реализовать API для обработки заказов;
• пройти успешную API-валидацию;
• согласовать логику работы со статусами и ТТН.

Фактически был создан полноценный технический фундамент для запуска продавца на Monomarket.

Что показывает этот кейс

Этот проект хорошо иллюстрирует простую вещь: интеграция с маркетплейсом почти никогда не сводится к задаче “написать API по документации”.

На практике это всегда комбинация нескольких параллельных потоков:

• техническая реализация;
• очистка и нормализация товарных данных;
• согласование бизнес-логики;
• договорная и финансовая подготовка.

Именно поэтому в таких проектах важен не просто разработчик, а интегратор, который способен держать в голове весь контур сразу. В этом кейсе CiFrame выступал именно в такой роли: не только реализовывал методы, но и прояснял спорные моменты, уточнял реальные сценарии платформы и доводил интеграцию до рабочего состояния.

Нужна интеграция с маркетплейсом?

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