Интеграция служб доставки в 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%, а средняя экономия на каждом возврате составляет до $4–6 за счет автоматизации.

Как мы это делаем

Используем 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 месяц.

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