Інтеграція з Prom

Інтеграція з Prom передає товари, ціни, залишки, фото і різновиди зі Skynum у Prom та завантажує замовлення Prom у Skynum. Зміна статусу замовлення в Skynum може повертатися в Prom.

Інтеграція створюється в Налаштування → Інтеграції → Інтернет-магазини, сервіс Пром.

Як працює обмін

Товари йдуть у Prom через файл. Skynum формує XML-файл у форматі Prom і дає на нього посилання. Це посилання додається в кабінеті Prom як джерело періодичного імпорту, і далі Prom сам забирає файл за своїм розкладом. Skynum оновлює файл щогодини та після кожного збереження інтеграції.

Замовлення йдуть через API Prom за токеном. Skynum забирає нові та змінені замовлення з інтервалом, який задається в інтеграції. Якщо увімкнено експорт статусів, Skynum передає зміну статусу замовлення назад у Prom.

Обидва напрямки спираються на один ключ — ідентифікатор позиції в Prom. Товар потрапляє в Prom під цим ключем, і рядок замовлення Prom знаходить товар у Skynum за цим самим ключем. Тому товари потрібно налаштувати й завантажити в Prom до того, як вмикати замовлення.

У картці інтеграції три вкладки: Налаштування інтеграції, API мапінг і Журнал синхронізації.

Токен API в кабінеті Prom

Токен створюється в кабінеті Prom у розділі Налаштування → Управління API-токенами. Розділ доступний власнику компанії та користувачам з роллю адміністратора.

1. Натисніть Створити токен.
2. Введіть назву токена: літери, цифри або символи, наприклад Skynum.
3. У полі Дійсний до вкажіть термін дії: від одного дня до одного року. Після закінчення терміну потрібно створити новий токен і оновити його в інтеграції.
4. У блоці Доступ надайте права для груп методів:
   • Замовлення і повідомлення — Читання та запис;
   • Клієнти — Читання;
   • Продукти та групи — Читання та запис;
   • Налаштування — Читання.
5. Натисніть Створити токен.
6. Натисніть Дивитись навпроти створеного токена і скопіюйте його.

Для коректної роботи відкривайте доступ для кожної групи на максимальному рівні.

Після закінчення терміну дії токена Prom відповідає на запити Skynum помилкою авторизації, і замовлення перестають завантажуватися. Prom попереджає про закінчення терміну за 30 і за 7 днів у кабінеті та push-сповіщенням. Новий токен вставляється в поле Токен інтеграції.

Створення інтеграції в Skynum

1. Відкрийте Налаштування → Інтеграції → Інтернет-магазини.
2. Натисніть Додати інтеграцію і виберіть Пром.
3. Заповніть Назва магазину.
4. Вставте токен у поле Токен.
5. Збережіть інтеграцію.
6. Натисніть Перевірити підключення.

Перевірка проходить, коли токен дійсний і має право читати замовлення. Якщо перевірка не проходить, перегляньте права токена в Prom і скопіюйте його ще раз.

Налаштування товарів

У блоці Товари увімкніть Синхронізація товарів активна і заповніть налаштування вивантаження.

• Ідентифікатор товара — поле Skynum, значення якого стає ідентифікатором позиції в Prom.
• Ідентифікатор модифікації — поле модифікації, значення якого стає ідентифікатором різновиду в Prom.
• Вивантажувати категорії — як категорії Skynum передаються в Prom.
• Тип ціни товарів — ціна Skynum, яка стає ціною позиції в Prom.
• Вивантажувати фото товарів — чи передавати світлини.
• Вивантажувати товари без залишків — чи передавати позиції з нульовим залишком.
• Опис маркетплейсів — брати для Prom окремий опис із поля Опис маркетплейсів картки товару замість основного опису.
• Назва модифікацій — як складається назва різновиду в Prom.
• Виключити категорії — категорії, товари яких не передаються.
• Тільки товари з категорії — передавати лише товари вибраної категорії та її підкатегорій.
• Тільки залишки по складах — склади, залишок яких передається в Prom.
• Тільки товари з типами — типи номенклатури, які передаються. Послуга потрапляє в Prom як позиція з типом «послуга».
• Використовувати мови — мови, якими передаються назви й описи.

