Інтеграція з Monomarket: фіди, API замовлень, валідація

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

Цей кейс добре показує реальність marketplace-інтеграцій: навіть коли документація формально є, на практиці виникають питання щодо обов’язковості полів, логіки статусів, трактування помилок, дублювання ідентифікаторів і формату контентних даних. Саме такі вузли зазвичай і вирішують, чи інтеграція піде в прод, чи зависне між “майже готово” і “ще пару правок”.

Клієнт і завдання

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

Що потрібно було реалізувати

У рамках проєкту потрібно було:

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

З якими викликами зіткнувся проєкт

1. Контентний фід не пройшов перевірку з першої спроби

Після передачі XML-фіда на перевірку команда отримала критичні зауваження: у фіді були дублі і російськомовні значення. У процесі уточнення з’ясувалося, що система Monomarket вважає дублями не схожі товари чи повтори за артикулом, а саме дублікати штрихкодів. Це важливий нюанс, бо без такого уточнення легко почати виправляти не ті поля.

Щоб спростити перший етап запуску, було вирішено тимчасово звузити асортимент у фіді до більш релевантних позицій, залишивши на старті лише окремі товарні групи. Це зменшило шум і дозволило швидше перейти до тестування інтеграції. 

2. Частина “необов’язкових” полів виявилася фактично критичною

Під час перевірки фіда офферів Monomarket повернув додаткові зауваження. Зокрема, бракувало полів:

• warranty_period
• max_pay_in_parts
• days_to_dispatch

Окремо був уточнений і формат доставки: методи потрібно було передавати окремими об’єктами, а не одним рядком через кому. Це типовий сюжет для marketplace-інтеграцій: у документації поле може виглядати другорядним, але в реальному процесі без нього перевірка не проходить.

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

Після підготовки endpoint для замовлень команда CiFrame відкрила тестову точку прийому і ввімкнула розширене логування, щоб бачити, як саме Monomarket звертається до API. Уже на перших перевірках виявилися проблеми з HTTP status code, форматом JSON-відповідей, сценаріями обробки неіснуючих товарів, скасуваннями замовлень і повторними викликами на вже створені замовлення.

Важливим моментом стало і те, що Monomarket тестував не лише “щасливий шлях”, а й негативні сценарії, наприклад створення замовлення з товаром, якого немає у фіді. У такому випадку очікувалась відповідь зі статусом 409 і кодом ITEM_NOT_FOUND. Крім того, по мірі тестів уточнювались очікування щодо кодів 201 для нового замовлення та 200 для повторного звернення по вже існуючому. Саме на таких деталях і сиплються інтеграції, якщо розробник читає документацію занадто буквально.

4. Потрібно було розібратися з логікою подальших GET-запитів

Окремий пласт роботи стосувався не тільки прийому замовлень, а й подальшої синхронізації статусів. У переписці було уточнено, що після створення замовлення платформа далі регулярно звертається до API продавця, щоб отримувати статус замовлення і ТТН. Інтервал опитування стартує приблизно з 5 хвилин, а тригерами є створення замовлення клієнтом і подальше очікування статусу та номера відправлення. Це було критично для розуміння, як правильно будувати обмін і що саме повертати в GET-методах. 

Що зробила команда CiFrame

Проаналізувала вимоги та побудувала карту інтеграції

На першому етапі команда CiFrame розклала інтеграцію на окремі блоки: контент, оффери, API-методи, статуси, скасування, логіку тестування і договірну частину. Це дозволило не змішувати все в один потік і рухатись поетапно.

Підготувала і доопрацювала контентний фід

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

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

У подальшій комунікації Monomarket окремо пояснив значення цих полів: id мав слугувати ідентифікатором товару, code використовувався для прив’язки оффера, vendor_code був кодом товару від виробника, а barcode залишався обов’язковим полем. Також пізніше з’явилось додаткове зауваження по відсутніх фото.

Зібрала тестовий фід офферів і адаптувала його під вимоги майданчика

CiFrame передав тестовий JSON-фід офферів на перевірку, після чого до структури були додані відсутні важливі параметри, а формат доставки був приведений до очікуваного вигляду. Згодом Monomarket підтвердив, що фід офферів уже виправлений.

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

Команда CiFrame підготувала endpoint для замовлень і організувала поетапне тестування по реальних сценаріях. У процесі довелося кілька разів перезапускати перевірки, коригувати логіку відповідей, розбирати статус-коди, структуру JSON і негативні бізнес-кейси. Прогрес добре видно по переписці: кількість помилок у валідації поступово зменшувалась, після чого Monomarket підтвердив, що API успішно провалідовано. 

Результат

На цьому етапі CiFrame допоміг клієнту пройти найскладнішу частину підключення до Monomarket:

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

Що показує цей кейс

Цей проєкт добре ілюструє просту річ: інтеграція з маркетплейсом майже ніколи не є просто “зробити API по документації”. Насправді це комбінація з чотирьох паралельних потоків:

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

Саме тому в подібних задачах важливий не просто розробник, а інтегратор, який здатен тримати весь контур одразу. У цьому кейсі CiFrame виступав саме в такій ролі: не лише писав методи, а й розбирав конфлікти в логіці, уточнював сценарії, підсвічував неочевидні залежності й доводив інтеграцію до робочого стану. Весь цей ланцюг підтверджується перепискою по файлу з повною історією комунікації.

Потрібна інтеграція з маркетплейсом?

Якщо вам потрібно підключити магазин до маркетплейсу, реалізувати API замовлень, підготувати фіди або пройти технічну валідацію партнера, CiFrame допоможе пройти цей шлях без хаотичних ітерацій і затяжних “ще однієї правки”.