K2 Модуль Magento

K2 Модуль Magento — це інтеграційний модуль для обміну даними між K2 ERP та платформою електронної комерції Magento / Adobe Commerce. Він використовується для автоматизації роботи з товарами, категоріями, цінами, залишками, замовленнями, клієнтами, оплатами, доставкою, поверненнями, статусами та фіскалізацією.

Magento Open Source і Adobe Commerce використовують спільну REST API-архітектуру для on-premises та cloud PaaS-розгортань, а також мають GraphQL API для ефективного обміну даними між магазином і storefront. Для Adobe Commerce as a Cloud Service набір REST endpoint-ів відрізняється, а для автентифікації використовується Adobe Identity Management Service.

Важливо: K2 Модуль Magento не замінює інтернет-магазин і не замінює ERP. Magento відповідає за онлайн-вітрину, каталог, кошик, оформлення замовлення та клієнтський досвід, а K2 ERP має бути центральною системою для товарів, залишків, цін, документів, складів, оплат, доставок і фіскалізації.

Загальний опис

Magento використовується як канал онлайн-продажів. У магазині Magento покупець переглядає каталог, фільтрує товари, додає їх у кошик, оформлює замовлення, вибирає доставку, оплату та отримує підтвердження покупки.

Без інтеграції менеджерам доводиться вручну переносити товари, категорії, ціни, залишки, клієнтів і замовлення між Magento та ERP. Це створює ризики: застарілі залишки, неправильні ціни, дублікати замовлень, несвоєчасне оновлення статусів, помилки під час відвантаження та складність контролю фіскалізації.

K2 Модуль Magento автоматизує обмін даними. K2 ERP може виступати головним джерелом товарів, цін, залишків, складів, документів, оплат і фіскалізації, а Magento — зовнішнім каналом продажів і вітриною для покупців.

Зверніть увагу: конкретні можливості модуля залежать від версії Magento або Adobe Commerce, доступних API, типу розгортання, прав інтеграційного користувача, структури товарів, складів, store views, способів доставки, оплат, податків, валюти та бізнес-логіки K2 ERP.

Для чого потрібен K2 Модуль Magento

K2 Модуль Magento потрібен для автоматизації обміну між ERP і Magento.

Основні задачі модуля:

передавання товарів із K2 ERP у Magento;
оновлення назв, описів, фото, категорій, атрибутів і варіантів;
синхронізація цін;
синхронізація залишків;
робота з кількома складами або джерелами запасів;
отримання замовлень із Magento;
створення замовлень клієнта в K2 ERP;
створення або оновлення карток клієнтів;
передавання статусів замовлень назад у Magento;
передавання shipment-даних;
передавання tracking number;
контроль оплат;
контроль invoice-статусів;
контроль повернень і credit memo;
підготовка даних для фіскалізації;
зберігання історії обміну;
обробка помилок інтеграції.

Основні можливості

K2 Модуль Magento може забезпечувати такі можливості:

підключення одного або кількох магазинів Magento;
налаштування REST API або GraphQL API;
налаштування інтеграційного користувача;
імпорт товарів із Magento;
експорт товарів у Magento;
оновлення товарних карток;
робота з configurable products;
робота з simple products;
робота з bundle, grouped або virtual products за потреби;
робота з категоріями;
робота з атрибутами;
синхронізація цін;
синхронізація залишків;
отримання нових замовлень;
отримання клієнтів;
отримання оплат і статусів;
створення shipment;
передавання tracking number;
обробка повернень;
зіставлення товарів за SKU або Magento ID;
зіставлення способів доставки;
зіставлення способів оплати;
журнал API-запитів;
повторна обробка помилок;
ручний і автоматичний режим синхронізації.

Практичне застосування: K2 Модуль Magento особливо корисний для магазинів із великим каталогом, складними атрибутами, кількома store views, частими змінами цін, багатоскладським обліком і регулярними онлайн-замовленнями.

