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

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

Какие задачи решают кастомные плагины Saleor?

Типичные сценарии: расчёт налогов по специфическим правилам (например, для маркетплейсов), подключение платежного шлюза, которого нет в стандартной поставке, синхронизация заказов с ERP или CRM через webhook, нестандартная логика скидок. Каждый такой случай — отдельный плагин, наследующий BasePlugin. По нашим данным, в 70% проектов требуется хотя бы один кастомный плагин, а в сложных интеграциях — до 5 плагинов. Стоимость варьируется от $300–800 в зависимости от сложности.

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

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 — обеспечиваем обратную совместимость.

Свяжитесь с нами, чтобы обсудить ваш проект — оценим сложность и предложим оптимальное решение. Получите консультацию до начала работ.