Після збереження в блоці з'являється Файл синхронізації товарів (XML) — посилання на файл для Prom.

Ідентифікатор позиції

Prom знаходить позицію під час імпорту тільки за її ідентифікатором. В Excel-експорті Prom це колонка Ідентифікатор_товару. Назва, код товару та інші поля для зіставлення не використовуються. Якщо в Prom немає позиції з таким ідентифікатором, Prom створює нову.

Значення ідентифікатора береться з поля Skynum, вибраного в Ідентифікатор товара:

• Внутрішній ID;
• Зовнішній ID;
• Код;
• Артикул.

Для товарів з модифікаціями ідентифікатор кожного різновиду береться з поля, вибраного в Ідентифікатор модифікації: Внутрішній ID, Зовнішній ID, Код або Артикул модифікації.

Вибране поле має бути заповнене в кожному товарі, який передається. Товар з порожнім полем у файл не потрапляє.

Якщо товарів у Prom ще немає, виберіть Внутрішній ID: він є в кожного товару і не змінюється. Якщо каталог у Prom уже є, спочатку підготуйте ідентифікатори в Prom за розділом Каталог уже є в Prom і лише потім вибирайте поле.

попередження

Не змінюйте Ідентифікатор товара або Ідентифікатор модифікації в робочій інтеграції. Після зміни Prom отримає ті самі товари з новими ідентифікаторами і створить їх ще раз.

Категорії

Prom вимагає категорію для кожної позиції, тому для Prom у полі Вивантажувати категорії вибирається За назвою або За зовнішнім ID. Skynum передає категорії разом з товарами, і Prom створює або оновлює групи з тією самою вкладеністю, що в каталозі Skynum.

• За назвою — ідентифікатором групи в Prom стає внутрішній ID категорії Skynum, назва групи — назва категорії.
• За зовнішнім ID — ідентифікатором групи стає Зовнішній ID категорії Skynum. Цей варіант потрібен, коли групи в Prom уже існують і їхні ідентифікатори записані в категоріях Skynum.

Полями Виключити категорії і Тільки товари з категорії обмежується перелік категорій і товарів у файлі. Виключення категорії прибирає з файлу і всі її підкатегорії.

Ціни

У полі Тип ціни товарів вибирається ціна Skynum, яка стає ціною позиції в Prom. Якщо для Prom потрібен окремий прайс, створіть додаткову ціну і виберіть її тут.

Якщо в картці товару заповнена Ціна перекреслена, Prom отримує її як стару ціну, а ціну з вибраного типу — як ціну зі знижкою.

Залишки та наявність

Залишок позиції в Prom — це вільний залишок товару в Skynum (залишок мінус резерв) по складах із поля Тільки залишки по складах. Якщо склади не вибрані, рахуються всі склади. Статус наявності в Prom залежить від цього залишку: позиція з залишком більше нуля — «в наявності», з нульовим — «немає в наявності».

Статус можна задати вручну полем Статус наявності в блоці Інтернет-магазин картки товару. Значення В наявності передає позицію як «в наявності» незалежно від залишку, Немає і Очікується — як «немає в наявності». Значення Автоматично означає розрахунок за залишком.

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

Товар зі статусом публікації Чернетка і архівований товар передаються як «немає в наявності». Товар, у якого ця інтеграція знята в блоці Підключені інтеграції картки, у файл не потрапляє.

Назва, опис, фото і виробник

Prom вимагає для кожної позиції назву та опис. Назва береться з картки товару. Опис береться з поля Опис картки або, якщо в інтеграції увімкнено Опис маркетплейсів, з поля Опис маркетплейсів. Заповніть вибране поле в кожному товарі, який передається.

