Типичный 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;
Пошаговый процесс создания кастомного провайдера:
- Разобрать API перевозчика и составить схему запросов.
- Создать класс-клиент с методами для каждого endpoint.
- Реализовать AbstractFulfillmentService с переопределением ключевых методов.
- Настроить webhook-роуты для получения событий.
- Написать unit-тесты и протестировать интеграцию на staging.
Пример архитектуры провайдера
Архитектура включает три слоя: слой интеграции (API клиент), слой бизнес-логики (сервис), слой представления (webhook роуты). Каждый слой тестируется отдельно, а интеграционные тесты покрывают все сценарии работы с перевозчиком.Для production мы добавляем мониторинг через Grafana и алерты в Telegram при падении API перевозчика или ошибках конвертации данных.
Сравнение: manual vs кастомный провайдер
| Параметр | Manual провайдер | Кастомный провайдер |
|---|---|---|
| Расчет тарифов | Только фиксированная цена | Динамический расчет по API перевозчика |
| Создание отправления | Вручную в админке | Автоматически при заказе |
| Отслеживание | Нет | Webhook + обновление статусов |
| Возвраты | Нет | Полная поддержка отмены |
Этапы и сроки реализации
| Этап | Описание | Длительность |
|---|---|---|
| Анализ API | Изучение документации, тестирование endpoints | 0,5 дня |
| Проектирование | Схема классов, обработка ошибок, поддержка v1/v2 | 1 день |
| Реализация | Пакет с unit-тестами и интеграционными тестами | 2–3 дня |
| Тестирование | На staging с реальными заказами | 1 день |
| Деплой и мониторинг | Разворот в production, алерты | 0,5 дня |
- Базовая интеграция (один перевозчик, без возвратов): 3–5 дней.
- Добавление webhook и трекинга: +1–2 дня.
- Полноценный npm-пакет с поддержкой Medusa v1 и v2: 5–7 дней.
Что входит в работу
- Исходный код провайдера (TypeScript).
- Конфигурация для
medusa-config.js. - Документация по установке и настройке.
- Обучение команды (1 час).
- Гарантийная поддержка 1 месяц.
Закажите интеграцию, и мы автоматизируем вашу логистику за неделю. Получите консультацию инженера и точную оценку стоимости. Свяжитесь с нами для бесплатного аудита вашего проекта — мы оценим сложность и предложим оптимальное решение.