Начало работы с ApiShip для Medusa

В этом руководстве вы узнаете, как установить и настроить плагин ApiShip для Medusa.

• Medusa v2.17.2 или новее
• Node.js v22.23.4, v24.22.1, v26.12.1 или новее
• Аккаунт ApiShip – зарегистрируйтесь или войдите
• Модуль интеграций

yarn add @gorgo/medusa-integration @gorgo/medusa-fulfillment-apiship

Зарегистрируйте плагин и два его провайдера в medusa-config.ts вашего приложения Medusa:

medusa-config.ts
1// ...
2const APISHIP_INTEGRATION_ID = "apiship-1"
3
4module.exports = defineConfig({
5  // ...
6  plugins: [
7    // ...
8    {
9      resolve: "@gorgo/medusa-integration",
10      options: {
11        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
12        providers: [
13          {
14            resolve: "@gorgo/medusa-fulfillment-apiship/providers/integration-apiship",
15            id: APISHIP_INTEGRATION_ID,
16            options: {},
17          },
18        ],
19      },
20    },
21    {
22      resolve: "@gorgo/medusa-fulfillment-apiship",
23      options: {},
24    },
25  ],
26  modules: [
27    // ...
28    {
29      resolve: "@medusajs/medusa/fulfillment",
30      options: {
31        providers: [
32          {
33            resolve: "@medusajs/medusa/fulfillment-manual",
34            id: "manual",
35          },
36          {
37            resolve: "@gorgo/medusa-fulfillment-apiship/providers/fulfillment-apiship",
38            id: "apiship",
39            options: {
40              id: APISHIP_INTEGRATION_ID,
41            },
42          },
43        ],
44      },
45    },
46  ],
47})

Конфигурация регистрирует три вещи:

• Провайдер интеграции в @gorgo/medusa-integration. Его id, apiship-1, задаёт имя инстанса, поэтому его настройки хранятся под int_apiship_apiship-1 и открываются в Medusa Admin в Настройки → Интеграции → ApiShip.
• Сам плагин. Без этой записи провайдер продолжает работать, но Medusa Admin не загружает страницу настроек плагина, виджет служб доставки и переводы.
• Провайдер фулфилмента в @medusajs/medusa/fulfillment. Его options.id должен совпадать с id провайдера интеграции, так он находит свои настройки. Способы доставки, которые вы с ним создаёте, получают провайдер apiship_apiship.

Список провайдеров в @medusajs/medusa/fulfillment заменяет список Medusa по умолчанию, поэтому конфигурация заново указывает ручной провайдер. Без него перестают работать способы доставки с manual_manual.

Добавьте в переменные окружения ключ, которым Модуль интеграций шифрует API-токен:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret