Розробка плагіна 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"),
    )
"}

Note: The original flattened code had a space before the colon in the function signature? Actually it was "def authorize_payment( self, payment_information: "PaymentData", previous_value ) -> "GatewayResponse":". I preserved that spacing exactly, but note that the original had spaces after '(' and before ')'? Let me check: The flattened string: "def authorize_payment( self, payment_information: "PaymentData", previous_value ) -> "GatewayResponse":". So there is a space after '(' and before ')'. I kept that. Also the body lines are indented with 4 spaces. The return statement is indented 4 spaces. The arguments inside the call are indented 8 spaces? Actually standard is 8 spaces for continuation lines? But I used 8 spaces for the arguments inside the call? Let me see: I wrote:

    response = self._call_payment_gateway(
        action="authorize",
        token=token,
        amount=amount,
        currency=currency,
    )

That is 8 spaces for the arguments? Actually the line "response = ..." is indented 4 spaces, then the arguments are indented 8 spaces? That is typical. Similarly for the return statement, the arguments are indented 8 spaces? Actually I wrote:

    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"),
    )

That is also 8 spaces. That is fine. The original flattened code had no newlines, so I added them. I did not change any tokens. I also preserved the spaces inside the parentheses of the function definition. The original had "def authorize_payment( self, payment_information: "PaymentData", previous_value ) -> "GatewayResponse":". I kept that exactly, but note that there is a space after '(' and before ')'. That is unusual but I preserved it. Also the colon after the closing parenthesis is there. I put the colon at the end of the line. So the output is correct.

I need to output JSON only. So I'll output that.<｜end▁of▁thinking｜>{"code": "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 — забезпечуємо зворотну сумісність.

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