Поле Використовувати мови визначає, якими мовами передаються назва й опис. Щоб у Prom заповнювалися і російська, і українська версії позиції, виберіть UA і RU та заповніть мовні версії назви й опису в картці товару. Prom оновлює українські назву й опис позиції лише тоді, коли у файлі заповнені обидва поля.

При увімкненому Вивантажувати фото товарів Skynum передає до десяти світлин товару. Для різновиду передаються його власні світлини, а якщо їх немає — світлини товару.

Назва виробника з картки товару передається в поле Виробник позиції. Prom приймає виробника лише з власної бази виробників; невідомого виробника Prom позначає у звіті імпорту попередженням і не заповнює.

Характеристики товару передаються лише ті, що зіставлені на вкладці API мапінг (див. API мапінг товарів).

Товари з модифікаціями

Товар з модифікаціями стає в Prom групою різновидів. Кожна модифікація — окрема позиція Prom зі своїм ідентифікатором, ціною, залишком і світлинами. Сам товар окремою позицією в Prom не передається: у Prom основний товар групи — це один із різновидів, а не окрема картка.

Основним товаром групи в Prom стає перша модифікація за назвою (за алфавітом). У кабінеті Prom саме вона показується як головна позиція групи.

Для роботи з різновидами в кабінеті Prom має бути підключений додаток «Різновиди». Без нього Prom імпортує модифікації як окремі незалежні товари.

Поле Назва модифікацій визначає назву кожного різновиду в Prom:

• Товар з модифікацією — назва товару і назва модифікації через дефіс;
• Дублювати назву товара — у всіх різновидів назва товару;
• Не передавати назву — назва не передається.

Характеристики модифікацій (розмір, колір тощо) передаються як характеристики позиції Prom, якщо вони зіставлені в блоці Модифікації на вкладці API мапінг.

API мапінг товарів

На вкладці API мапінг у блоках Характеристики, Модифікації і Додаткові поля навпроти кожного поля Skynum вписується назва, під якою значення передається в Prom. Поле з порожньою назвою в Prom не передається.

• Характеристики — характеристики товару. Назва має збігатися з назвою характеристики в кабінеті Prom для категорії товару, інакше Prom не прив'яже її до своєї характеристики.
• Модифікації — характеристики, за якими створені модифікації. Для товарів з різновидами зіставте хоча б одну: за нею покупець у Prom вибирає різновид.
• Додаткові поля — додаткові поля картки товару; вписана назва стає назвою поля позиції у файлі для Prom, наприклад keywords для пошукових запитів.

Каталог уже є в Prom

Якщо позиції в Prom уже створені, їм потрібно задати ідентифікатор, який збігається зі значенням вибраного поля Skynum. Інакше після імпорту файлу Prom створить другий комплект позицій, а старі залишаться без оновлення.

У кабінеті Prom ідентифікатор позиції задається лише через Excel. Для кожної позиції в Excel-експорті є дві колонки:

• Унікальний_ідентифікатор — внутрішній номер Prom. Його змінити не можна;
• Ідентифікатор_товару — ідентифікатор для імпорту. Саме його Skynum передає у файлі.

Ключем стає Унікальний_ідентифікатор Prom: його записують і в Ідентифікатор_товару позиції Prom, і в Зовнішній ID товару Skynum. Для цього один Excel-файл проходить через обидва кабінети.

Крок у Prom: задати ідентифікатор позиціям

