Формування payload

Інтеграційне API не має окремого опису кожного типу даних. Payload має таку саму структуру, як у звичайному API WMS, яким користуються застосунки WMS. Відрізняється лише запис ідентифікаторів: ваша система використовує власні коди, а WMS їх перекладає.

Де знайти структуру

Знайдіть тип даних на сторінці Типи даних інтеграції.
Його розділ посилається на дві операції звичайного API у Swagger:
- Що ви надсилаєте — операція створення; її тіло запиту — це структура payload імпорту. Для приймання: POST /api/v1/inbound/receipts (ReceiptIncomeDto).
- Що ви читаєте — операція читання; її відповідь — це структура payload стрічки змін. Для приймання: GET /api/v1/inbound/receipts/{id} (ReceiptFullResponseDto).
Візьміть поля з цієї схеми й застосуйте правила нижче до кожного поля-ідентифікатора.

Поля, які сервер заповнює сам, як-от номер документа чи дата створення, можна не передавати. Поля, яких немає в схемі, ігноруються.

Ідентифікатори в тому, що ви надсилаєте

Власний ідентифікатор запису

id — це ваш ідентифікатор запису: код, GUID чи ключ, який запис має у вашій системі. WMS запам'ятовує, який її запис йому відповідає, тож зберігати ідентифікатори WMS вам не потрібно.

{
  "id": "erp-prod-cement-m400",
  "name": "Цемент М400",
  "categoryId": "erp-cat-cement",
  "uomId": "erp-uom-kg"
}

Ідентифікатори нечутливі до регістру: ABC-1 і abc-1 — той самий запис. WMS зберігає їх у нижньому регістрі.
Довідники (товари, контрагенти…) зіставляються в межах зовнішньої системи: дві системи можуть мати однаковий код для різних записів.
Документи зіставляються в межах компанії: id документа — його ідентифікатор для всіх систем.

Посилання на інші записи

Кожне поле, що вказує на інший запис (categoryId, warehouseId, lines[].productId тощо), приймає одну з двох форм:

ваш ідентифікатор цього запису, рядком — "productId": "erp-prod-cement-m400";
ідентифікатор WMS, загорнутий в об'єкт — "warehouseId": {"wmsId": "0199a7c4-…"}. Використовуйте його для записів, яких ваша система ніколи не надсилала, наприклад для складів, налаштованих у WMS.

Обидві форми можна змішувати в одному payload, і вони працюють у вкладених списках на кшталт lines і containers. Запис, на який ви посилаєтеся своїм ідентифікатором, має бути вже відомий WMS — надісланий раніше або раніше в тому самому запиті імпорту. Інакше елемент не пройде з помилкою на цьому полі.

Службові поля

Ці поля розташовані на верхньому рівні payload поруч із даними. Як дані вони ніколи не зберігаються.

Поле	Типи даних	Що робить
`_representation`	довідники	Назва, під якою запис показується у WMS. За замовчуванням — `name`; обов'язкове, якщо в payload немає `name`.
`_key`	довідники	Поля, за якими знаходять наявний запис WMS, коли ваш `id` ще ні з чим не пов'язаний, наприклад `"code"` або `["code", "type"]`. Використовується в режимах Лише зіставити і Доповнити.
`_updateFields`	усі	Поля, які треба змінити в наявному записі; решта лишаються як були. Обов'язкове для Доповнити.
`_wmsId`	усі	Ідентифікатор цього запису у WMS, якщо ви його знаєте. Має пріоритет над `id` і пов'язує їх.
`deleted`	довідники	`true` видаляє запис, `false` відновлює (в елементі з режимом Створити або оновити).

Ідентифікатори в тому, що ви читаєте

У payload, які надсилає вам WMS (стрічка змін, ресинхронізація, залишки на дату), кожне поле-ідентифікатор — це пара:

{
  "id": {"int": "0199a7c4-1f2e-7a10-9b3c-5d6e7f8091a2", "ext": "erp-prod-cement-m400"},
  "uomId": {"int": "0199a7c4-2a3b-7c4d-8e5f-6a7b8c9d0e1f", "ext": "erp-uom-kg"},
  "categoryId": {"int": "0199a7c4-3b4c-7d5e-9f60-7b8c9d0e1f2a", "ext": null}
}

int — ідентифікатор у WMS.
ext — ваш ідентифікатор цього запису в нижньому регістрі або null, якщо у вашій системі його немає: запис створено у WMS, або це щось внутрішнє для WMS, наприклад користувач.

Знаходьте запис у своїй системі за ext. Якщо ext дорівнює null, зберігайте зв'язок між int і своїм записом і передавайте int назад як {"wmsId": …} або _wmsId, коли посилаєтеся на нього.

Числові ідентифікатори — штрихкод, номер рядка — лишаються звичайними числами.

Усе це на прикладі одного документа — у розділі Приклад: ідентифікатори в прийманні.

Де знайти структуру​

Ідентифікатори в тому, що ви надсилаєте​

Власний ідентифікатор запису​

Посилання на інші записи​

Службові поля​

Ідентифікатори в тому, що ви читаєте​