K2 Модуль Shopify

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

Shopify надає Admin API для розробки застосунків та інтеграцій, які розширюють можливості Shopify Admin. Основним рекомендованим напрямом для нових інтеграцій є GraphQL Admin API, а REST Admin API має статус legacy; Shopify також зазначає, що деякі новіші можливості платформи можуть бути доступні лише через GraphQL.

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

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

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

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

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

Зверніть увагу: конкретні можливості модуля залежать від API Shopify, прав доступу застосунку, тарифу Shopify, структури товарів, локацій, способів доставки, оплат, податків, валюти та бізнес-логіки K2 ERP.

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

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

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

передавання товарів із K2 ERP у Shopify;
оновлення назв, описів, фото, варіантів і характеристик;
синхронізація цін;
синхронізація залишків;
робота з кількома складами або Shopify locations;
отримання замовлень із Shopify;
створення замовлень клієнта в K2 ERP;
створення або оновлення карток клієнтів;
передавання статусів замовлень назад у Shopify;
передавання даних доставки;
передавання номерів відправлень;
контроль оплат;
контроль повернень і refund-операцій;
підготовка даних для фіскалізації;
зберігання історії обміну;
обробка помилок інтеграції.

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

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

підключення одного або кількох магазинів Shopify;
зберігання access token;
налаштування API scopes;
імпорт товарів із Shopify;
експорт товарів у Shopify;
оновлення товарних карток;
робота з variants;
робота з collections;
синхронізація цін;
синхронізація залишків;
отримання нових замовлень;
отримання клієнтів;
отримання оплат і фінансових статусів;
отримання fulfillment-статусів;
передавання fulfillment-даних;
передавання tracking number;
обробка повернень;
робота з webhooks;
зіставлення товарів за SKU або Shopify ID;
зіставлення способів доставки;
зіставлення способів оплати;
журнал API-запитів;
повторна обробка помилок;
ручний і автоматичний режим синхронізації.

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

Shopify Admin API

Для інтеграції з Shopify використовується Admin API. Shopify надає GraphQL Admin API для створення застосунків та інтеграцій, які працюють із даними магазину, зокрема товарами, замовленнями, клієнтами, інвентарем і fulfillment-процесами.

REST Admin API у Shopify має статус legacy. У документації Shopify зазначено, що REST Admin API є legacy API з 1 жовтня 2024 року, а з 1 квітня 2025 року всі нові публічні застосунки мають будуватися виключно на GraphQL Admin API.

Рекомендація: нову інтеграцію K2 ERP з Shopify бажано проєктувати на GraphQL Admin API. REST API можна використовувати лише там, де це виправдано сумісністю, старим кодом або конкретними обмеженнями проєкту.

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

Для інтеграції K2 ERP із Shopify потрібно створити застосунок або custom app у Shopify Admin і отримати access token з потрібними правами доступу.

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

назву магазину;
shop domain;
access token;
перелік API scopes;
дату створення підключення;
статус підключення;
користувача, який налаштував інтеграцію;
дату останньої перевірки;
версію API;
журнал помилок авторизації.

API scopes мають відповідати задачам інтеграції. Наприклад, для роботи з товарами потрібні права на читання або запис товарів, для залишків — права на inventory, для замовлень — права на orders, для fulfillment — відповідні права на fulfillment-операції.

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

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

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

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

назва товару;
опис;
SKU;
barcode;
vendor;
product type;
tags;
collections;
images;
variants;
options;
price;
compare-at price;
inventory tracking;
weight;
SEO-поля;
metafields;
статус публікації.

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

Shopify product ID;
Shopify variant ID;
inventory item ID;
назва;
SKU;
barcode;
ціна;
залишок;
статус товару;
collections;
images;
options;
variants.

Variants і options

У Shopify товар може мати варіанти. Наприклад, футболка може мати розмір і колір, а кожна комбінація розміру й кольору буде окремим variant зі своїм SKU, ціною, залишком і barcode.

У K2 ERP потрібно визначити, як варіанти Shopify зіставляються з товарами ERP.

Можливі підходи:

кожен Shopify variant відповідає окремому товару K2 ERP;
один товар K2 ERP має характеристики, які експортуються як Shopify options;
Shopify product використовується як група, а variants — як окремі складські позиції;
зіставлення виконується за SKU;
зіставлення виконується за Shopify variant ID;
зіставлення виконується вручну через таблицю відповідності.

Для обліку: у більшості ERP-сценаріїв саме variant, а не product, є реальною складською позицією. Тому для залишків, резервів і відвантаження бажано зберігати Shopify variant ID та inventory item ID.

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

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

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

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

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

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

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

Синхронізація залишків дозволяє передавати актуальну доступну кількість товару з K2 ERP у Shopify.

Shopify використовує inventory items і locations для обліку залишків. У GraphQL Admin API inventory item може містити властивості, пов’язані з SKU, cost, tracking і shipping requirement, а для оновлення інвентарних даних потрібні відповідні inventory access scopes.

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

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

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

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

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

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