1. Відкрийте список позицій (Товари та послуги → Позиції) і натисніть Експорт.
2. Виберіть Експортувати всі групи і позиції, видимість всі позиції, формат XLS і натисніть Експортувати групи та позиції. Посилання на файл Prom надсилає на пошту та в повідомлення кабінету; воно діє 12 годин.
3. Відкрийте файл і скопіюйте колонку Унікальний_ідентифікатор у колонку Ідентифікатор_товару для всіх рядків. Якщо Ідентифікатор_товару у якихось рядках уже заповнений і саме ці значення записані в Skynum, ці рядки не змінюйте.
4. Збережіть файл і завантажте його в Prom: Товари та послуги → Імпорт, джерело Файл, у блоці Інформація, яку потрібно оновити залиште всі поля. Після імпорту в кожної позиції буде потрібний Ідентифікатор_товару.

Крок у Skynum: записати ідентифікатор у товари

Той самий файл імпортується в Skynum, щоб записати значення з Ідентифікатор_товару в поле Зовнішній ID існуючих товарів. Докладно про вікно імпорту — у статті Імпорт товарів з Excel.

1. Відкрийте Товари → Картотека → Опції → Імпорт і завантажте файл.
2. Над колонками виберіть поля:
   • колонка з назвою позиції тією мовою, якою записані назви товарів у Skynum (Назва_позиції або Назва_позиції_укр) → Найменування; якщо коди товарів у Prom і Skynum збігаються, замість назви використовуйте Код_товару → Код товару;
   • Ідентифікатор_товару → Зовнішній ID товару;
   • решта колонок — Не обрано.
3. Увімкніть Оновити існуючі записи і, якщо зіставляєте за назвою, Пошук за найменуванням. Дозволити створення записів не вмикайте: рядок, для якого товар не знайдено, має залишитися без змін, а не стати новою карткою.
4. Запустіть імпорт.

Skynum знаходить товар за назвою або кодом і записує йому Зовнішній ID з файлу. Назви товарів для такого зіставлення мають бути унікальними: якщо дві картки мають однакову назву, ідентифікатор отримає перша з них.

Після імпорту в інтеграції виберіть Ідентифікатор товара = Зовнішній ID.

Товари з різновидами

Рядки різновидів у файлі Prom (колонка ID_групи_різновидів заповнена) мають одну назву на всю групу, тому за назвою в Skynum їх зіставити не можна. Для них ключем служить код модифікації Skynum:

1. У файлі Prom у кожному рядку групи впишіть в Ідентифікатор_товару код відповідної модифікації Skynum; в основному рядку групи — код першої модифікації за назвою. Зробіть це до імпорту файлу в Prom.
2. Перед імпортом у Skynum приберіть рядки груп різновидів з таблиці імпорту.
3. В інтеграції виберіть Ідентифікатор модифікації = Код.

порада

Перш ніж обробляти весь каталог, перевірте зіставлення на одній категорії: задайте ідентифікатори кільком позиціям, обмежте файл полем Тільки товари з категорії і запустіть імпорт у Prom. Якщо позиції оновилися, а не створилися заново, ключ вибраний правильно.

Імпорт файлу в кабінеті Prom

Після збереження інтеграції скопіюйте посилання з поля Файл синхронізації товарів (XML).

1. У кабінеті Prom відкрийте Товари та послуги → Імпорт.
2. У блоці Спосіб імпорту виберіть Посилання і вставте посилання на файл.
3. У блоці Інформація, яку потрібно оновити залиште позначеними поля, які Prom має брати з файлу. Якщо картки позицій ведуться в Skynum, залиште всі поля. Якщо описи, фото або характеристики редагуються безпосередньо в Prom, залиште лише Ціна, Наявність і Кількість: тоді імпорт не перезаписує те, що змінено в Prom.
4. У блоці Статус товарів, яких немає в файлі виберіть, що робити з позиціями, яких у файлі вже немає. Для каталогу, який повністю ведеться в Skynum, підходить Немає в наявності або Приховані.
5. Не вмикайте Завантажити позиції «В наявності»: з цим прапорцем Prom не оновлює позиції з нульовим залишком, і вони залишаються в Prom «в наявності».
6. Натисніть Почати імпорт і дочекайтеся завершення.

