Перейти до основного вмісту

Імпорт

Ваша система надсилає до WMS довідники й документи через один ендпоінт. Один запит може містити елементи різних типів у різних режимах імпорту:

POST /api/v1/integrations/import
WMS-Idempotency-Key: 6f1c2b7e-3d4a-4c1b-9a8e-2f5d7c9b1e04
{
  "externalSystemCode": "ERP_MAIN",
  "items": [
    {
      "entityType": "PARTY",
      "importMode": "UPSERT",
      "payload": {"id": "sup-0001", "name": "Northwind Supplies"}
    },
    {
      "entityType": "PRODUCT",
      "importMode": "UPSERT",
      "payload": {"id": "prod-0017", "name": "Цемент М400", "uomId": "uom-bag"}
    }
  ]
}
  • externalSystemCode — код вашої зовнішньої системи.
  • entityType — тип даних елемента.
  • importMode — що з ним зробити; обов'язковий для кожного елемента.
  • payload — дані, сформовані як описано у Формуванні payload.

Щоб надсилати довідники, системі потрібна можливість Імпорт довідників, а щоб надсилати документи — Імпорт документів.

Як обробляються елементи​

  • По порядку. Елементи застосовуються один за одним у порядку масиву. Ставте запис перед елементами, що на нього посилаються: товар — перед прийманням, у якому його приймають. Посилання на запис, надісланий раніше в тому самому запиті, працює.
  • По одному. Кожен елемент зберігається окремо. Якщо один елемент не пройшов, решта все одно зберігаються; нічого не відкочується.
  • У будь-якому поєднанні. Один запит може змішувати типи даних, довідники й документи та режими імпорту. Тримайте розмір запиту в межах кількох сотень елементів.

Відповідь​

Відповідь — 200, навіть якщо частина елементів не пройшла. Вона звітує про кожен елемент:

{
  "externalSystemId": "01a17a5d-5148-71bf-8935-79c3016fbf5c",
  "summary": {
    "PARTY": {"created": 1, "updated": 0, "skipped": 0, "deleted": 0, "restored": 0},
    "PRODUCT": {"created": 0, "updated": 0, "skipped": 1, "deleted": 0, "restored": 0}
  },
  "results": [
    {
      "itemIndex": 0,
      "entityType": "PARTY",
      "status": "CREATED",
      "internalEntityId": "01a17a69-a738-732f-9880-39fe2ce9783a",
      "errors": []
    },
    {
      "itemIndex": 1,
      "entityType": "PRODUCT",
      "status": "SKIPPED",
      "errors": [
        {
          "path": "uomId",
          "message": "External reference was not found for UNIT_OF_MEASURE with external id `uom-bag`"
        }
      ]
    }
  ],
  "processedAt": "2026-10-27T09:51:46.985Z"
}
  • results[].itemIndex — позиція елемента у вашому масиві items.
  • status — що сталося; див. Статуси елементів імпорту.
  • internalEntityId — ідентифікатор запису у WMS. Зберігати його не обов'язково: WMS уже знає ваш id.
  • errors — порожній, якщо елемент пройшов. Інакше кожна помилка має path усередині payload елемента (наприклад uomId або lines[0].productId) і message. Елемент із помилками нічого не змінив; виправте його й надішліть знову.

Повторення запиту​

Кожен запит імпорту несе заголовок WMS-Idempotency-Key — унікальний рядок, наприклад UUID. Якщо ви не знаєте, чи дійшов запит до сервера (тайм-аут, обірване з'єднання, відповідь 5xx), надішліть той самий запит із тим самим ключем ще раз:

  • якщо перший запит уже оброблено, сервер не застосовує його вдруге, а повертає збережену відповідь із заголовком WMS-Idempotency-Replayed: true;
  • якщо ні — сервер обробить його зараз.

Сервер пам'ятає ключ близько 10 хвилин. Для кожного нового запиту використовуйте новий ключ: той самий ключ з іншими елементами поверне відповідь першого запиту.

Видалення​

Щоб видалити запис, надішліть його в режимі Видалити; у payload достатньо id. Довідник також можна видалити чи відновити через "deleted": true або false в елементі з режимом Створити або оновити. Видалити запис може лише та система, що його надіслала.

Код​

Функція надсилає один запит і перелічує елементи, що не пройшли. Вона використовує клієнт з Основ API.

import {randomUUID} from 'node:crypto';

// Sends one import request. `items` is an array of
// {entityType, importMode, payload}; items are applied in this order.
// Returns the whole answer and the items that failed, with their errors.
async function importItems(items, idempotencyKey = randomUUID()) {
  // Keep the key if you may need to repeat this exact request (e.g. after a timeout).
  const {body} = await wmsRequest('POST', '/api/v1/integrations/import', {
    body: {externalSystemCode: config.externalSystem, items},
    idempotencyKey,
  });
  const failed = body.results
    .filter((result) => result.errors.length > 0)
    .map((result) => ({item: items[result.itemIndex], result}));
  for (const {item, result} of failed) {
    const reasons = result.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
    console.warn(`${item.entityType} ${item.payload.id} was not imported — ${reasons}`);
  }
  return {response: body, failed};
}