Shopify order ID;
order name;
дата створення;
дата оновлення;
фінансовий статус;
fulfillment-статус;
покупець;
email;
телефон;
billing address;
shipping address;
список товарів;
Shopify line item ID;
variant ID;
SKU;
кількість;
ціна;
знижки;
податки;
доставка;
загальна сума;
валюта;
payment gateway;
shipping method;
note;
tags;
metafields;
refund-дані за потреби.

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

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

Клієнти

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

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

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

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

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

Оплати

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

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

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

Типові фінансові стани:

pending;
authorized;
paid;
partially_paid;
refunded;
partially_refunded;
voided.

Доставка і fulfillment

У Shopify fulfillment відповідає за виконання замовлення: комплектування, передавання перевізнику, відправлення і tracking.

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

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

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

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

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

Повернення і refunds

Повернення в Shopify можуть бути пов’язані з refund-операціями, поверненням товару, частковим поверненням коштів або скасуванням замовлення.

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

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

Webhooks

Shopify webhooks дозволяють отримувати події з магазину без постійного опитування API.

Webhook може повідомляти K2 ERP про такі події:

створено замовлення;
оновлено замовлення;
оплачено замовлення;
скасовано замовлення;
створено fulfillment;
оновлено fulfillment;
створено refund;
оновлено товар;
змінено інвентар;
оновлено клієнта.

У REST-документації Shopify зазначено, що REST Admin API має legacy-статус, тому для нових інтеграцій варто враховувати актуальні рекомендації Shopify щодо GraphQL і сучасної моделі застосунків.

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

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

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

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

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

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

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

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

налаштування підключення до Shopify;
зберігання shop domain;
зберігання access token;
вибір API-версії;
вибір складів для залишків;
зіставлення Shopify locations зі складами K2 ERP;
вибір типу цін для Shopify;
зіставлення товарів за SKU, product ID або variant ID;
експорт товарів;
оновлення цін;
оновлення залишків;
імпорт замовлень;
імпорт клієнтів;
створення документів замовлення клієнта;
резервування товарів;
передавання fulfillment-даних;
передавання tracking number;
інтеграцію з доставкою;
інтеграцію з оплатами;
фіскалізацію;
журнал технічного обміну;
обробку webhooks.

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

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

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

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

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

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

Покупець оформлює замовлення в Shopify.
Shopify надсилає webhook або модуль отримує замовлення за розкладом.
K2 ERP перевіряє, чи замовлення вже не імпортоване.
Система створює замовлення клієнта.
Система зіставляє товари за SKU або variant ID.
Товари резервуються на складі.
Менеджер або система перевіряє оплату.
Формується складське відвантаження.
Створюється ТТН або інший документ доставки.
За потреби виконується фіскалізація.
Tracking number і fulfillment-дані передаються назад у Shopify.
Статус замовлення оновлюється.

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

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

shop domain;
Shopify store ID за потреби;
access token;
API version;
Shopify product ID;
Shopify variant ID;
inventory item ID;
Shopify location ID;
SKU;
статус синхронізації товару;
дату останнього оновлення товару;
Shopify order ID;
Shopify order name;
дату замовлення;
financial status;
fulfillment status;
Shopify customer ID;
email покупця;
телефон покупця;
shipping address;
billing address;
спосіб доставки;
спосіб оплати;
payment transaction ID;
tracking number;
fulfillment ID;
refund ID;
статус фіскалізації;
номер фіскального чека;
текст помилки API;
журнал запитів і відповідей;
кількість спроб синхронізації.

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

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

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

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

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

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

access token недійсний;
недостатньо API scopes;
магазин недоступний;
API-версія застаріла;
перевищено ліміт запитів;
товар не знайдено;
дублюється SKU;
не зіставлено variant;
не знайдено inventory item;
не зіставлена Shopify location;
не завантажується фото;
неправильна ціна;
неправильний залишок;
замовлення вже імпортоване;
товар із замовлення не знайдено в K2 ERP;
неправильний спосіб доставки;
неправильний спосіб оплати;
fulfillment не створено;
tracking number не передано;
webhook не пройшов перевірку;
помилка фіскалізації;
помилка повернення;
статус не оновився.

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

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

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

доступ до access token;
API scopes;
права користувачів;
журнал дій;
обмеження доступу до налаштувань;
шифрування секретів;
захист логів;
перевірку webhook-підписів;
резервне копіювання налаштувань;
блокування доступу звільнених працівників;
розмежування прав між менеджерами й адміністраторами;
контроль змін цін і залишків.

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

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

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

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

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

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

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

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

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

залежність від API Shopify;
потребу в access token;
потребу в правильних API scopes;
обмеження API rate limits;
потребу в правильному зіставленні товарів;
різницю між product і variant;
різницю між складами ERP і Shopify locations;
можливі помилки в SKU;
потребу в контролі залишків;
потребу в обробці дублювань;
потребу в тестуванні перед масовим експортом;
ризик оновлення неправильних цін;
ризик передавання неправильних залишків;
потребу в контролі персональних даних покупців.

Не плутати: K2 Модуль Shopify — це не просто імпорт замовлень. Повноцінна інтеграція має охоплювати товари, variants, ціни, залишки, locations, замовлення, клієнтів, оплати, fulfillment, повернення, фіскалізацію та журнал помилок.

Висновок

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

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

Джерела

Див. також

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

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

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

РРО

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

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

ДПС

ЕДО