Хід імпорту видно на вкладці Імпорт, результат і помилки — на вкладці Звіт по імпорту. Якщо у звіті є помилки, виправте дані в Skynum (категорію, опис, виробника, світлини) і запустіть імпорт ще раз. Ручний запуск доступний до 10 разів на добу з інтервалом 2 години.

Збережене посилання Prom перевіряє сам: ціну, наявність, кількість і знижку оновлює раз на 4 години, решту полів і нові позиції — раз на добу вночі. Якщо файл шість днів поспіль недоступний або порожній, Prom вимикає періодичний імпорт за цим посиланням; після усунення причини запустіть імпорт за посиланням знову.

Після першого імпорту відкрийте Товари та послуги → Позиції в Prom і перевірте кілька товарів: назву, ціну, наявність, світлини, групу і різновиди.

Налаштування замовлень

У блоці Замовлення увімкніть Синхронізація замовлень активна і заповніть налаштування.

• Інтервал синхронізації — через скільки хвилин Skynum знову запитує замовлення в Prom.
• Ігнорувати замовлення до дати — замовлення, створені раніше цієї дати, не завантажуються. Поставте дату підключення, щоб не отримати старі замовлення.
• Резервувати товари після створення замовлення — після завантаження замовлення Skynum одразу резервує товари.
• Встановити зовнішній номер замовлення — номером замовлення в Skynum стає номер замовлення Prom.
• Імпортувати повторно змінені замовлення — Skynum повторно забирає замовлення, які змінилися в Prom після першого завантаження.
• Спосіб оновлення замовлень — що саме Skynum оновлює в уже завантаженому замовленні: Не оновлювати, Тільки статус, Оновити заповнені або Повністю оновити.
• Заборонити оновлення замовлень у статусі — замовлення у вибраних статусах Skynum не змінюються повторним імпортом.
• Створити пов'язаний платіж на суму оплати — для оплаченого в Prom замовлення Skynum створює платіж.
• Фіскалізація платежу і ПРРО для фіскалізації — автоматичний фіскальний чек на створений платіж.
• Експорт замовлень — Ні або Тільки статус: чи передавати зміну статусу замовлення назад у Prom.
• Склад за замовчуванням — склад замовлення для резервування та відвантаження.
• Канал продажів — канал, який отримують усі замовлення з Prom.
• Група контрагента — група для покупців, яких Skynum створює із замовлень.
• Контрагент за замовчуванням — Створити контрагента, щоб кожен покупець Prom став окремим контрагентом, або один контрагент для всіх замовлень.
• Сповіщати про нові замовлення — користувачі, які отримують сповіщення про кожне нове замовлення.

Поле Час останньої синхронізації показує, коли Skynum востаннє забирав замовлення.

Товари в замовленні

Рядок замовлення Prom містить ідентифікатор позиції. Skynum шукає за ним модифікацію за полем Ідентифікатор модифікації, а потім товар за полем Ідентифікатор товара. Знайдений товар стає рядком замовлення з ціною та кількістю з Prom.

Якщо товар за ідентифікатором не знайдено, замовлення все одно створюється, а рядок пропускається; у журналі замовлення з'являється помилка «Товар не знайдений» з назвою позиції. Так буває, коли позицію створили в кабінеті Prom вручну без ідентифікатора або товар видалили зі Skynum. Задайте позиції правильний Ідентифікатор_товару в Prom і завантажте замовлення ще раз.

Різниця між сумою рядків і сумою замовлення Prom записується в замовлення як знижка.

Покупець і доставка

Покупець створюється з імені, телефону та e-mail замовлення в групі з поля Група контрагента. Нотатки покупця з Prom записуються в поле Опис замовлення.

