Власна інтеграція замовлень через 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. Створіть персональний токен доступу#
- У Mergado Editor натисніть на свій профіль у правому верхньому куті та відкрийте API and Access.
- Натисніть + Create token, дайте токену назву (наприклад «Інтеграція замовлень до ERP») і встановіть термін його дії.
- У дозволах у групі E-shop поставте позначку Read e-shop data. API Mergado Marketplaces не потребує інших дозволів.
- Створіть токен, скопіюйте його та збережіть у надійному місці. Після закриття сторінки він більше не відображатиметься.
Детальну інструкцію ви знайдете у статті Персональний токен доступу (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 у документації#
- Відкрийте документацію API Mergado Marketplaces.
- Натисніть Authorize і введіть свій персональний токен доступу.
- Виберіть, наприклад, ендпоінт для переліку замовлень, введіть ID інтернет-магазину і натисніть Try it out, а потім Execute.
Документація покаже вам реальну відповідь із даними ваших замовлень і точну адресу запиту, яку розробник може використати безпосередньо.
4. Підключіть свою систему#
Усі виклики проходять через Mergado API за адресою https://api.mergado.com/apps/ordelogyproducts/proxy. Токен надсилається в заголовку Authorization: Bearer <ваш токен>. Конкретні ендпоінти та параметри розробник знайде в документації.
Рекомендований порядок синхронізації замовлень#
Для регулярного отримання замовлень до вашої системи рекомендуємо такий порядок:
- Завантажуйте зміни з регулярними інтервалами. Під час переліку замовлень використовуйте параметр
updated_sinceіз часом останнього завантаження. Ви отримаєте нові замовлення та ті, що змінилися відтоді: наприклад, статус, дані, помилка синхронізації або завантажений рахунок-фактура. - Після імпорту позначайте замовлення. Збережіть ID, який замовлення має у вашій системі. Параметром
imported=falseви отримаєте лише замовлення, які ще не імпортовані. - Відправляйте зміни назад. Коли ви відправляєте замовлення у своїй системі, надішліть через 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.