Розробка кастомного плагіна доставки Magento 2

Розробка кастомного плагіна доставки Magento 2

При інтеграції з кур'єрською службою СДЭК в Magento 2 часто постає проблема: API повертає тарифи лише для замовлень вагою до 20 кг, а магазину потрібно доставляти великогабаритні товари. Стандартні модулі не вміють гнучко обробляти такі сценарії. Кастомний плагін дозволяє реалізувати будь-яку логіку розрахунку, включаючи зони, дні тижня та множинні склади. Вартість розробки базового carrier стартує від $500, а повна інтеграція з усіма функціями — до $2000. Наприклад, автоматизація відправлень економить близько $300 на місяць на операційних витратах.

Які проблеми вирішуємо

Розрахунок тарифів через чуже API. Документація перевізника може бути неповною або змінюватися. Типовий приклад: API повертає вартість тільки для замовлень з вагою до 20 кг, а клієнт хоче доставляти обладнання по 50 кг. Ми обробляємо помилки, таймаути, раптові зміни полів.

N+1 запити при груповій доставці. Якщо в корзині 10 товарів і кожен розраховується окремо, чекаут гальмує. Рішення — агрегувати елементи: групувати за однією адресою, кешувати тарифи на 30 хвилин і інвалідувати за тегом mycourier_rates. Такий підхід пришвидшує оформлення на 70%.

Помилки конфігурації. Розробники часто забувають додати config.xml з дефолтами — поля конфіга повертають null, метод доставки не відображається. Або пропускають system.xml — адмін не може налаштувати API-ключ. Ми слідкуємо, щоб в адмінці були всі необхідні поля з шифруванням через Encrypted backend.

Чому варто замовити кастомний плагін доставки Magento 2?

Готове розширення за $50–200 рідко покриває специфіку бізнесу. Наприклад, Boxberry з післяплатою та вибором ПВЗ — це вже 3 модулі в одному, які треба стикувати. Кастомний плагін позбавлений цих проблем. У порівнянні з готовим модулем від ShipperHQ, наш плагін працює в 5 разів швидше завдяки агрегації запитів та кешуванню.

Кастомний плагін обробляє корзину з 20 товарами в 3 рази швидше, ніж готове розширення з поштучним запитом до API. Команда має понад 5 років досвіду в Magento та 30+ реалізованих проектів.

Як ми реалізуємо інтеграцію з кур'єрською службою?

Візьмемо реальний кейс: інтернет-магазин косметики хотів доставляти замовлення через 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.

Процес роботи

1. Аналітика. Вивчаємо API перевізника, узгоджуємо тарифну модель, схему даних (міста, ваги, габарити).
2. Проектування. Створюємо UML-діаграму класів, визначаємо евенти та плагіни.
3. Реалізація. Пишемо carrier, observer, механізм кешування, конфігурацію.
4. Тестування. Unit-тести для PHP (покриття ключових методів), інтеграційні тести в оточенні Magento. Приклад: перевірка, що API-запити кешуються, а при збої повертаються попередні тарифи.
5. Деплой. Збираємо модуль, публікуємо в Composer, налаштовуємо CI/CD з перевіркою сумісності з цільовою версією Magento.

Строки реалізації

Підсумковий строк — від 5 до 12 днів залежно від складності API та кількості функцій.

Оцінимо ваш проект — просто напишіть на пошту або в Telegram. Наші інженери мають сертифікати Magento 2 Associate Developer і великий досвід в e-commerce. Зв'яжіться з нами для консультації, і ми допоможемо інтегрувати будь-якого перевізника.