Доставку Skynum створює до кожного замовлення. Нову пошту, Укрпошту, Meest і доставку Rozetka Skynum визначає з даних замовлення Prom і підставляє відділення або адресу одержувача; для Нової пошти підставляється відділення одержувача. Решта варіантів доставки Prom створюється як Кур'єром по місту з адресою з замовлення в нотатках.

Оплата і фіскалізація

Prom позначає замовлення оплаченим, коли покупець оплатив його через Prom. Якщо в інтеграції увімкнено Створити пов'язаний платіж на суму оплати, а спосіб оплати Prom зіставлений зі способом оплати Skynum у блоці Оплата вкладки API мапінг, Skynum створює платіж на суму оплати і прив'язує його до замовлення.

Щоб на такий платіж одразу виходив фіскальний чек, увімкніть Фіскалізація платежу і виберіть ПРРО для фіскалізації. Спосіб оплати Skynum при цьому має бути пов'язаний із касою або банківським рахунком.

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

Докладніше:

• Оплачені замовлення з інтернет-магазинів і автофіскалізація;
• Способи оплати;
• Налаштування фіскального сервісу.

Статуси в обидва боки

Статуси зіставляються в блоці Статуси вкладки API мапінг: навпроти кожного статусу Skynum вибирається статус Prom. Перелік статусів Prom, зокрема власні статуси компанії, завантажується кнопкою Завантажити з Пром.

Зміна статусу в Prom потрапляє в Skynum при повторному імпорті, якщо увімкнено Імпортувати повторно змінені замовлення і вибраний спосіб оновлення включає статус.

Зміна статусу в Skynum передається в Prom, якщо в полі Експорт замовлень вибрано Тільки статус. Передається статус Prom, зіставлений з новим статусом Skynum. Скасоване в Skynum замовлення скасовується в Prom із причиною «немає в наявності».

попередження

Один статус Prom зіставляйте лише з одним статусом Skynum. Статуси, які не потрібні, залишайте порожніми.

Ручне завантаження

Кнопка Завантажити замовлення в картці інтеграції запускає завантаження одразу, не чекаючи інтервалу. Завантажені замовлення видно в Торгівля → Замовлення з фільтром за джерелом Пром. Окреме замовлення оновлюється з Prom кнопкою Завантажити в документі.

Далі із замовленням працюють як зі звичайним замовленням покупця: резерв, оплата, доставка, виконання.

Журнал синхронізації

На вкладці Журнал синхронізації записується кожен запуск завантаження замовлень і передачі статусів: успішний результат або текст помилки Prom. Помилка авторизації означає, що токен прострочений, видалений або не має потрібних прав.

Результат вивантаження товарів перевіряється не тут, а у звіті імпорту в кабінеті Prom: файл формує Skynum, а читає і перевіряє його Prom.

Загальний порядок перевірки інтеграцій описаний у статті Перевірка синхронізації інтеграцій, типові причини помилок — у статті Типові помилки інтеграцій.

Коротка перевірка

• токен Prom створений з доступом до всіх груп, вставлений у Skynum, підключення перевірене;
• Ідентифікатор товара і Ідентифікатор модифікації вибрані, поля заповнені в товарах;
• для каталогу, який уже був у Prom, ідентифікатори записані в Ідентифікатор_товару;
• Вивантажувати категорії — За назвою або За зовнішнім ID;
• у товарів заповнені назва, опис, світлини і категорія;
• характеристики і модифікації зіставлені на вкладці API мапінг;
• посилання на файл додане в імпорт Prom, перший імпорт завершився без помилок;
• позиції в Prom оновилися, а не створилися повторно;
• статуси й оплати зіставлені, тестове замовлення з Prom завантажилося в Skynum.

Підсумок

Товари передаються в Prom файлом, замовлення повертаються через API, і обидва потоки зв'язує ідентифікатор позиції. Правильно вибраний ідентифікатор і підготовлений каталог Prom дають оновлення існуючих позицій замість дублікатів, а зіставлені статуси й оплати — повний цикл замовлення в Skynum.