API K2 ERP

API K2 ERP — це програмний інтерфейс для взаємодії зовнішніх систем, модулів, сервісів, сайтів, мобільних застосунків, інтеграційних конекторів та внутрішніх компонентів із системою K2 ERP.

API K2 ERP використовується для автоматизації обміну даними: створення документів, отримання довідників, синхронізації товарів, клієнтів, замовлень, оплат, залишків, бухгалтерських операцій, статусів, інтеграційних подій і результатів обробки.

Важливо: API K2 ERP — це не окремий модуль обліку, а технічний інтерфейс доступу до функцій і даних ERP. Через API зовнішні системи можуть читати, створювати або оновлювати дані відповідно до прав доступу та бізнес-правил.

Загальний опис

K2 ERP може містити багато функціональних модулів: продажі, закупівлі, склад, виробництво, зарплата, основні засоби, бухгалтерія, документообіг, інтеграції з банками, ДПС, ЕДО, РРО, ПРРО, маркетплейсами, інтернет-магазинами та логістичними сервісами.

API K2 ERP потрібне для того, щоб ці модулі могли взаємодіяти із зовнішніми системами без ручного дублювання даних. Наприклад, інтернет-магазин може передати замовлення в K2 ERP, платіжний сервіс — повідомити про оплату, складська система — оновити залишки, а модуль ПРРО — повернути фіскальний номер чека.

API може бути реалізоване як REST API, GraphQL API, WebSocket API, RPC-інтерфейс, webhook-механізм або внутрішній сервісний інтерфейс між модулями.

Зверніть увагу: API K2 ERP має працювати не напряму з таблицями бази даних, а через бізнес-логіку системи. Це дозволяє перевіряти права доступу, статуси документів, обов’язкові поля, залишки, проводки, податки та інші правила.

Для чого потрібне API K2 ERP

API K2 ERP потрібне для інтеграції ERP з іншими системами та автоматизації бізнес-процесів.

Основні задачі API:

отримання довідників;
створення документів;
оновлення статусів документів;
отримання залишків;
синхронізація товарів;
синхронізація цін;
отримання замовлень;
передавання замовлень;
обробка оплат;
передавання даних для фіскалізації;
отримання фіскальних чеків;
інтеграція з інтернет-магазинами;
інтеграція з маркетплейсами;
інтеграція з банками;
інтеграція з ЕДО;
інтеграція з ДПС;
інтеграція з логістикою;
робота з мобільними застосунками;
обмін даними між модулями K2 ERP.

Основні можливості

API K2 ERP може забезпечувати такі можливості:

авторизацію користувачів і сервісів;
роботу з access token;
роботу з API keys;
отримання списку компаній;
отримання довідника контрагентів;
отримання довідника товарів;
отримання цін;
отримання залишків;
створення замовлення клієнта;
створення документа продажу;
створення документа закупівлі;
створення оплати;
створення повернення;
створення складського руху;
створення фіскального чека;
отримання статусу документа;
отримання історії змін;
обробку webhooks;
журналювання інтеграційних операцій;
контроль помилок і повторних запитів.

Типи API

REST API

REST API — це найпоширеніший варіант API для ERP-інтеграцій. Дані передаються через HTTP-запити, а об’єкти зазвичай представлені у форматі JSON.

Типові HTTP-методи:

GET;
POST;
PUT;
PATCH;
DELETE.

Приклади REST endpoint-ів:

GET /api/v1/products
GET /api/v1/products/{id}
POST /api/v1/orders
GET /api/v1/orders/{id}
POST /api/v1/payments
POST /api/v1/fiscal-receipts

GraphQL API

GraphQL API може використовуватися тоді, коли клієнту потрібно гнучко отримувати лише потрібні поля, об’єднувати кілька типів даних в одному запиті або будувати складні інтерфейси.

Приклад GraphQL-запиту:

query {
  order(id: "123") {
    id
    number
    status
    customer {
      name
      phone
    }
    items {
      sku
      name
      quantity
      price
    }
  }
}

Webhooks

Webhooks — це механізм, за якого K2 ERP або зовнішня система надсилає повідомлення про подію.

