Власна інтеграція замовлень через API Mergado Marketplaces#

Mergado Marketplaces має готові інтеграції замовлень для таких систем, як POHODA, Shoptet Premium, WooCommerce, UNAS або Upgates. Якщо ви обробляєте замовлення в іншій системі — наприклад у власній ERP-системі, складській програмі або внутрішньому застосунку — ви можете підключити їх самостійно через API Mergado Marketplaces. Для цього потрібен розробник, який запрограмує інтеграцію на боці вашої системи.

Через API ви можете:

  • завантажувати замовлення з усіх маркетплейсів, підключених у Mergado Marketplaces (Allegro, Kaufland, Amazon), включно з усіма даними, які містить CSV-експорт замовлень: покупець, платіжна та доставна адреса, оплата, доставка, позиції замовлення, документи та нотатки,
  • позначати замовлення як імпортовані, записуючи їхній ID із вашої системи — при наступному завантаженні ви отримаєте лише нові замовлення,
  • змінювати статус замовлення разом із номером відправлення та перевізником. Зміна надсилається безпосередньо на Allegro або Kaufland,
  • завантажувати рахунок-фактуру до замовлення на Allegro або Kaufland.

Повна технічна документація доступна в документації API Mergado Marketplaces. У ній ви знайдете всі ендпоінти, їхні параметри та формат відповідей. Запити можна випробувати безпосередньо на даних вашого інтернет-магазину.

📝 Корисно знати:

  • Документація API та повідомлення про помилки — англійською мовою.
  • API призначений для розробників. Якщо ви хочете підключити замовлення без програмування, перевірте, чи є ваша система серед готових інтеграцій у Mergado Marketplaces.

Що вам знадобиться#

  • Активне розширення Mergado Marketplaces з підключеним принаймні одним маркетплейсом.
  • Персональний токен доступу (PAT) з вашого облікового запису Mergado з дозволом Read e-shop data.
  • ID інтернет-магазину в Mergado.
  • Розробник, який запрограмує інтеграцію у вашій системі.

⚠️ Використовуйте або API, або готову інтеграцію з e-commerce платформою — не обидва варіанти одночасно. Якщо у Mergado Marketplaces активована інтеграція замовлень з e-commerce платформою (наприклад Shoptet Premium, Upgates або WooCommerce), і ви одночасно обробляєте ті самі замовлення через API, обидві системи можуть перезаписувати статуси замовлень одна одній.

Як налаштувати інтеграцію#

1. Створіть персональний токен доступу#

  1. У Mergado Editor натисніть на свій профіль у правому верхньому куті та відкрийте API and Access.
  2. Натисніть + Create token, дайте токену назву (наприклад «Інтеграція замовлень до ERP») і встановіть термін його дії.
  3. У дозволах у групі E-shop поставте позначку Read e-shop data. API Mergado Marketplaces не потребує інших дозволів.
  4. Створіть токен, скопіюйте його та збережіть у надійному місці. Після закриття сторінки він більше не відображатиметься.

Детальну інструкцію ви знайдете у статті Персональний токен доступу (PAT).

⚠️ Не плутайте Read e-shop data (група E-shop) із дозволом Read user’s e-shops (група User). API Mergado Marketplaces потребує першого.

Токен має доступ до тих самих інтернет-магазинів, що й ваш обліковий запис. Для читання замовлень достатньо доступу до читання інтернет-магазину. Для зміни статусу замовлення, завантаження рахунку-фактури або запису власного ID замовлення обліковий запис має мати доступ до запису.

2. Дізнайтеся ID інтернет-магазину#

Кожен виклик API містить числовий ID інтернет-магазину в Mergado. Найпростіше це зробити: у налаштуваннях API and Access увімкніть відображення внутрішніх ID. ID інтернет-магазину відображатиметься у дужках поруч із його назвою. Порядок дій описано у статті Відображення внутрішніх ID сутностей.

3. Випробуйте API у документації#

  1. Відкрийте документацію API Mergado Marketplaces.
  2. Натисніть Authorize і введіть свій персональний токен доступу.
  3. Виберіть, наприклад, ендпоінт для переліку замовлень, введіть ID інтернет-магазину і натисніть Try it out, а потім Execute.

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

4. Підключіть свою систему#

Усі виклики проходять через Mergado API за адресою https://api.mergado.com/apps/ordelogyproducts/proxy. Токен надсилається в заголовку Authorization: Bearer <ваш токен>. Конкретні ендпоінти та параметри розробник знайде в документації.

Рекомендований порядок синхронізації замовлень#

