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