Magento REST API

Magento REST API використовується для програмного доступу до даних магазину. Через REST API можна працювати з товарами, категоріями, замовленнями, клієнтами, інвентарем, shipment, invoice, credit memo та іншими об’єктами.

Adobe Commerce REST API документація описує REST API для Adobe Commerce PaaS, Adobe Commerce on-premises і Magento Open Source. Для Adobe Commerce as a Cloud Service доступний інший набір endpoint-ів, а customer і guest REST API, доступні в on-premises / PaaS-версіях, у SaaS-версії не доступні в такому самому вигляді.

Типові REST-напрями інтеграції:

catalog products;
categories;
customers;
orders;
invoices;
shipments;
credit memos;
inventory;
source items;
stock;
payment information;
shipping information;
store configuration.

Magento GraphQL API

Magento GraphQL API дозволяє ефективно отримувати дані для storefront і зовнішніх застосунків. Adobe описує GraphQL API як інструмент для швидкого та ефективного передавання інформації між Commerce store і storefront.

GraphQL API може використовуватися для:

отримання товарів;
отримання категорій;
отримання цін;
отримання атрибутів;
роботи з cart;
роботи з customer;
роботи з checkout;
отримання order-даних у підтримуваних сценаріях;
оптимізації кількості запитів;
побудови headless storefront.

Рекомендація: для K2 ERP основний обмін адміністративними даними зазвичай зручніше будувати через REST API, а GraphQL використовувати там, де потрібно ефективно отримувати складні набори даних або підтримувати headless-сценарії.

Авторизація і доступ

Для інтеграції K2 ERP із Magento потрібно налаштувати доступ до API. У Magento Open Source і Adobe Commerce on-premises / PaaS можуть використовуватися інтеграційні токени, admin token або OAuth-підходи залежно від конфігурації.

У модулі Magento бажано зберігати:

назву підключення;
base URL магазину;
тип API;
access token або інший спосіб авторизації;
права доступу;
store view;
website;
дату створення підключення;
статус підключення;
користувача, який налаштував інтеграцію;
дату останньої перевірки;
версію Magento;
журнал помилок авторизації.

Не плутати: access token або admin token — це ключ доступу до магазину Magento. Його не можна передавати стороннім особам, зберігати у відкритому коді, публікувати в логах або відправляти в незахищених повідомленнях.

Синхронізація товарів

Синхронізація товарів дозволяє передавати асортимент із K2 ERP у Magento або отримувати товари з Magento в ERP.

З K2 ERP у Magento можуть передаватися:

назва товару;
SKU;
опис;
короткий опис;
ціна;
спеціальна ціна;
статус активності;
visibility;
tax class;
weight;
категорії;
атрибути;
images;
media gallery;
stock data;
configurable options;
related products;
upsell products;
cross-sell products;
SEO-поля;
custom attributes.

З Magento у K2 ERP можуть завантажуватися:

Magento product ID;
SKU;
назва;
тип товару;
ціна;
статус;
категорії;
атрибути;
залишок;
media;
store view values;
custom attributes.

Типи товарів Magento

Magento підтримує різні типи товарів. Для інтеграції важливо правильно зіставити їх із моделлю товарів K2 ERP.

Типові типи товарів:

simple product;
configurable product;
grouped product;
bundle product;
virtual product;
downloadable product.

Simple product

Simple product — це базова товарна позиція з власним SKU, ціною та залишком. У складському обліку саме simple product часто відповідає реальному товару.

Configurable product

Configurable product — це товар із варіантами, наприклад за розміром, кольором або іншими параметрами. Він об’єднує кілька simple products, кожен із яких має власний SKU.

Для обліку: у більшості ERP-сценаріїв реальним складським товаром є simple product, а configurable product виконує роль вітринної групи варіантів. Тому для залишків, резервів і відвантаження потрібно зберігати зв’язки між configurable і simple products.

Категорії та атрибути

