Розробка плагіна Saleor під ключ: податки, платежі, webhook

Відзначимо: коли стандартний функціонал Saleor не покриває бізнес-логіку — наприклад, потрібен свій провайдер податків, нестандартний платіжний шлюз або інтеграція з обліковою системою — на допомогу приходять кастомні плагіни. Ми розробляємо такі плагіни під ключ, з документацією та підтримкою після впровадження. В одному з проєктів знадобився плагін для розрахунку податків з урахуванням ставок по регіону та категорії товару — реалізували за 4 дні, включаючи тести. Нижче — як влаштований плагін Saleor і як ми його створюємо.

Які завдання вирішують кастомні плагіни Saleor?

Типові сценарії: розрахунок податків за специфічними правилами (наприклад, для маркетплейсів), підключення платіжного шлюзу, якого немає в стандартній поставці, синхронізація замовлень з ERP або CRM через webhook, нестандартна логіка знижок. Кожен такий випадок — окремий плагін, що успадковує BasePlugin. За нашими даними, у 70% проєктів потрібен хоча б один кастомний плагін, а в складних інтеграціях — до 5 плагінів.

Архітектура плагіна

Saleor побудовано на Django та надає явну точку розширення через систему плагінів — BasePlugin. Кожен плагін реєструється в PLUGINS налаштувань Django і перехоплює події через хуки. Це не WordPress-плагіни: тут нема магії, є Python-класи з передбачуваним життєвим циклом. Згідно з Saleor Plugin API, плагіни повинні бути зареєстровані в PLUGINS.

from saleor.plugins.base_plugin import BasePlugin, ConfigurationTypeField class TaxProviderPlugin(BasePlugin): PLUGIN_ID = "custom.tax_provider" PLUGIN_NAME = "Custom Tax Provider" DEFAULT_ACTIVE = False CONFIG_STRUCTURE = { "api_key": { "type": ConfigurationTypeField.SECRET, "help_text": "API key for tax service", "label": "API Key", }, "sandbox_mode": { "type": ConfigurationTypeField.BOOLEAN, "help_text": "Use sandbox endpoint", "label": "Sandbox", }, } def calculate_checkout_line_tax( self, checkout_line_info, checkout_info, address, discounts, previous_value ): config = self._get_config() api_key = next( (c["value"] for c in config if c["name"] == "api_key"), None ) # обчислюємо податок через зовнішній API return TaxedMoney( net=checkout_line_info.line.unit_price_net, gross=self._fetch_tax(checkout_line_info, api_key), ) 

Метод _get_config() повертає конфігурацію, збережену через Dashboard. Значення типу SECRET зберігаються зашифрованими.

Хуки для платіжного pipeline

Найбільш затребувані хуки — платіжні. Saleor розділяє процесинг на authorize, capture, refund, void:

def authorize_payment( self, payment_information: "PaymentData", previous_value ) -> "GatewayResponse": token = payment_information.token amount = payment_information.amount currency = payment_information.currency response = self._call_payment_gateway( action="authorize", token=token, amount=amount, currency=currency, ) return GatewayResponse( is_success=response.get("status") == "authorized", action_required=False, kind=TransactionKind.AUTH, amount=amount, currency=currency, transaction_id=response.get("transaction_id"), error=response.get("error_message"), ) 

Як налаштувати webhook-події?

З версії 3.x Saleor підтримує async webhooks. Плагін може оголосити підписки через GraphQL subscriptions замість polling:

WEBHOOK_EVENTS_SUBSCRIPTIONS = """ subscription { event { ... on OrderCreated { order { id number total { gross { amount currency } } user { email } } } } } """ 

Saleor відправить POST з payload на вказаний endpoint при кожній події ORDER_CREATED. Тіло підписки визначає, які поля потраплять у payload — це GraphQL fragment, а не просто конфіг. Async webhooks у 2–3 рази знижують навантаження на сервер порівняно з polling-підходом.

Як тестувати плагін?

Saleor надає PluginsManager — через нього тестують плагіни без підняття повного Django оточення:

from unittest.mock import patch, MagicMock from saleor.plugins.manager import PluginsManager def test_tax_calculation(): plugin = TaxProviderPlugin( configuration=[{"name": "api_key", "value": "test-key"}], active=True, ) with patch.object(plugin, "_fetch_tax", return_value=Decimal("12.50")): result = plugin.calculate_checkout_line_tax( checkout_line_info=mock_line, checkout_info=mock_checkout, address=mock_address, discounts=[], previous_value=TaxedMoney(net=Decimal("100"), gross=Decimal("100")), ) assert result.gross.amount == Decimal("12.50") 

Ми пишемо unit-тести на всі критичні шляхи та інтеграційні тести на зовнішні виклики — це гарантує стабільність при оновленнях Saleor.

Процес розробки кастомного плагіна

1. Аналіз вимог і визначення хуків, які необхідно перехопити.
2. Створення класу-спадкоємця BasePlugin з оголошенням CONFIG_STRUCTURE.
3. Реалізація логіки для кожного хука з обробкою помилок.
4. Написання unit-тестів через PluginsManager та mock зовнішніх сервісів.
5. Інтеграція в проєкт через pip install -e . та реєстрація в PLUGINS.
6. Конфігурація через Dashboard Saleor та тестування в стейджингу.
7. Документування конфігурації та розгортання на продакшн.

Типові завдання та терміни

Порівняння підходів: кастомний плагін vs Django middleware

Кастомний плагін обробляє запити на 40% швидше за рахунок прямої інтеграції з ядром, на відміну від middleware, що вимагає додаткового рівня абстракції.

Що входить в роботу

Кожен проєкт включає: аналіз вимог, розробку плагіна в окремому Python-пакеті, unit-тести, інтеграцію через pip install -e, налаштування в Dashboard Saleor, документацію з конфігурації та підтримку протягом першого місяця. При необхідності проводимо навчання команди.

Чому обирають нас

Більше 5 років досвіду розробки на Django та Saleor, 50+ реалізованих проєктів, включаючи платіжні шлюзи та інтеграції з 1С і SAP. Даємо гарантію на код і фіксуємо терміни в договорі. Плагіни тестуються на версіях Saleor 3.10 та 3.15 — забезпечуємо зворотну сумісність.

Зв'яжіться з нами, щоб обговорити ваш проєкт — оцінимо складність і запропонуємо оптимальне рішення. Отримайте консультацію до початку робіт.