Наприклад:

створено замовлення;
змінено статус оплати;
фіскальний чек створено;
товар оновлено;
залишок змінився;
документ підписано в ЕДО;
замовлення відправлено;
отримано банківську виписку.

Практичне застосування: REST API зручно використовувати для запитів і команд, а webhooks — для швидкого повідомлення про події без постійного опитування системи.

Архітектура API K2 ERP

Типова архітектура API K2 ERP може включати:

API Gateway;
модуль авторизації;
бізнес-сервіси;
сервіс довідників;
сервіс документів;
сервіс залишків;
сервіс оплат;
сервіс фіскалізації;
сервіс інтеграцій;
журнал обміну;
систему черг;
базу даних;
модуль моніторингу;
механізм webhooks;
механізм rate limiting;
механізм аудиту.

У такій архітектурі зовнішня система не працює напряму з базою даних K2 ERP, а звертається до API, яке перевіряє запит і виконує бізнес-операцію.

Авторизація і автентифікація

API K2 ERP має мати механізм автентифікації та авторизації.

Можливі варіанти:

login і password;
access token;
refresh token;
API key;
OAuth2;
JWT;
service account;
client credentials;
IP allowlist;
mTLS для критичних інтеграцій.

Авторизація має визначати:

хто виконує запит;
до якої компанії є доступ;
які модулі доступні;
які документи можна читати;
які документи можна створювати;
які поля можна змінювати;
чи дозволено виконувати фіскалізацію;
чи дозволено працювати з оплатами;
чи дозволено бачити персональні дані.

Безпека: API token, private key, client secret і access token не можна зберігати у відкритому коді, логах, публічних файлах, wiki-сторінках або повідомленнях. Вони мають зберігатися в захищених сховищах.

Версіонування API

API K2 ERP бажано версіонувати, щоб зміни не ламали існуючі інтеграції.

Приклади версіонування:

/api/v1/orders
/api/v2/orders

Або через заголовок:

Accept: application/vnd.k2erp.v1+json

Версіонування потрібне для:

підтримки старих інтеграцій;
безпечного розвитку API;
поступового переходу клієнтів;
тестування нових endpoint-ів;
документування змін;
контролю сумісності.

Формат даних

Основним форматом для API K2 ERP може бути JSON.

Приклад замовлення:

{
  "externalId": "SHOPIFY-10025",
  "customer": {
    "name": "Іван Петренко",
    "phone": "+380501112233",
    "email": "ivan@example.com"
  },
  "items": [
    {
      "sku": "SKU-001",
      "quantity": 2,
      "price": 450.00
    }
  ],
  "payment": {
    "method": "liqpay",
    "status": "paid"
  }
}

Для деяких інтеграцій також можуть використовуватися:

XML;
CSV;
XLSX;
YAML;
multipart/form-data;
binary files;
ZIP-архіви;
підписані файли.

Основні ресурси API

Компанії

API компаній може використовуватися для отримання списку юридичних осіб або організацій, доступних користувачу чи інтеграційному сервісу.

Приклади endpoint-ів:

GET /api/v1/companies
GET /api/v1/companies/{id}

Контрагенти

API контрагентів використовується для роботи з клієнтами, постачальниками, перевізниками, партнерами та іншими учасниками обліку.

Можливі операції:

отримати список контрагентів;
створити контрагента;
оновити контактні дані;
знайти контрагента за ЄДРПОУ;
знайти контрагента за ІПН;
знайти клієнта за телефоном;
знайти клієнта за email.

Приклади endpoint-ів:

GET /api/v1/counterparties
POST /api/v1/counterparties
GET /api/v1/counterparties/{id}
PATCH /api/v1/counterparties/{id}

Товари

API товарів використовується для отримання і синхронізації номенклатури.

Можливі операції:

отримати список товарів;
отримати товар за ID;
отримати товар за SKU;
створити товар;
оновити товар;
отримати характеристики;
отримати фото;
отримати статус публікації;
отримати категорії.

Приклади endpoint-ів:

GET /api/v1/products
GET /api/v1/products/{id}
GET /api/v1/products/by-sku/{sku}
POST /api/v1/products
PATCH /api/v1/products/{id}

