Разработка кастомного плагина доставки Magento 2
При интеграции с курьерской службой СДЭК в Magento 2 часто возникает проблема: API возвращает тарифы только для заказов весом до 20 кг, а магазину нужно доставлять крупногабаритные товары. Стандартные модули не умеют гибко обрабатывать такие сценарии. Кастомный плагин позволяет реализовать любую логику расчёта, включая зоны, дни недели и множественные склады.
Какие проблемы решаем
Расчёт тарифов через чужое API. Документация перевозчика может быть неполной или меняться. Типичный пример: API возвращает стоимость только для заказов с весом до 20 кг, а клиент хочет доставлять оборудование по 50 кг. Мы обрабатываем ошибки, таймауты, внезапные изменения полей.
N+1 запросы при групповой доставке. Если в корзине 10 товаров и каждый рассчитывается отдельно — чекаут тормозит. Решение — агрегировать элементы: группировать по одному адресу, кешировать тарифы на 30 минут и инвалидировать по тэгу mycourier_rates.
Ошибки конфигурации. Разработчики часто забывают добавить config.xml с дефолтами — поля конфига возвращают null, метод доставки не отображается. Или пропускают system.xml — админ не может настроить API-ключ. Мы следим за тем, чтобы в админке были все необходимые поля с шифрованием через Encrypted backend.
Почему стоит заказать кастомный плагин доставки Magento 2?
Готовое расширение за $50–200 редко покрывает специфику бизнеса. Например, Boxberry с наложенным платежом и выбором ПВЗ — это уже 3 модуля в одном, которые надо стыковать. Кастомный плагин лишён этих проблем:
| Критерий | Встроенные/готовые | Кастомный плагин |
|---|---|---|
| Поддержка локальных перевозчиков | Только глобальные (UPS и т.д.) | Любой по API |
| Гибкость тарификации | Фиксированная таблица или вес | Любая формула: зоны, день недели, стоимость товара |
| Интеграция с WMS/CMS | Нет | Через REST/SOAP, очереди RabbitMQ, файловый обмен |
| UI-компоненты чекаута | Нет | Выбор ПВЗ, дата доставки, калькулятор |
| Производительность | Стандартная | Кеширование, агрегация, асинхронные запросы |
Кастомный плагин обрабатывает корзину с 20 товарами в 3 раза быстрее, чем готовое расширение с поштучным запросом к API.
Как мы реализуем интеграцию с курьерской службой?
Возьмём реальный кейс: интернет-магазин косметики хотел доставлять заказы через DPD с расчётом стоимости по весу и габаритам. Стандартных решений не было — DPD даёт только API.
Архитектура модуля. Класс Vendor\MyCourier\Model\Carrier\MyCourier наследует \Magento\Shipping\Model\Carrier\AbstractCarrier (см. документацию Magento). В методе collectRates формируем запрос к DPD: передаём вес, город, почтовый индекс. Используем \Magento\Framework\HTTP\Client\Curl — он встроен в Magento 2, не требует дополнительных зависимостей.
<?php
namespace Vendor\MyCourier\Model\Carrier;
use Magento\Quote\Model\Quote\Address\RateRequest;
use Magento\Shipping\Model\Carrier\AbstractCarrier;
use Magento\Shipping\Model\Carrier\CarrierInterface;
use Magento\Shipping\Model\Rate\Result;
class MyCourier extends AbstractCarrier implements CarrierInterface
{
protected $_code = 'mycourier';
public function collectRates(RateRequest $request): ?Result
{
if (!$this->getConfigFlag('active')) {
return null;
}
/** @var Result $result */
$result = $this->_rateResultFactory->create();
$rates = $this->fetchRatesFromApi($request);
foreach ($rates as $rateData) {
$method = $this->_rateMethodFactory->create();
$method->setCarrier($this->_code);
$method->setCarrierTitle($this->getConfigData('title'));
$method->setMethod($rateData['code']);
$method->setMethodTitle($rateData['name']);
$method->setPrice($rateData['price']);
$method->setCost($rateData['price']);
$result->append($method);
}
return $result;
}
private function fetchRatesFromApi(RateRequest $request): array
{
$apiKey = $this->getConfigData('api_key');
$fromCity = $this->getConfigData('from_city');
$toCity = $request->getDestCity();
$postcode = $request->getDestPostcode();
$weight = 0;
foreach ($request->getAllItems() as $item) {
if ($item->getParentItem()) {
continue;
}
$weight += $item->getWeight() * $item->getQty();
}
$payload = json_encode([
'from' => $fromCity,
'to_city' => $toCity,
'postcode' => $postcode,
'weight' => max(0.1, $weight),
'currency' => $request->getPackageCurrency()->getCurrencyCode(),
]);
$this->_curl->addHeader('Authorization', 'Bearer ' . $apiKey);
$this->_curl->addHeader('Content-Type', 'application/json');
$this->_curl->setTimeout(10);
try {
$this->_curl->post('https://api.mycourier.ru/v2/rates', $payload);
$body = $this->_curl->getBody();
$status = $this->_curl->getStatus();
} catch (\Exception $e) {
$this->_logger->error('MyCourier API error: ' . $e->getMessage());
return [];
}
if ($status !== 200) {
return [];
}
$data = json_decode($body, true);
return $data['services'] ?? [];
}
public function getAllowedMethods(): array
{
return [$this->_code => $this->getConfigData('title')];
}
}
Конфигурация. config.xml задаёт дефолты, system.xml — форму в админке. API-ключ шифруется через \Magento\Config\Model\Config\Backend\Encrypted.
Кеширование тарифов. Используем CacheInterface с тэгом mycourier_rates. Время жизни — 30 минут. Это снимает нагрузку с API перевозчика и ускоряет чекаут.
Обработка создания отправления. После оплаты (событие sales_order_invoice_pay) observer CreateShipment вызывает API перевозчика для создания заказа, получает трек-номер и автоматически создаёт shipment в Magento. Это исключает ручной ввод.
UI-компонент выбора ПВЗ. Добавляем поле через checkout_index_index.xml. Компонент Vendor_MyCourier/js/pvz-selector загружает список пунктов выдачи и сохраняет выбранный в адрес заказа.
Что входит в разработку кастомного плагина доставки?
- Модуль с исходным кодом в закрытом репозитории.
- Документация: описание конфигурации, архитектуры, инструкция по обновлению.
- Настройка прав доступа к репозиторию.
- Обучение команды: как менять тарифы, добавлять новые методы доставки.
- Гарантийная поддержка 6 месяцев (исправление ошибок, адаптация под обновления API).
- Пост-релизная помощь при деплое на production.
Процесс работы
- Аналитика. Изучаем API перевозчика, согласовываем тарифную модель, схему данных (города, веса, габариты).
- Проектирование. Создаём UML-диаграмму классов, определяем эвенты и плагины.
- Реализация. Пишем carrier, observer, механизм кеширования, конфигурацию.
- Тестирование. Unit-тесты для PHP (покрытие ключевых методов), интеграционные тесты в окружении Magento. Пример: проверка, что API-запросы кешируются, а при сбое возвращаются предыдущие тарифы.
- Деплой. Собираем модуль, публикуем в Composer, настраиваем CI/CD с проверкой совместимости с целевой версией Magento.
Сроки реализации
| Этап | Срок (рабочие дни) |
|---|---|
| Базовый carrier с расчётом тарифов через API | 3–4 |
| Observer отправления + трек-номер | 2–3 |
| UI-компонент ПВЗ | 2–3 |
| Интеграция с MSI (multi-source inventory) | 3–5 |
| Тестирование и деплой | 2–3 |
Итоговый срок — от 5 до 12 дней в зависимости от сложности API и количества фич.
Типичные ошибки при создании shipping carrier
- Забывают добавить
system.xml— поле API-ключа не отображается в админке. - Не указывают дефолты в
config.xml— при активации модуля метод доставки не виден. - Не кешируют тарифы — каждый запрос к чекауту вызывает API, что замедляет работу.
- Не обрабатывают ошибки API — при недоступности перевозчика чекаут падает с 500-й ошибкой.
Оценим ваш проект бесплатно — просто напишите на почту или в Telegram. Наши инженеры имеют сертификаты Magento 2 Associate Developer и большой опыт в e-commerce. Свяжитесь с нами для консультации, и мы поможем интегрировать любого перевозчика.