Интеграция служб доставки в 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 месяц.

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