Ціни

API цін використовується для синхронізації прайсів з інтернет-магазинами, маркетплейсами, мобільними застосунками або B2B-порталами.

Можливі операції:

отримати ціну товару;
отримати ціни за типом цін;
оновити ціну;
отримати акційну ціну;
отримати валюту ціни;
отримати історію зміни ціни.

Приклад:

GET /api/v1/prices?priceType=shopify
GET /api/v1/products/{id}/prices

Залишки

API залишків використовується для отримання доступної кількості товарів на складах.

Можливі операції:

отримати залишок за товаром;
отримати залишки за складом;
отримати доступний залишок;
отримати резерви;
отримати залишки для каналу продажів;
оновити зовнішню систему після складського руху.

Приклад:

GET /api/v1/inventory?warehouseId=1
GET /api/v1/inventory/{sku}

Рекомендація: для інтернет-магазинів і маркетплейсів API має повертати не бухгалтерський залишок, а доступний до продажу залишок: фактична кількість мінус резерви та інші блокування.

Замовлення

API замовлень використовується для створення та оновлення замовлень клієнтів.

Можливі операції:

створити замовлення;
отримати замовлення;
змінити статус;
додати оплату;
додати доставку;
скасувати замовлення;
створити повернення;
отримати історію змін.

Приклади endpoint-ів:

POST /api/v1/orders
GET /api/v1/orders/{id}
GET /api/v1/orders/by-external-id/{externalId}
PATCH /api/v1/orders/{id}/status
POST /api/v1/orders/{id}/cancel

Оплати

API оплат використовується для зв’язку з LiqPay, банками, еквайрингом, касами та внутрішніми документами оплати.

Можливі операції:

створити оплату;
отримати статус оплати;
прив’язати платіж до замовлення;
обробити callback;
створити повернення;
отримати історію платежів;
виконати звірку оплат.

Приклад:

POST /api/v1/payments
GET /api/v1/payments/{id}
POST /api/v1/payments/liqpay/callback
POST /api/v1/payments/{id}/refund

Фіскальні чеки

API фіскалізації використовується для створення чеків через ПРРО або РРО.

Можливі операції:

створити фіскальний чек;
створити чек повернення;
отримати статус чека;
отримати фіскальний номер;
отримати посилання на чек;
відкрити зміну;
закрити зміну;
сформувати Z-звіт.

Приклад:

POST /api/v1/fiscal/receipts
GET /api/v1/fiscal/receipts/{id}
POST /api/v1/fiscal/refunds
POST /api/v1/fiscal/shifts/open
POST /api/v1/fiscal/shifts/close

Для облікової системи: фіскальний чек має бути пов’язаний із замовленням, оплатою, касиром, зміною, складом, клієнтом і документом продажу. API має повертати не лише статус, а й фіскальний номер та технічну відповідь.

Доставка

API доставки використовується для роботи з логістикою.

Можливі операції:

створити доставку;
прив’язати ТТН до замовлення;
отримати статус доставки;
оновити tracking number;
отримати дані перевізника;
створити е-ТТН;
отримати історію доставки.

Приклад:

POST /api/v1/shipments
GET /api/v1/shipments/{id}
PATCH /api/v1/shipments/{id}/tracking

ЕДО

API електронного документообігу може використовуватися для інтеграції з M.E.Doc, EDIN, СОТА, FREDO або іншими сервісами.

Можливі операції:

створити електронний документ;
відправити документ;
отримати статус;
отримати квитанцію;
отримати підписаний файл;
обробити відхилення;
зберегти технічну відповідь.

Приклад:

POST /api/v1/edo/documents
GET /api/v1/edo/documents/{id}
POST /api/v1/edo/documents/{id}/send
GET /api/v1/edo/documents/{id}/status

Webhooks API K2 ERP

K2 ERP може надсилати webhooks у зовнішні системи.

Типові події:

order.created;
order.updated;
order.cancelled;
payment.paid;
payment.refunded;
product.updated;
inventory.changed;
fiscal.receipt.created;
fiscal.receipt.failed;
shipment.created;
shipment.delivered;
edo.document.signed;
edo.document.rejected.