Magento має гнучку систему категорій та атрибутів. Це важливо для товарного каталогу, фільтрів, пошуку і SEO.

K2 Модуль Magento може синхронізувати:

дерево категорій;
прив’язку товарів до категорій;
attribute sets;
product attributes;
значення атрибутів;
фільтраційні атрибути;
текстові характеристики;
числові характеристики;
select і multiselect-атрибути;
store view значення.

У K2 ERP потрібно визначити правила:

які атрибути ведуться в ERP;
які атрибути імпортуються з Magento;
які атрибути не синхронізуються;
як зіставляти довідники значень;
як оновлювати атрибути без втрати ручних даних у Magento;
хто є головним джерелом атрибутів.

Store views, websites і мови

Magento підтримує websites, stores і store views. Це дозволяє одному Magento-інстансу обслуговувати кілька магазинів, мов або регіонів.

Для інтеграції потрібно врахувати:

website;
store;
store view;
мову;
валюту;
локалізовані назви;
локалізовані описи;
локалізовані SEO-поля;
різні ціни за website;
різні статуси публікації;
різні категорії за магазином.

Зверніть увагу: якщо Magento використовується для кількох мов або магазинів, у K2 ERP потрібно зберігати локалізовані назви, описи та правила публікації для кожного store view.

Синхронізація цін

Синхронізація цін потрібна для того, щоб у Magento відображалися актуальні ціни з K2 ERP.

Можливі сценарії:

K2 ERP є головним джерелом цін;
для Magento використовується окремий тип цін;
ціни оновлюються за розкладом;
ціни оновлюються після зміни в ERP;
special price використовується для акцій;
ціни залежать від website;
ціни залежать від валюти;
ціни округлюються за правилами магазину;
частина товарів не оновлюється автоматично;
ціни груп клієнтів передаються окремо.

У K2 ERP бажано мати окремі правила:

основна ціна Magento;
акційна ціна Magento;
валюта Magento;
website для ціни;
правило округлення;
правило оновлення;
дата останньої синхронізації.

Синхронізація залишків

Magento Inventory Management використовується для обліку запасів. Adobe зазначає, що Inventory Management у Magento Open Source і Adobe Commerce замінює старі core API CatalogInventory та ScalableInventory і додає нові API для розширення функціональності.

Inventory Management включає concepts sources, stocks і source items. Для багатоскладських сценаріїв важливо правильно зіставити склади K2 ERP з Magento sources або stocks.

Можливі сценарії синхронізації:

залишок з одного складу K2 ERP передається в default source;
кілька складів K2 ERP зіставляються з кількома Magento sources;
у Magento передається доступний залишок з урахуванням резервів;
залишок оновлюється за розкладом;
залишок оновлюється після складського руху;
при нульовому залишку товар вимикається або змінює stock status;
залишок обмежується мінімальним або максимальним значенням для показу.

Рекомендація: для Magento потрібно передавати не бухгалтерський залишок, а доступний до продажу залишок: фактична кількість мінус резерви, очікувані відвантаження та інші блокування.

Отримання замовлень

Одна з ключових функцій модуля — отримання замовлень із Magento у K2 ERP.

Із замовлення можуть завантажуватися:

Magento order ID;
increment ID;
дата створення;
дата оновлення;
статус замовлення;
state;
покупець;
email;
телефон;
billing address;
shipping address;
список товарів;
order item ID;
product ID;
SKU;
кількість;
ціна;
знижки;
податки;
доставка;
загальна сума;
валюта;
payment method;
shipping method;
customer group;
coupon code;
comments;
invoices;
shipments;
credit memos за потреби.

У K2 ERP на підставі замовлення Magento може створюватися:

замовлення клієнта;
картка клієнта;
резерв товару;
завдання на пакування;
документ оплати;
документ доставки;
фіскальний чек;
видаткова накладна;
документ повернення.

Клієнти

Модуль Magento може завантажувати або оновлювати клієнтів у K2 ERP.

