Prom.ua — маркетплейс №1 в Україні й частина міжнародної родини майданчиків EVO. Якщо ви продаєте на Prom, замовлення надходять у ваш кабінет; Elbuz забирає їх напряму через API й перетворює на документи, з якими працюють ваші менеджери. Так замовлення Prom опиняються в одній черзі обробки разом із продажами з інших каналів.
Ця стаття — про підключення саме Prom. Загальний порядок для всіх систем із замовленнями описано в огляді імпорту замовлень через API; тут — особливості Prom: який ключ потрібен, що саме приходить у документ і як рядки замовлень зв'язуються з вашим каталогом. Prom через це підключення приносить замовлення; про завантаження товарів Prom — окремо (див. нижче).
Де це у програмі
У вікні імпорту створіть шаблон і оберіть тип «Prom» (EVO). Це API-джерело: файл не потрібен, підключення відбувається за токеном. Один шаблон — одне підключення до одного кабінету Prom.
1
Поле «Токен»- Поле «Токен» — сюди вставляється токен API, отриманий у кабінеті Prom.ua.
Що потрібно для підключення
Для Prom потрібне лише одне значення — Токен. Це ключ доступу до API, який ви створюєте самі в кабінеті компанії Prom. Токен — це доступ до вашого кабінету, тож зберігайте його як пароль.
Де взяти токен: крок за кроком
| Де | Що зробити |
|---|---|
| Кабінет Prom | Розділ «Налаштування» → «Управління API-токенами» → кнопка «Створити токен» |
| Там само | Задати назву (необов'язково), термін дії та права доступу за групами методів |
| Там само | Натиснути на створений токен, щоб переглянути й скопіювати його |
| Elbuz | Вікно завантаження → ваш шаблон «Prom» → картка «Підключення» → поле «Токен» |
Створювати токени може власник компанії або користувач з роллю «Адміністратор». Якщо пункту меню немає — швидше за все, у вашого користувача інша роль.
Права налаштовуються окремо для кожної групи методів: немає доступу / тільки читання / читання і запис. Для завантаження замовлень у Elbuz достатньо дати читання групі «Замовлення і повідомлення». Хоча б одна група має бути відкрита, інакше Prom не дасть зберегти токен.
Prom обмежує термін дії токена — максимум один рік (мінімум один день). Коли строк вийде, завантаження замовлень зупиниться, а в журналі з'являться помилки авторизації. Тому одразу поставте собі нагадування: перед закінченням строку продовжте токен у кабінеті (термін дії можна редагувати) або створіть новий і оновіть його в полі «Токен».
Ознаки в журналі: якщо прав бракує — Prom відповідає відмовою в доступі; якщо строк вийшов — помилкою авторизації.
Покрокова інструкція Prom з описом усіх параметрів токена: Управління API-токенами в кабінеті компанії (довідка для продавців Prom.ua).
Як підключити крок за кроком
Створіть шаблон типу «Prom». Вставте токен у картці «Підключення». Більше вмикати нічого не потрібно: у шаблона Prom немає картки «Що завантажувати» з галочками — це підключення завжди забирає замовлення й тільки їх. Збережіть і запустіть. Перше підключення забере ту історію замовлень, яку віддасть Prom, наступні прогони — замовлення, що з'явилися після останнього завантаженого. Радимо перший запуск перевірити очима: відкрийте кілька завантажених замовлень і звірте позиції, суми, покупця й статус.
Що приходить із замовленням: маппінг полів
Prom віддає одне з найповніших замовлень серед усіх джерел — ось що потрапляє в документ:
| Дані Prom | Поле документа в Elbuz |
|---|---|
| номер замовлення | Зовнішній номер (за ним замовлення впізнається повторно) |
| ім'я, по батькові, прізвище покупця | Ім'я, по батькові, прізвище (з великої літери) |
| ідентифікатор клієнта | Прив'язка контрагента до джерела |
| пошта й телефон | Пошта, телефон |
| адреса доставки | Адреса доставки |
| спосіб доставки, служба, відділення відправника й отримувача | Дані доставки |
| номер накладної | ТТН (у поле відповідної служби) |
| вартість доставки | Вартість доставки |
| сума замовлення | Сума документа |
| коментар покупця | Опис замовлення |
| джерело замовлення | Джерело |
| знижка, промокод, безкоштовна доставка за акцією | Дані акції |
| комісія CPA та ознака її повернення | Комісія майданчика |
| спосіб і статус оплати | Тип оплати, статус оплати |
| статус замовлення | Статус документа |
| дати створення й зміни | Дати замовлення на майданчику |
У рядках замовлення приходять назва, артикул, ціна, кількість, одиниця виміру, сума рядка, а також посилання на товар і його зображення на Prom.
Як позиції зв'язуються з вашим каталогом
Тут у Prom є перевага, якої немає в інших джерел замовлень. Разом із рядком замовлення Prom повертає зовнішній ідентифікатор товару — той самий, який ви передали майданчику, коли вивантажували туди каталог. А наша вивантаження записує в поле «Ідентифікатор товару» власний код товару Elbuz. Виходить замкнене коло: товар поїхав на Prom із нашим кодом — замовлення повернулося з ним же — позиція точно знайшла свою картку.
Вивантажте каталог на Prom засобами Elbuz — експортом XLSX або XML-фідом. Тоді в кожного товару на Prom стоїть наш ідентифікатор, і рядки замовлень зіставляються за ним, а не за збігом назв. Якщо ж каталог заливали на Prom вручну чи чужим інструментом, позиції шукатимуться за артикулом із назвою або лише за назвою — це працює, але менш надійно.
Prom не передає категорію товару в рядку замовлення. Тому позиція, якої немає у вашому каталозі, не губиться, але й не потрапляє в потрібну гілку: для неї створюється картка у службовій категорії з назвою «Товари - evo_market - назва вашого шаблону». У категорії вимкнено «Активність категорії» і «Вивантажувати у файл (на сайт)», а картка отримує назву, артикул, ціну, кількість, одиницю виміру, посилання на сторінку товару на Prom і фото за посиланням з Prom. Що з цією категорією можна робити далі — нижче, у розділі про службову категорію.
Тому тримайте каталог актуальним і вивантажуйте його на Prom засобами Elbuz — тоді позиції зіставляються з наявними картками, а службова категорія не заростає дублікатами. Докладніше про порядок зіставлення — в огляді імпорту замовлень через API.
Статуси і їх зіставлення
Статуси Prom Elbuz зводить до власних, і це зіставлення вбудоване в саме підключення:
| Статус у Prom | Статус документа в Elbuz |
|---|---|
| новий (очікує) | Новий |
| прийнято | Погодження |
| оплачено | Оплачено |
| доставлено | Доставлено |
| скасовано | Скасовано |
| чернетка | Чернетка |
Окремо зіставляється статус оплати: «не оплачено» стає очікуванням, «оплачено» — оплатою, «повернено» — поверненням, «виплачено продавцю» — окремим станом розрахунку з майданчиком. Тип оплати визначається за назвою способу: «Пром-оплата» відноситься до оплати через маркетплейс, «Безготівковий розрахунок» — до банківського переказу, а будь-який спосіб зі словами «Накладений платіж» — до післяплати.
У картці «Пов'язані налаштування» є кнопки ручного зіставлення статусів і видів оплати та доставки. Порядок такий: спершу спрацьовує вбудоване зіставлення з таблиць вище, а ваші ручні правила добирають лише те, для чого відповідності не знайшлося. Тобто ручна таблиця доповнює вбудовану, а не перевизначає її.
Що робить повторний прогін з уже завантаженим замовленням
Кожен запуск читає замовлення Prom наново — разом із тими, що у вас уже є. Перед записом прогін шукає для кожного прочитаного замовлення документ із таким самим номером замовлення Prom і таким самим джерелом. Знайшов документ — далі з ним нічого не робить. Створюються тільки ті замовлення, документа для яких ще немає.
Звідси головне: в уже завантаженому замовленні прогін нічого не перезаписує. Ваш статус, сума, покупець, адреса доставки, номер накладної, спосіб оплати, коментар — усе лишається таким, яким його залишив менеджер. Другої копії замовлення теж не з'являється.
Зміна статусу на Prom після завантаження до вас не доїде. Покупець скасував замовлення в кабінеті Prom, оператор Prom позначив його оплаченим — Elbuz цього не побачить: документ уже існує, і наступний прогін його пропускає. Колонка «Статус документа (сайт)» лишається з тим статусом, який стояв у момент завантаження. Про пізніші скасування й оплати дивіться в кабінеті Prom.
Картка покупця — окремий випадок. Покупця прогін шукає за поштою й телефоном, а якщо не знайшов — за відбитком «пошта + телефон», яким Elbuz помічає контрагентів із зовнішніх джерел. У знайдену картку дописуються тільки порожні пошта й телефон із замовлення. Заповнені поля не замінюються; ім'я, адреса й решта картки не оновлюються.
Картки товарів завантаження замовлень теж не оновлює: ані ціну, ані залишок, ані назву. Нова картка заводиться лише для позиції, якій не знайшлося відповідника в каталозі. Єдине, що прогін міняє в наявних картках, — сумарна кількість продажів: вона перераховується за всіма замовленнями клієнтів.
Рядок, який менеджер прибрав із уже завантаженого замовлення, може повернутися. Так буває в прогоні, де прийшло хоча б одне нове замовлення: у такому прогоні позиції дописуються до всіх документів, які він читав, і видалений рядок Prom з'являється в документі знову. Щоб позиція не поверталася, не видаляйте рядок, а поставте в ньому нульову кількість: прогін дописує лише те, чого в документі немає зовсім.
За чим видно, що прогін відпрацював
Кнопки «Перевірити підключення» у шаблоні Prom немає — вона зроблена для інших типів джерел. Тож перевірка тут одна: запустити завантаження й прочитати журнал. Журнал іде в Центр операцій, тому вікно завантаження не блокується й можна працювати далі, а поруч із журналом є кнопка «Зупинити».
| Рядок журналу | Що він означає |
|---|---|
| «Запитуємо список замовлень #1», «#2», … | номер сторінки, яку зараз забирають у Prom; скільки таких рядків — стільки сторінок і прочитано |
| «Отримано замовлень: N» | скільки замовлень Prom віддав усіма сторінками разом — і нових, і тих, що у вас уже були |
| «Всього товарів завантажено: N» | скільки нових карток товару довелося завести під позиції замовлень |
| «Всього замовлень завантажено: N» | скільки документів створено. Це і є результат прогону |
| «Оновлення значень на основі формул» | завершальний крок |
| «Завантаження даних завершено! Витрачено часу: …» | прогін закінчився, поруч — його тривалість |
Розвилка, яку варто знати наперед. Якщо рядка «Отримано замовлень» немає зовсім — Prom не віддав жодного замовлення, тобто нових із моменту минулого завантаження не з'явилося. Рядків про товари й замовлення в такому прогоні теж не буде, а завершиться він тими самими словами «Завантаження даних завершено!». Порожній і вдалий прогін у кінці виглядають однаково, тому дивіться на числа, а не на останній рядок.
Помилки прогін пише окремими рядками — «Не вказано API токен» або відповідь Prom з відмовою в авторизації (у тексті рядка буде 401 Not Authenticated). Такий рядок позначає всю операцію як помилкову в Центрі операцій, навіть якщо внизу стоїть «Завантаження даних завершено!».
Коли журнал уже закритий, слід прогону лишається у двох місцях: у списку шаблонів колонка «Останнє завантаження» показує дату останнього прогону, а під нею — скільки він тривав; кнопка «Історія запусків» у шапці шаблону відкриває всі його прогони з підсумками — «Запусків за період», «Середня тривалість», «Найдовший», «З помилками».
Про кожне нове замовлення прогін надсилає сповіщення «Нове замовлення» з номером документа, сумою, покупцем і переліком товарів. Сповіщень за один прогін надсилається не більше десяти: якщо замовлень прийшло більше, решту шукайте у списку документів.
Самі завантажені замовлення видно у списку документів за колонками джерела:
| Колонка списку документів | Що в ній для Prom |
|---|---|
| «Джерело: назва» | назва вашого шаблону Prom |
| «Джерело (код)» | код підключення — для Prom це evo_market |
| «Джерело: ID» | номер шаблону, яким завантажено документ |
| «ID документа зовнішній (рядок UUID)» і «№ документа (сайт)» | номер замовлення на Prom — той самий ключ, за яким прогін упізнає вже завантажене |
Скільки замовлень іде за прогін
Elbuz забирає замовлення сторінками по 100 штук і між сторінками тримає паузу в одну секунду. Сторінки йдуть одна за одною, доки Prom не відповість порожнім списком, тож стелі на кількість замовлень за прогін у програмі немає — прогін іде рівно стільки, скільки є замовлень.
У коді підключення записані обмеження Prom на частоту звернень з однієї IP-адреси: 100 запитів за секунду, 200 за 10 секунд і 21 600 за дві години. Одна сторінка на секунду тримає прогін далеко від цих меж.
Глибина відбору задається так:
- Перше підключення — дата в запиті не вказується взагалі. Prom віддає замовлення від найновіших і далі назад, а Elbuz гортає сторінки, доки вони не закінчаться. Тобто перший прогін тягне всю історію, яку віддає майданчик.
- Кожен наступний прогін — від початку доби, у яку створено останнє завантажене замовлення. Час при цьому відкидається навмисно, щоб не загубити замовлення, створені тієї ж доби пізніше. Ті з них, що вже лежать у вас, прогін просто пропустить.
Межу видно у формі шаблону: розділ «Розширене» показує «Завантаження замовлень починаючи з ID» і «Завантаження замовлень починаючи з дати (РРРР-ММ-ДД)». Обидва значення проставляє сам прогін після кожного вдалого завантаження.
- Значення в «Розширеному» не редагуються. Поля виглядають як звичайні, але вписане руками при збереженні шаблону не запам'ятовується: перечитати історію з довільної дати через них не вийде.
- Два завантаження одночасно за розкладом не запускаються. Якщо в момент запуску вже йде інший шаблон, у журналі з'явиться «Скасовано завантаження за розкладом, причина - завантажується інший шаблон (конфлікт обробки даних)», і цей прогін не відбудеться. Наступний за розкладом пройде як звичайно.
Якщо прогін обірвався або його зупинили
Порядок роботи тут такий, що обрив між сторінками нічого не псує. Прочитані сторінки прогін складає у два тимчасові файли й бази не чіпає взагалі, доки не дочитає всі сторінки. Тому:
- обрив під час гортання сторінок — у базі не з'явилося жодного документа, позначка «починаючи з дати» лишилася на місці. Наступний запуск починає з першої сторінки, переписуючи тимчасові файли, і читає той самий проміжок заново;
- кнопка «Зупинити» діє інакше, ніж очікують: прапорець зупинки перевіряється перед запитом кожної наступної сторінки, і те, що вже прочитано до цього моменту, все одно зберігається в базу. У журналі при цьому стоїть «Операція перервана користувачем!». Зупинка не скасовує вже прочитане, вона лише припиняє читати далі;
- обрив під час запису — у базі лишається те, що встигло записатися. Записує прогін по черзі: спершу нові картки покупців, потім нові картки товарів, потім документи, потім рядки документів і аж наприкінці — позначку «починаючи з дати». Оскільки позначка рухається останньою, повторний запуск читає той самий проміжок ще раз: документи, які встигли створитися, він упізнає за номером замовлення Prom і не задвоїть, а ті, що не встигли, створить.
Якщо завантажили не те
Скажімо, шаблон запустили не з тим токеном і в базу приїхали чужі замовлення. Усе, що створив прогін, помічене джерелом, тому шукається відбором, а не очима.
| Що прибрати | Де шукати |
|---|---|
| Документи | список документів, відбір за колонками «Джерело: назва», «Джерело (код)» або «Джерело: ID» |
| Картки товарів | базовий каталог, колонки «Джерело: код», «Джерело: назва», «Джерело: ID»; крім того, всі нові картки лежать у службовій категорії «Товари - evo_market - назва шаблону» |
| Контрагенти | довідник контрагентів, колонки «Джерело - код» і «Джерело - назва» |
Позначені документи видаляються пачкою, і це оборотна дія: перед видаленням Elbuz складає повний знімок кожного документа разом із позиціями й зв'язками в «Кошик документів». Кнопка «Скасувати» повертає всю пачку; знімки зберігаються 30 днів.
Проведені документи з пачки виключаються: масове видалення їх не чіпає. Скільки документів лишилося на місці, видно з попередження після видалення — «Проведені документи не видалено (N). Спершу скасуйте проведення».
Видалення документів не відсуває позначку «починаючи з дати» — вона лишається там, куди її поставив прогін. Тому ті самі замовлення Prom наступним прогоном уже не завантажаться: для нього вони старіші за позначку. Якщо видалили помилково, повертайте пачку з «Кошика документів», поки не минули 30 днів.
Службова категорія Prom: перенести чи видалити
Категорія «Товари - evo_market - назва шаблону» створюється не завжди, а тільки в тому прогоні, де хоча б одна позиція замовлення не знайшла картки у вашому каталозі. Вона одна на шаблон і поповнюється далі такими ж «незнайомими» позиціями.
Переносити картки звідти у своє дерево безпечно. Рядок завантаженого замовлення посилається на картку товару, а не на категорію, і власні копії назви, артикулу, ціни та кількості зберігає всередині себе. Тому після переносу картки в потрібну гілку всі раніше завантажені замовлення лишаються цілими, а нові позиції того ж товару знаходитимуть її на новому місці.
Порожню категорію після переносу можна видаляти — забирати з собою їй уже нічого.
Якщо видалити категорію разом із картками, видаляться й самі картки — усі, для яких ця категорія основна, а з ними описи, фото, характеристики й посилання. Рядки вже завантажених замовлень при цьому лишаються на місці зі своїми назвами, артикулами, цінами й кількостями, але зв'язок рядка з карткою обривається. А наступний прогін, зустрівши ту саму позицію, заведе картку заново й заново створить службову категорію. Тому спершу переносьте картки, і лише потім видаляйте категорію.
Якщо зняти «Активність» із шаблону
Стан шаблону перемикається пілюлею «Активний» / «Вимкнений» у шапці його форми; у списку шаблонів це колонка «Стан».
Вимкнений шаблон пропускає планувальник: завдання за розкладом до нього не доходить, і в загальному запуску всіх активних шаблонів він теж не бере участі. На цьому все й закінчується — токен, зіставлення статусів, розклад, уже завантажені замовлення й позначка «починаючи з дати» лишаються недоторканими. Вимкнення нічого не видаляє.
Запустити вимкнений шаблон руками з його форми або зі списку шаблонів усе одно можна: заборона стосується лише розкладу.
Коли ви ввімкнете шаблон назад, наступний прогін за розкладом почне з тієї самої позначки — від початку доби останнього завантаженого замовлення. Замовлення, які з'явилися на Prom за час паузи, для нього нові, тому вони завантажаться. А от статуси, що змінилися за паузу в уже завантажених замовленнях, не приїдуть — з тієї самої причини, що описана вище.
А як щодо товарів Prom
Це підключення приносить саме замовлення. Каталог Prom завантажується іншим шляхом — файлом у форматі маркетплейсів EVO (XLSX для prom.ua, satu.kz, deal.by) або через YML. Тобто товари й замовлення Prom розведено: асортимент ви заливаєте імпортом XLSX (EVO), а замовлення — цим API-підключенням. Це зручно: каталог зазвичай оновлюють рідше й пачками, а замовлення потрібні свіжими й часто.
Розклад, оновлення й ліміти
Prom працює поллінгом: Elbuz сам звертається за розкладом і забирає свіжі замовлення — вебхука (миттєвого сповіщення) немає. Розклад визначає, наскільки швидко нові замовлення потраплять у Elbuz; для активного магазину має сенс перевіряти часто. Розклад задають кнопкою «Налаштування розкладу» в картці «Пов'язані налаштування» самої форми шаблону. Prom обмежує частоту звернень до API, тому Elbuz забирає замовлення сторінками з паузою між ними. Межа, від якої береться наступна порція, — не номер замовлення, а дата: прогін іде від початку доби останнього завантаженого замовлення, а те, що у вас уже є, пропускається (числа й подробиці — у розділі про обсяг прогону). Кілька кабінетів Prom можна вести паралельно — під кожен свій шаблон із власним токеном і розкладом, і всі вони наповнюють одну спільну чергу замовлень у Elbuz.
Навіщо зводити замовлення Prom в Elbuz
Кабінет Prom добре показує замовлення самого Prom, але якщо каналів кілька, продажі опиняються в різних місцях. Звівши замовлення Prom в Elbuz, ви обробляєте їх в одній черзі: списання зі складу, облік покупців, єдині статуси, друк документів. Менеджеру не треба тримати окрему вкладку Prom, а історія покупок клієнта збирається у вашій базі контрагентів.
Спершу вивантажте каталог на Prom засобами Elbuz, і лише потім вмикайте завантаження замовлень. Тоді в товарів на майданчику стоїть наш ідентифікатор, і позиції замовлень зіставляються з картками точно, а не за збігом назв.
Що далі із завантаженими замовленнями
Завантажити замовлення — це початок. Далі вони живуть у Elbuz як документи «замовлення покупця», і з ними працюють як зі звичайними: підтверджують, резервують і списують товар зі складу, оформлюють доставку й друкують документи, ведуть покупця в базі контрагентів. Якщо ви тільки починаєте знайомство з системою, орієнтуйтеся на загальну карту дій — з чого почати і куди рухатися: там показано весь робочий цикл в Elbuz.
Коли Prom — не єдиний ваш канал, його замовлення сходяться в один список разом з іншими майданчиками, і менеджер обробляє їх однаково. Загальні принципи роботи із замовленнями з різних систем описано в огляді імпорту замовлень через API — Prom підпорядковується тому самому порядку, а вирізняється повнотою даних замовлення (ТТН, комісія майданчика, промокоди) і тим, що каталог у нього завантажується окремо, форматом EVO.
Типовий сценарій для продавця з України виглядає так: асортимент ви заливаєте імпортом XLSX (EVO) й тримаєте актуальним, а замовлення тягнете цим API-підключенням і обробляєте в Elbuz. Обидва потоки — товари й замовлення — сходяться в одній системі, і Prom перестає бути окремим «острівцем», який доводиться вести руками в його власному кабінеті.
Часті питання
Де взяти токен Prom?
Токен видається в кабінеті Prom, у розділі налаштувань / API. Ви вставляєте його в поле «Токен» у формі шаблону — це єдине, що потрібно для підключення.
Чому не завантажуються товари Prom?
Бо це підключення приносить лише замовлення. Каталог Prom вантажать окремо — файлом формату EVO (XLSX) або через YML. Так товари й замовлення Prom розведено навмисно.
Чи змінюється статус замовлення на Prom, коли я обробляю його в Elbuz?
Ні, це підключення працює в один бік: замовлення приходять із Prom у Elbuz, а статус на боці Prom ви змінюєте в кабінеті майданчика. Далі в Elbuz замовлення живе за вашими внутрішніми статусами, і повторне завантаження їх не чіпає. Але й назад нічого не приїде: якщо статус зміниться на Prom уже після завантаження, Elbuz про це не дізнається — прогін пропускає документ, який у вас уже є (докладніше).
Як налаштувати відповідність статусів?
Базове зіставлення вбудоване. Для тонкого налаштування у формі шаблону є кнопки: статус замовлення, доставки, оплати, а також типи оплати й доставки — там ви задаєте, який статус Prom відповідає якому вашому.
Замовлення з'являються з затримкою — чому?
Prom працює поллінгом, без миттєвих сповіщень, тож нові замовлення підтягуються під час чергового запуску за розкладом. Щоб затримка була меншою, поставте частіший розклад — з урахуванням лімітів Prom на частоту звернень.