Приклад webhook-повідомлення:

{
  "event": "order.created",
  "eventId": "evt_100001",
  "createdAt": "2026-05-08T12:30:00Z",
  "data": {
    "orderId": "12345",
    "externalId": "SHOPIFY-10025",
    "status": "new"
  }
}

Idempotency

Idempotency — це властивість API-запиту, за якої повторне виконання того самого запиту не створює дублікати.

Це особливо важливо для:

створення замовлень;
створення оплат;
створення фіскальних чеків;
створення повернень;
імпорту документів;
обробки webhooks;
повторних запитів після збою мережі.

Приклад заголовка:

Idempotency-Key: 9b2d7a8e-5c1a-4e6a-9e22-123456789abc

Рекомендація: усі API-операції, які створюють гроші, документи, чеки або складські рухи, мають підтримувати ідемпотентність. Це захищає систему від дублювання при повторному запиті.

Обробка помилок

API K2 ERP має повертати зрозумілі помилки.

Типові HTTP-коди:

200 — успішний запит;
201 — створено;
400 — помилка валідації;
401 — не авторизовано;
403 — немає прав доступу;
404 — об’єкт не знайдено;
409 — конфлікт або дублювання;
422 — бізнес-правило не виконано;
429 — перевищено ліміт запитів;
500 — внутрішня помилка сервера;
503 — сервіс тимчасово недоступний.

Приклад відповіді з помилкою:

{
  "error": {
    "code": "ORDER_ALREADY_EXISTS",
    "message": "Замовлення з таким externalId вже існує",
    "details": {
      "externalId": "SHOPIFY-10025"
    }
  }
}

Валідація даних

API має перевіряти вхідні дані до виконання бізнес-операції.

Перевіряти потрібно:

обов’язкові поля;
формат телефону;
формат email;
валюту;
кількість;
ціну;
SKU;
наявність товару;
контрагента;
склад;
статус документа;
форму оплати;
податкові ставки;
права користувача;
дублювання externalId.

Rate limiting

Rate limiting обмежує кількість запитів до API за певний період часу.

Це потрібно для:

захисту від перевантаження;
контролю інтеграцій;
захисту від помилкових циклів;
стабільності системи;
пріоритезації критичних запитів.

Приклад заголовків:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1715179200

Для великих списків API має підтримувати пагінацію.

Приклад:

GET /api/v1/products?page=1&pageSize=100

Або cursor-based pagination:

GET /api/v1/orders?cursor=eyJpZCI6MTIzfQ

Пагінація потрібна для:

товарів;
замовлень;
документів;
платежів;
журналів;
залишків;
подій;
контрагентів.

Filtering і sorting

API має підтримувати фільтрацію та сортування.

Приклади:

GET /api/v1/orders?status=paid&createdFrom=2026-05-01
GET /api/v1/products?updatedFrom=2026-05-01T00:00:00Z
GET /api/v1/inventory?warehouseId=2&sku=ABC-001

Це дозволяє інтеграціям не завантажувати всі дані щоразу, а отримувати лише потрібні зміни.

Incremental synchronization

Incremental synchronization — це синхронізація тільки тих даних, які змінилися після певного часу або версії.

Приклад:

GET /api/v1/products/changes?updatedAfter=2026-05-08T00:00:00Z
GET /api/v1/orders/changes?sinceToken=abc123

Це корисно для:

товарів;
залишків;
цін;
замовлень;
контрагентів;
документів;
статусів.

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

API для інтернет-магазинів

API K2 ERP може використовуватися для інтеграції з інтернет-магазинами:

Shopify;
Magento;
Wix;
OpenCart;
Tilda Commerce;
власний сайт;
мобільний застосунок;
B2B-портал;
B2C-портал.

Типовий обмін:

ERP передає товари;
ERP передає ціни;
ERP передає залишки;
магазин передає замовлення;
магазин передає оплату;
ERP передає статус;
ERP передає tracking number;
ERP виконує фіскалізацію;
ERP передає чек або посилання на чек.

API для маркетплейсів

API K2 ERP може використовуватися для інтеграції з маркетплейсами:

Prom;
Rozetka;
Hotline;
інші торгові майданчики.

Типовий обмін:

синхронізація товарів;
оновлення цін;
оновлення залишків;
отримання замовлень;
передавання статусів;
передавання ТТН;
фіскалізація;
обробка повернень.

API для платіжних сервісів

API K2 ERP може приймати події від платіжних сервісів або передавати платіжні запити.

Приклади:

LiqPay;
інтернет-еквайринг;
банківські платежі;
оплата карткою;
післяплата;
переказ на рахунок.

Типові операції:

створити платіж;
отримати callback;
перевірити підпис;
оновити статус оплати;
створити документ оплати;
запустити фіскалізацію;
створити повернення.

API для ПРРО і РРО

API K2 ERP може працювати з ПРРО або РРО.

Типові операції:

відкрити зміну;
закрити зміну;
створити чек;
створити чек повернення;
отримати статус чека;
отримати фіскальний номер;
створити Z-звіт;
зберегти відповідь ДПС;
надіслати електронний чек покупцю.

API для ЕДО

API K2 ERP може взаємодіяти з сервісами електронного документообігу.

Приклади:

M.E.Doc;
EDIN;
СОТА;
FREDO;
Вчасно;
інші оператори ЕДО.

Типові операції:

створити документ;
відправити документ;
отримати статус;
отримати підписаний файл;
отримати квитанцію;
обробити відмову;
синхронізувати вхідні документи.

API для ДПС

API K2 ERP може використовуватися для інтеграцій із ДПС або сервісами, які передають дані до ДПС.

Можливі напрями:

ПРРО;
SAF-T UA;
електронна звітність;
податкові накладні;
розрахунки коригування;
запити до електронного кабінету;
контроль строків звітності;
отримання квитанцій.

API для банків

API K2 ERP може використовуватися для роботи з банківськими даними.

Можливі операції:

отримати банківські виписки;
імпортувати платежі;
зіставити платіж із замовленням;
створити платіжне доручення;
отримати статус платежу;
виконати звірку;
зберегти банківський документ.

API для логістики

API K2 ERP може працювати з логістичними сервісами.

Приклади:

Нова пошта;
Укрпошта;
Мурашина логістика;
кур’єрські служби;
внутрішня доставка;
е-ТТН.

Типові операції:

створити ТТН;
отримати статус доставки;
отримати вартість доставки;
отримати відділення;
передати tracking number;
створити е-ТТН;
отримати підтвердження доставки.

Документація API

API K2 ERP має мати документацію.

Документація повинна містити:

базовий URL;
версію API;
спосіб авторизації;
список endpoint-ів;
приклади запитів;
приклади відповідей;
моделі даних;
помилки;
rate limits;
webhooks;
правила ідемпотентності;
changelog;
sandbox-оточення;
contact support;
приклади інтеграції.

Документацію можна оформити через:

OpenAPI / Swagger;
Postman Collection;
Markdown;
MediaWiki;
Redoc;
Developer Portal.

Для K2 ERP: API-документація має бути частиною продукту. Без зрозумілої документації інтеграції стають залежними від усних пояснень, ручних тестів і технічної підтримки.

OpenAPI

OpenAPI — це формат опису REST API. Він дозволяє формально описати endpoint-и, параметри, схеми даних, відповіді, помилки й авторизацію.

Приклад фрагмента OpenAPI:

openapi: 3.0.3
info:
  title: K2 ERP API
  version: 1.0.0
paths:
  /api/v1/orders:
    post:
      summary: Create order
      responses:
        '201':
          description: Order created

OpenAPI корисний для:

генерації документації;
генерації клієнтів;
тестування API;
контрактного тестування;
контролю змін;
роботи frontend і backend команд.

Sandbox

Sandbox — це тестове середовище API, у якому інтеграції можуть перевірятися без впливу на production-дані.

Sandbox потрібен для:

тестування інтеграцій;
перевірки авторизації;
перевірки форматів;
навчання партнерів;
тестування webhooks;
перевірки помилок;
тестування фіскалізації в тестовому режимі;
перевірки обробки повторних запитів.