Дані клієнта можуть включати:

Magento customer ID;
ім’я;
прізвище;
email;
телефон;
адреси;
країну;
місто;
поштовий індекс;
customer group;
website;
store view;
дату створення;
дату останнього оновлення.

У K2 ERP потрібно визначити правила зіставлення клієнтів:

за email;
за телефоном;
за Magento customer ID;
за комбінацією email і телефону;
створювати нового клієнта, якщо збігу немає;
не дублювати клієнта при повторному замовленні;
окремо обробляти guest checkout.

Оплати

Magento може мати різні payment methods і статуси оплат. У K2 ERP потрібно коректно зіставити оплату з документом продажу.

В ERP бажано зберігати:

спосіб оплати;
payment method code;
payment title;
transaction ID;
суму замовлення;
суму оплати;
валюту;
комісію за потреби;
дату оплати;
invoice ID;
статус invoice;
статус повернення коштів;
зв’язок із касовим, банківським або платіжним документом.

Доставка, shipment і tracking

У Magento shipment відповідає за відвантаження замовлення. K2 ERP може створювати shipment у Magento або оновлювати shipment-дані після фактичного відвантаження.

Модуль K2 Magento може передавати назад у Magento:

shipment data;
tracking number;
carrier code;
carrier title;
дату відправлення;
часткове відвантаження;
інформацію про відвантажені позиції;
коментарі до shipment.

У K2 ERP це може бути пов’язано з:

складським відвантаженням;
видатковою накладною;
завданням на пакування;
службою доставки;
ТТН;
статусом доставки;
частковим відвантаженням.

Практичне застосування: коли K2 ERP передає tracking number у Magento, покупець може бачити актуальну інформацію про відправлення, а менеджерам не потрібно вручну оновлювати замовлення в Magento Admin.

Повернення і credit memo

Повернення в Magento можуть бути пов’язані з credit memo, поверненням товару, частковим поверненням коштів або скасуванням замовлення.

У K2 ERP потрібно визначити правила:

як отримувати credit memo з Magento;
як створювати документ повернення;
як повертати товар на склад;
як обробляти часткове повернення;
як обробляти повернення доставки;
як оновлювати фінансовий статус;
як виконувати фіскалізацію повернення;
як зберігати зв’язок із початковим замовленням.

Webhooks і події

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

періодичне опитування API;
Magento webhooks через розширення;
Adobe Commerce events або App Builder-сценарії;
власний модуль Magento для відправлення подій;
черги повідомлень;
інтеграційний middleware.

Події можуть повідомляти K2 ERP про:

створення замовлення;
оновлення замовлення;
оплату;
скасування;
створення shipment;
створення invoice;
створення credit memo;
оновлення товару;
зміну залишку;
оновлення клієнта.

Інтеграційний акцент: подієвий обмін бажано поєднувати з періодичною звіркою. Подія пришвидшує реакцію на зміну, а регулярна синхронізація допомагає знайти пропущені або некоректно оброблені записи.

Фіскалізація замовлень Magento

Для B2C-продажів через Magento може бути потрібна фіскалізація через РРО або ПРРО залежно від країни, способу оплати, юридичної особи та законодавчих вимог.

У K2 ERP це може працювати так:

Замовлення надходить із Magento.
ERP перевіряє статус оплати.
Система створює документ продажу.
Виконується фіскалізація через РРО або ПРРО.
Номер фіскального чека зберігається в ERP.
За потреби чек надсилається покупцю.
Статус фіскалізації зберігається у замовленні.
У разі повернення формується чек повернення.

Використання модуля Magento у K2 ERP

У системі K2 ERP модуль Magento може використовуватися як окремий канал продажів.

Типова реалізація може включати:

налаштування підключення до Magento;
зберігання base URL;
зберігання access token;
вибір API-режиму;
вибір store view;
вибір website;
вибір складів для залишків;
зіставлення Magento sources зі складами K2 ERP;
вибір типу цін для Magento;
зіставлення товарів за SKU або product ID;
зіставлення configurable і simple products;
зіставлення категорій;
зіставлення атрибутів;
експорт товарів;
оновлення цін;
оновлення залишків;
імпорт замовлень;
імпорт клієнтів;
створення документів замовлення клієнта;
резервування товарів;
передавання shipment-даних;
передавання tracking number;
інтеграцію з доставкою;
інтеграцію з оплатами;
фіскалізацію;
журнал технічного обміну;
обробку подій або періодичної синхронізації.

Для K2 ERP: Magento варто розглядати як зовнішній канал продажів. K2 ERP має бути головною системою для товарів, залишків, цін, документів, оплат, доставок і фіскалізації, а Magento — онлайн-вітриною та джерелом замовлень.

Типовий сценарій синхронізації товарів

Типовий сценарій експорту товарів із K2 ERP у Magento може виглядати так:

Користувач створює або оновлює товар у K2 ERP.
Система перевіряє SKU, назву, опис, ціну, фото, вагу, категорії та атрибути.
Модуль Magento визначає, чи товар уже існує в Magento.
Якщо товар існує, система оновлює його дані.
Якщо товару немає, система створює нову картку товару.
Для configurable products створюються або оновлюються пов’язані simple products.
Оновлюються ціни.
Оновлюються залишки.
Magento повертає результат обробки.
K2 ERP зберігає Magento product ID і зв’язки з товарами.
У журналі обміну зберігається статус і можливі помилки.

Типовий сценарій обробки замовлення

Типовий сценарій обробки замовлення Magento у K2 ERP може виглядати так:

Покупець оформлює замовлення в Magento.
Magento створює замовлення.
K2 ERP отримує замовлення через API або подію.
K2 ERP перевіряє, чи замовлення вже не імпортоване.
Система створює замовлення клієнта.
Система зіставляє товари за SKU або product ID.
Товари резервуються на складі.
Менеджер або система перевіряє оплату.
Формується складське відвантаження.
Створюється ТТН або інший документ доставки.
За потреби виконується фіскалізація.
Shipment і tracking number передаються назад у Magento.
Статус замовлення оновлюється.

Дані, які бажано зберігати в ERP

Для якісної інтеграції з Magento в K2 ERP бажано зберігати:

base URL магазину;
тип API;
access token;
Magento version;
website ID;
store ID;
store view ID;
Magento product ID;
SKU;
product type;
configurable parent ID;
simple child IDs;
source code;
stock ID;
статус синхронізації товару;
дату останнього оновлення товару;
Magento order ID;
increment ID;
дату замовлення;
order state;
order status;
Magento customer ID;
email покупця;
телефон покупця;
shipping address;
billing address;
shipping method;
payment method;
transaction ID;
invoice ID;
shipment ID;
tracking number;
credit memo ID;
статус фіскалізації;
номер фіскального чека;
текст помилки API;
журнал запитів і відповідей;
кількість спроб синхронізації.

Журнал обміну

Журнал обміну потрібен для контролю інтеграції та швидкого пошуку помилок.

У журналі бажано зберігати:

дату і час запиту;
напрям обміну;
тип операції;
об’єкт обміну;
Magento ID;
ідентифікатор K2 ERP;
endpoint або GraphQL operation;
статус операції;
текст помилки;
технічну відповідь API;
користувача або сервіс, який запустив обмін;
кількість повторних спроб;
результат повторної обробки.

Можливі помилки під час інтеграції

Під час роботи модуля Magento можуть виникати такі помилки:

access token недійсний;
недостатньо прав доступу;
магазин недоступний;
API-версія або endpoint не відповідає розгортанню;
перевищено ліміт або виникла технічна помилка API;
товар не знайдено;
дублюється SKU;
не зіставлено configurable product;
не знайдено simple product;
не зіставлена категорія;
не зіставлений attribute set;
не зіставлене значення атрибута;
не завантажується фото;
неправильна ціна;
неправильний залишок;
не зіставлений source або stock;
замовлення вже імпортоване;
товар із замовлення не знайдено в K2 ERP;
неправильний спосіб доставки;
неправильний спосіб оплати;
shipment не створено;
tracking number не передано;
помилка фіскалізації;
помилка повернення;
статус не оновився.

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

Безпека інтеграції

Для безпечної роботи K2 Модуля Magento потрібно контролювати:

доступ до access token;
права інтеграційного користувача;
права користувачів K2 ERP;
журнал дій;
обмеження доступу до налаштувань;
шифрування секретів;
захист логів;
резервне копіювання налаштувань;
оновлення Magento;
встановлення security patches;
блокування доступу звільнених працівників;
розмежування прав між менеджерами й адміністраторами;
контроль змін цін і залишків.

Безпека: Magento і Adobe Commerce потрібно регулярно оновлювати та патчити. Через те, що магазин обробляє замовлення, клієнтів і платежі, застарілі версії та вразливі модулі можуть створювати критичні ризики для бізнесу.

Дані, які не можна виводити в логах

У логах інтеграції не варто виводити:

access token;
admin token;
паролі;
приватні ключі;
повні дані платіжних карток;
webhook secrets;
персональні дані понад необхідний мінімум;
production connection strings;
внутрішні ключі API;
сертифікати;
конфіденційні фінансові дані.

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

Переваги K2 Модуля Magento

До основних переваг модуля можна віднести:

менше ручного введення;
швидше оновлення товарів;
актуальні ціни;
актуальні залишки;
підтримку складних товарних структур;
підтримку категорій і атрибутів;
автоматичне отримання замовлень;
менше помилок менеджерів;
швидша обробка замовлень;
контроль оплат;
контроль shipment-статусів;
передавання tracking number;
зв’язок із фіскалізацією;
централізований облік у K2 ERP;
прозорий журнал інтеграції;
підтримку кількох каналів продажів.

Обмеження та ризики

Під час впровадження модуля Magento потрібно враховувати:

залежність від API Magento;
різницю між Magento Open Source, Adobe Commerce PaaS і Adobe Commerce as a Cloud Service;
потребу в access token;
потребу в правильних правах доступу;
складність configurable products;
складність attribute sets;
різницю між складами ERP і Magento sources;
можливі помилки в SKU;
потребу в контролі залишків;
потребу в обробці дублювань;
потребу в тестуванні перед масовим експортом;
ризик оновлення неправильних цін;
ризик передавання неправильних залишків;
потребу в контролі персональних даних покупців;
потребу в оновленнях і security patches.

Не плутати: K2 Модуль Magento — це не просто імпорт замовлень. Повноцінна інтеграція має охоплювати товари, категорії, атрибути, configurable products, ціни, залишки, sources, замовлення, клієнтів, оплати, shipment, повернення, фіскалізацію та журнал помилок.

Висновок

K2 Модуль Magento — це інтеграційний компонент для автоматизації обміну між K2 ERP та Magento / Adobe Commerce. Він дозволяє синхронізувати товари, категорії, атрибути, ціни, залишки, отримувати замовлення, передавати shipment-статуси, tracking number і забезпечувати зв’язок онлайн-продажів із внутрішнім обліком компанії.

Для K2 ERP модуль Magento доцільно реалізовувати як окремий канал продажів із власними налаштуваннями API, типом цін, складами, правилами синхронізації, журналом обміну, обробкою помилок, підтримкою подій або регулярної синхронізації та зв’язком із доставкою, оплатами, поверненнями й фіскалізацією.

Джерела

Див. також

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

Інтеграція з Новою поштою в Python

Інтеграція з Укрпоштою в Python

РРО

Інтеграція РРО в Python

Технічне завдання: інтеграція ПРРО Checkbox для Python

ДПС

ЕДО