Для регулярного отримання замовлень до вашої системи рекомендуємо такий порядок:

  1. Завантажуйте зміни з регулярними інтервалами. Під час переліку замовлень використовуйте параметр updated_since із часом останнього завантаження. Ви отримаєте нові замовлення та ті, що змінилися відтоді: наприклад, статус, дані, помилка синхронізації або завантажений рахунок-фактура.
  2. Після імпорту позначайте замовлення. Збережіть ID, який замовлення має у вашій системі. Параметром imported=false ви отримаєте лише замовлення, які ще не імпортовані.
  3. Відправляйте зміни назад. Коли ви відправляєте замовлення у своїй системі, надішліть через API статус SENT із номером відправлення. Зміна записується безпосередньо на маркетплейс. Таким само чином можна завантажити рахунок-фактуру.

Час без зазначеного часового поясу API інтерпретує як центральноєвропейський час (Europe/Prague). У такому самому часовому поясі вказано весь час у відповідях.

Статуси замовлень#

Mergado Marketplaces перетворює статуси окремих маркетплейсів на уніфіковані статуси. В API вони відображаються так:

Статус в API Статус у Mergado Marketplaces
OPEN відкрито
READY не відправлено
PROCESSING обробляється
SENT відправлено
ONHOLD призупинено
RETURNED повернуто
CANCELLED скасовано
UNKNOWN невідомий

Через API можна встановити такі статуси:

Маркетплейс Статуси, які можна встановити
Allegro PROCESSING, SENT, CANCELLED, ONHOLD
Kaufland PROCESSING, SENT, CANCELLED

Для Amazon замовлення через API можна лише читати.

Статус у Mergado Marketplaces змінюється лише тоді, коли його приймає маркетплейс. Якщо маркетплейс відхиляє зміну, API повертає помилку з причиною від маркетплейсу, і помилка відображається також у замовленні в Mergado Marketplaces. Невдала зміна не повторюється автоматично. Ви можете надіслати статус, який замовлення вже має, наприклад, щоб додати номер відправлення до вже відправленого замовлення.

Рахунки-фактури#

До замовлення на Allegro або Kaufland через API можна завантажити рахунок-фактуру у форматі PDF розміром не більше 5 МБ разом із номером рахунку-фактури. Результат завантаження відображається в історії замовлення в Mergado Marketplaces.

Ліміти#

  • З однієї IP-адреси можна надіслати не більше 60 запитів за хвилину.
  • Один виклик повертає не більше 1 000 замовлень. Наступні замовлення завантажуються посторінково.

FAQ#

Чи потрібне для API якесь спеціальне підключення в Mergado Marketplaces?#

Ні. Достатньо персонального токена доступу та ID інтернет-магазину. У розділі Connections лише перевірте, що для маркетплейсів увімкнена синхронізація замовлень. Нічого додаткового для API налаштовувати не потрібно.

API повертає помилку 403 «Missing required scope: shop.read». Що робити?#

Токен не має дозволу Read e-shop data. Створіть новий токен і поставте позначку для цього дозволу в групі E-shop.

API повертає помилку 403 «Access denied for this eshop». Що робити?#

Ваш обліковий запис не має потрібного доступу до інтернет-магазину, або ID інтернет-магазину не збігається. Перевірте ID інтернет-магазину та доступ до нього. Для зміни статусу, завантаження рахунку-фактури та запису ID замовлення потрібен доступ до запису. Щойно наданий доступ може набути чинності до 5 хвилин.

API повертає помилку 401. Що робити?#

Запит не містить токена, або токен недійсний. Перевірте, що ви надсилаєте повний токен у заголовку Authorization і що термін його дії не минув та його не відкликано.

Чому при завантаженні за датою мені бракує змін статусів старих замовлень?#

Параметри date_from і date_to фільтрують за датою, коли покупець створив замовлення. Зміни статусів старих замовлень, наприклад скасування, так не відстежуються. Для регулярної синхронізації використовуйте параметр updated_since.

Чи можна використовувати API одночасно з інтеграцією замовлень з e-commerce платформою?#

Не рекомендуємо. Якщо замовлення одночасно обробляє інтеграція з платформою (наприклад Shoptet Premium або Upgates) і ваша система через API, вони можуть перезаписувати статуси замовлень одна одній. Для передачі замовлень використовуйте або API, або готову інтеграцію.

Чи можна через API працювати з кількома інтернет-магазинами?#

Так. Токен працює для всіх інтернет-магазинів, до яких ваш обліковий запис у Mergado має доступ. У кожному виклику ви вказуєте ID інтернет-магазину, з яким хочете працювати.

Допоможете нам з інтеграцією?#

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

Чи була ця стаття корисною?