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

Основи API

Цей розділ — для розробника, який підключає до WMS облікову чи ERP-систему. Тут описано, як ваш код входить у систему, які заголовки несе кожен запит і як читати відповіді. Наступні сторінки описують кожну операцію обміну.

WMS — хмарний сервіс: усі компанії працюють з одним сервісом за адресою https://app.wms.com.ua, і всі запити цього розділу надсилаються туди. Перед початком адміністратор вашої компанії налаштовує сторону WMS і передає вам три речі — див. контрольний список передачі:

  • код компанії (на екрані входу в Клієнт це поле Компанія);
  • технічний токен — довгостроковий секрет технічного користувача;
  • код зовнішньої системи — код, під яким зареєстровано вашу систему.

Опис API​

Сервіс публікує машиночитаний опис усього свого API. Інтеграційні ендпоінти зібрано під тегами, що починаються з Integrations. Опис опубліковано в тестовому середовищі:

Вхід​

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

POST /api/v1/auth/technical/jwt
Authorization: Bearer <технічний токен>
WMS-Tenant-Code: <код компанії>

Тіла в запиті немає. Відповідь:

{
  "accessToken": "eyJhbGciOi…",
  "expiresAt": "2026-10-27T10:15:00.123Z"
}
  • Токен доступу живе близько 10 хвилин. Зберігайте його й використовуйте повторно до моменту незадовго перед expiresAt, а тоді входьте знову.
  • Технічний користувач може одночасно мати лише кілька токенів доступу. Вхід перед кожним запитом витісняє токени інших ваших процесів, тож кешуйте токен.
  • Якщо запит отримав 401, токен доступу прострочився або його відкликано: увійдіть знову й повторіть запит один раз. Якщо 401 отримав сам вхід, технічний токен неправильний, прострочений або замінений — попросіть адміністратора видати новий (Видача токена).

Заголовки запиту​

ЗаголовокКолиЩо містить
Authorization: Bearer <токен доступу>кожен запиттокен доступу, отриманий під час входу
WMS-Tenant-Codeкожен запиткод компанії
Content-Type: application/jsonзапити з тіломусі тіла — JSON у кодуванні UTF-8
WMS-Idempotency-Keyзапити імпортуунікальний ключ цього запиту, щоб його повторення було безпечним; див. Імпорт
Accept-Languageза бажанняммова повідомлень про помилки, наприклад uk або en
WMS-Correlation-Idза бажаннямваш власний ідентифікатор запиту; вкажіть його, коли повідомляєте про проблему

Клієнт, на якому побудовано приклади​

Кожен приклад цього розділу спирається на невеликий клієнт нижче. Він входить у систему, кешує токен доступу, додає заголовки й повторює запит один раз після 401. Версії на JavaScript і Python беруть параметри підключення зі змінних оточення (WMS_BASE_URL, WMS_TENANT, WMS_TOKEN, WMS_EXTERNAL_SYSTEM); версія для 1С зберігає їх у структурі, яку створює НовоеПодключение. Ніколи не вписуйте технічний токен у вихідний код.

// WMS integration client: exchanges the technical token for a short-lived
// access token (JWT) and sends authorized requests. Node.js 18+, no dependencies.
const config = {
  baseUrl: process.env.WMS_BASE_URL, // e.g. https://app.wms.com.ua
  tenant: process.env.WMS_TENANT, // company code
  token: process.env.WMS_TOKEN, // technical token issued in the WMS Client
  externalSystem: process.env.WMS_EXTERNAL_SYSTEM, // external system code
};

let jwt = null; // {accessToken, renewAt}

async function getAccessToken() {
  if (jwt && Date.now() < jwt.renewAt) return jwt.accessToken;
  const res = await fetch(`${config.baseUrl}/api/v1/auth/technical/jwt`, {
    method: 'POST',
    headers: {Authorization: `Bearer ${config.token}`, 'WMS-Tenant-Code': config.tenant},
  });
  if (!res.ok) throw new Error(`WMS sign-in failed: HTTP ${res.status} ${await res.text()}`);
  const {accessToken, expiresAt} = await res.json();
  // Renew 30 seconds before the token expires.
  jwt = {accessToken, renewAt: Date.parse(expiresAt) - 30_000};
  return accessToken;
}

class WmsError extends Error {
  constructor(status, body) {
    const details = body?.errors?.map((e) => `${e.path || '(request)'}: ${e.message}`).join('; ');
    super(`WMS HTTP ${status}: ${body?.message ?? body}${details ? ` — ${details}` : ''}`);
    this.status = status;
    this.body = body;
  }
}

async function wmsRequest(method, path, {query = {}, body, idempotencyKey} = {}) {
  const url = new URL(config.baseUrl.replace(/\/$/, '') + path);
  for (const [name, value] of Object.entries(query)) {
    // Arrays become repeated parameters: entityTypes=A&entityTypes=B
    for (const item of [].concat(value ?? [])) url.searchParams.append(name, String(item));
  }
  const send = async () => {
    const headers = {
      Authorization: `Bearer ${await getAccessToken()}`,
      'WMS-Tenant-Code': config.tenant,
      Accept: 'application/json',
    };
    if (body !== undefined) headers['Content-Type'] = 'application/json';
    if (idempotencyKey) headers['WMS-Idempotency-Key'] = idempotencyKey;
    return fetch(url, {method, headers, body: body === undefined ? undefined : JSON.stringify(body)});
  };

  let res = await send();
  if (res.status === 401) {
    // The access token expired or was revoked: sign in again and repeat once.
    jwt = null;
    res = await send();
  }
  const text = await res.text();
  let data = text;
  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    // Some errors come back as plain text.
  }
  if (!res.ok) throw new WmsError(res.status, data);
  return {status: res.status, headers: res.headers, body: data};
}

Помилки​

Запит, який сервер відхиляє повністю, повертається зі статусом 4xx. Більшість помилок мають тіло JSON:

{
  "message": "INVALID_DATA_FORMAT",
  "errors": [
    {"path": "code", "message": "External system with code NOPE not found"}
  ]
}

path вказує на поле, що спричинило проблему (порожній path означає запит загалом). Деякі помилки натомість повертаються простим текстом, наприклад Limit must be between 1 and 500, тож не розраховуйте, що тіло завжди буде JSON. Тексти помилок залежать від заголовка Accept-Language.

СтатусЩо означаєЩо робити
400Запит некоректний: неправильне поле, значення поза межами, невідомий код зовнішньої системи.Виправте запит; повтор без змін дасть ту саму відповідь.
401Токена доступу немає, він прострочений або відкликаний.Увійдіть знову й повторіть один раз.
403Доступ заборонено: зовнішню систему вимкнено або їй бракує можливості, код компанії не збігається, або в ліцензії немає вільних технічних місць.Попросіть адміністратора перевірити зовнішню систему й технічного користувача.
404Такої адреси не існує.Перевірте шлях.
429Забагато запитів за короткий час.Зачекайте (відповідь підказує скільки) і повторіть.
5xxЗбій на боці сервера.Зачекайте й повторіть; для імпорту — з тим самим ключем ідемпотентності.

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