Журнал API-запитів

У K2 ERP бажано зберігати журнал API-запитів.

У журналі можна зберігати:

дату і час запиту;
endpoint;
HTTP-метод;
користувача або сервіс;
IP-адресу;
request ID;
correlation ID;
статус відповіді;
час виконання;
текст помилки;
ідентифікатор об’єкта;
напрям інтеграції;
кількість повторних спроб.

Безпека: журнал API потрібен для діагностики, але в ньому не можна зберігати паролі, private keys, access tokens, повні реквізити карток, ключі електронного підпису або зайві персональні дані.

Monitoring API

API K2 ERP потрібно моніторити.

Варто контролювати:

доступність API;
середній час відповіді;
кількість запитів;
кількість помилок;
error rate;
кількість 401 і 403;
кількість 429;
кількість 500;
повільні endpoint-и;
стан черг;
статус зовнішніх інтеграцій;
помилки webhooks;
невдалі фіскалізації;
невдалі платежі.

API Gateway

API Gateway може бути вхідною точкою для API K2 ERP.

Він може виконувати:

маршрутизацію запитів;
авторизацію;
rate limiting;
логування;
перевірку токенів;
балансування навантаження;
трансформацію запитів;
кешування;
контроль версій;
захист від некоректних запитів.

Черги і асинхронна обробка

Не всі API-операції потрібно виконувати синхронно. Довгі або ризиковані операції краще передавати в чергу.

Асинхронно можуть оброблятися:

масовий експорт товарів;
масове оновлення залишків;
фіскалізація після оплати;
передавання документів в ЕДО;
формування SAF-T UA;
імпорт великих файлів;
синхронізація маркетплейсів;
відправлення webhooks;
повторна обробка помилок.

Приклад відповіді:

{
  "jobId": "job_12345",
  "status": "queued"
}

Retry і dead letter queue

Для інтеграцій потрібно підтримувати повторну обробку помилок.

Retry потрібен, якщо:

зовнішній сервіс тимчасово недоступний;
стався timeout;
виникла мережева помилка;
endpoint повернув 503;
webhook не доставлено;
фіскальний сервер не відповів.

Dead letter queue потрібна для повідомлень, які не вдалося обробити після кількох спроб.

Безпека API K2 ERP

Для безпечної роботи API потрібно контролювати:

HTTPS;
автентифікацію;
авторизацію;
ролі;
права доступу;
IP allowlist;
rate limiting;
audit log;
secrets management;
token rotation;
захист від SQL injection;
захист від XSS для web-інтерфейсів;
валідацію вхідних даних;
CORS;
CSRF для браузерних сценаріїв;
журнал доступів;
контроль персональних даних.

Дані, які не можна відкривати через API

Через API не можна безконтрольно відкривати:

паролі;
хеші паролів;
private keys;
ключі електронного підпису;
access tokens;
refresh tokens;
production connection strings;
повні дані платіжних карток;
зайві персональні дані;
внутрішні технічні секрети;
системні журнали без фільтрації;
фінансові дані без прав доступу.

Не плутати: API має надавати тільки ті дані, які потрібні інтеграції. Принцип мінімально необхідного доступу важливий для безпеки ERP, персональних даних, платежів і фіскальних операцій.

Типовий сценарій інтеграції інтернет-магазину

Типовий сценарій інтеграції інтернет-магазину з API K2 ERP може виглядати так:

Інтернет-магазин отримує товари з K2 ERP.
Магазин отримує ціни.
Магазин отримує залишки.
Покупець оформлює замовлення.
Магазин надсилає замовлення в K2 ERP через API.
K2 ERP створює замовлення клієнта.
Платіжний сервіс надсилає callback про оплату.
K2 ERP створює документ оплати.
Система резервує товар.
За потреби виконується фіскалізація.
ERP створює відвантаження.
ERP передає tracking number у магазин.
Магазин показує покупцю статус замовлення.

Типовий сценарій інтеграції з ЕДО

Типовий сценарій інтеграції з ЕДО може виглядати так:

У K2 ERP створюється документ.
Документ проходить внутрішню перевірку.
API передає документ у модуль ЕДО.
Модуль ЕДО надсилає документ оператору.
Оператор повертає статус.
API оновлює статус документа в K2 ERP.
Після підписання зберігається підписаний файл.
У картці документа зберігається історія обміну.

Типовий сценарій фіскалізації через API

Типовий сценарій фіскалізації може виглядати так:

Зовнішній сайт створює замовлення.
Сайт передає замовлення в K2 ERP.
Після оплати сайт або платіжний сервіс надсилає подію.
K2 ERP перевіряє оплату.
API створює фіскальний чек.
ПРРО повертає фіскальний номер.
K2 ERP зберігає чек.
Покупцю надсилається електронний чек.
Статус замовлення оновлюється.

Дані, які бажано зберігати для інтеграції

Для якісної роботи API в K2 ERP бажано зберігати:

integration ID;
назву інтеграції;
тип інтеграції;
користувача або service account;
права доступу;
API token у захищеному вигляді;
дату створення токена;
дату останнього використання;
статус інтеграції;
request ID;
correlation ID;
external ID об’єкта;
internal ID об’єкта;
статус синхронізації;
останню дату синхронізації;
текст помилки;
технічну відповідь;
кількість повторних спроб.

Можливі помилки під час інтеграції

Під час роботи з API K2 ERP можуть виникати такі помилки:

неправильний token;
token прострочений;
немає прав доступу;
неправильний формат JSON;
відсутнє обов’язкове поле;
некоректний SKU;
контрагент не знайдений;
товар не знайдений;
склад не знайдений;
замовлення вже існує;
недостатній залишок;
неправильний статус документа;
оплата вже проведена;
чек уже фіскалізований;
помилка зовнішнього сервісу;
timeout;
дублювання webhook;
перевищено rate limit;
API-версія застаріла;
помилка бізнес-правила.

Рекомендація: API має повертати машинозчитуваний код помилки і зрозуміле повідомлення для розробника. Це спрощує інтеграцію та підтримку зовнішніх систем.

Переваги API K2 ERP

До основних переваг API K2 ERP можна віднести:

автоматизацію обміну даними;
менше ручного введення;
менше дублювання документів;
швидше створення інтеграцій;
централізований доступ до даних ERP;
контроль прав доступу;
зв’язок зовнішніх систем із бізнес-логікою ERP;
прозорий журнал обміну;
підтримку інтернет-магазинів;
підтримку маркетплейсів;
підтримку оплат;
підтримку фіскалізації;
підтримку ЕДО;
можливість створення мобільних застосунків;
можливість побудови B2B і B2C-порталів.

Обмеження та ризики

Під час впровадження API потрібно враховувати:

потребу в якісній документації;
потребу в стабільному версіонуванні;
потребу в захисті токенів;
потребу в логуванні без секретів;
ризик перевантаження API;
ризик дублювання документів;
ризик некоректної фіскалізації;
ризик неправильного оновлення цін;
ризик неправильних залишків;
потребу в ідемпотентності;
потребу в моніторингу;
потребу в sandbox;
потребу в тестах;
потребу в підтримці сумісності.

Не плутати: API — це не обхід бізнес-правил ERP. Якщо зовнішня система створює документ через API, він має проходити ті самі перевірки, що й документ, створений користувачем у K2 ERP.

Висновок

API K2 ERP — це технічний інтерфейс для інтеграції K2 ERP із зовнішніми системами, модулями, сайтами, мобільними застосунками, платіжними сервісами, маркетплейсами, інтернет-магазинами, ПРРО, ЕДО, ДПС, банками та логістичними платформами.

Якісне API K2 ERP має підтримувати авторизацію, версіонування, REST або GraphQL endpoint-и, webhooks, ідемпотентність, журнал обміну, зрозумілі помилки, документацію OpenAPI, sandbox, моніторинг, rate limiting і безпечне зберігання секретів.

Для K2 ERP API є основою інтеграційної архітектури: воно дозволяє будувати модулі Shopify, Magento, Wix, Prom, LiqPay, ПРРО, ЕДО, SAF-T UA, е-ТТН, банківські й логістичні інтеграції без ручного дублювання даних.