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

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