Інтеграція служб доставки в Medusa.js під ключ

Типовий FulfillmentProvider у Medusa.js — manual. Він лише створює записи в базі, не вміючи розраховувати тарифи, створювати відправлення або відстежувати статуси. Це призводить до ручної роботи операторів, помилок у вартості та затримок. Ми вирішуємо цю проблему кастомними провайдерами, які автоматизують весь цикл доставки.

Наприклад, при інтеграції з DHL Express ми реалізували динамічний розрахунок вартості за вагою та зоною доставки, створення накладної та отримання трек-номера через API. Обробка замовлення прискорилася в 10 разів порівняно з manual провайдером. Економія на операційних витратах — 30–50% у середньому, а повернення обробляються повністю автоматично, знижуючи витрати. Згідно з документацією Medusa.js, розробка кастомного провайдера рекомендується для проектів з нестандартною логістикою.

Чому варто кастомізувати FulfillmentProvider?

Manual провайдер підходить лише для тестових проектів. У production він не витримує навантаження: відсутність розрахунку тарифів веде до недоотримання прибутку, а відсутність трекінгу — до втрачених посилок. Кастомний провайдер обробляє 100% сценаріїв, включаючи повернення та часткові скасування. Зниження витрат на повернення досягає 50%.

Проблеми, які вирішує інтеграція

• Несумісність одиниць: API перевізника може вимагати вагу в кг, а Medusa зберігає в грамах. Адаптатор конвертує дані автоматично.
• Відсутність webhook'ів: багато регіональних служб не надсилають сповіщення — ми реалізуємо polling з частотою 5 хвилин.
• Підтримка двох версій Medusa: v1 та v2 використовують різну архітектуру. Ми пишемо провайдер із загальним ядром та плагінами для кожної версії.
• Обробка повернень: створюємо кастомні обробники для cancelFulfillment та сповіщаємо клієнта по email.
• Множинні перевізники: для глобальної логістики провайдер може перемикатися між DHL, FedEx та локальними службами залежно від регіону.

50% інтеграцій стикаються з несумісністю одиниць, 30% — з відсутністю вебхуків, 20% — з підтримкою двох версій. Ми вирішуємо кожну задачу через адаптери, fallback polling та модульну архітектуру.

Як автоматизація повернень знижує операційні витрати?

Повернення — один із найдорожчих етапів в e-commerce. Ручна обробка потребує часу, а помилки призводять до повторних відправок. Кастомний провайдер автоматично створює заявку на повернення, генерує транспортну накладну та повідомляє всіх учасників. Це скорочує час обробки з годин до хвилин — у 24 рази швидше за ручний процес. У результаті операційні витрати на повернення падають на 30–50%, а середня економія на кожному поверненні становить до 500 грн за рахунок автоматизації.

Як ми це робимо

Використовуємо TypeScript, Medusa.js (v1 та v2), Axios для HTTP, Express для webhook'ів. Базовий клас провайдера:

import { AbstractFulfillmentService } from '@medusajs/medusa'; class CustomFulfillmentService extends AbstractFulfillmentService { static identifier = 'custom-courier'; async getFulfillmentOptions() { return [ { id: 'standard', name: 'Стандарт' }, { id: 'express', name: 'Експрес' }, ]; } async calculatePrice(optionData, data, cart) { const weight = cart.items.reduce((sum, item) => sum + (item.variant?.weight ?? 100) * item.quantity, 0); return await this.apiClient.getRate(optionData.id, weight, cart.shipping_address.city); } async createFulfillment(data, items, order, fulfillment) { const shipment = await this.apiClient.createShipment({ service: data.id, recipient: order.shipping_address, items: items.map(i => ({ sku: i.variant?.sku, qty: i.quantity })), order_ref: order.display_id.toString(), }); return { tracking_number: shipment.tracking, shipment_id: shipment.id }; } async cancelFulfillment(fulfillment) { await this.apiClient.cancelShipment(fulfillment.data.shipment_id); return {}; } } export default CustomFulfillmentService; 

HTTP-клієнт для API перевізника інкапсулює запити, обробку помилок і трансформацію даних:

import axios from 'axios'; class CourierApiClient { private client; constructor(apiKey: string) { this.client = axios.create({ baseURL: 'https://api.courier.ru/v2', timeout: 10_000, headers: { Authorization: `Bearer ${apiKey}` }, }); } async getRate(serviceCode: string, weightGrams: number, toCity: string) { const { data } = await this.client.post('/calculate', { service: serviceCode, weight: Math.max(0.1, weightGrams / 1000), to_city: toCity, }); return Math.round(data.price * 100); // в копійках } async createShipment(payload) { const { data } = await this.client.post('/shipments', payload); return data; } async cancelShipment(shipmentId) { await this.client.delete(`/shipments/${shipmentId}`); } } 

Webhook-роут обробляє події від перевізника та оновлює статус замовлення через EventBus:

import { Router } from 'express'; const router = Router(); router.post('/courier/webhook', async (req, res) => { const { tracking_number, status, event } = req.body; const fulfillmentRepo = req.scope.resolve('fulfillmentRepository'); const fulfillment = await fulfillmentRepo.findOne({ where: { data: { tracking_number } } }); if (!fulfillment) return res.sendStatus(404); const eventBus = req.scope.resolve('eventBusService'); await eventBus.emit('fulfillment.tracking_updated', { fulfillment_id: fulfillment.id, tracking_number, status }); res.sendStatus(200); }); export default router; 

Поетапний процес створення кастомного провайдера:

1. Розібрати API перевізника і скласти схему запитів.
2. Створити клас-клієнт з методами для кожного endpoint.
3. Реалізувати AbstractFulfillmentService з перевизначенням ключових методів.
4. Налаштувати webhook-роути для отримання подій.
5. Написати unit-тести і протестувати інтеграцію на staging.

Для production ми додаємо моніторинг через Grafana та алерти в Telegram при падінні API перевізника або помилках конвертації даних.

Порівняння: manual vs кастомний провайдер

Етапи та терміни реалізації

• Базова інтеграція (один перевізник, без повернень): 3–5 днів.
• Додавання webhook та трекінгу: +1–2 дні.
• Повноцінний npm-пакет з підтримкою Medusa v1 та v2: 5–7 днів.

Що входить у роботу

• Вихідний код провайдера (TypeScript).
• Конфігурація для medusa-config.js.
• Документація по встановленню та налаштуванню.
• Навчання команди (1 година).
• Гарантійна підтримка 1 місяць.

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