API-first

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

API-first особливо важливий для ERP, CRM, e-commerce, банківських інтеграцій, WMS, MES, Service Desk, мобільних застосунків, BI, Power BI, AI-асистентів, партнерських кабінетів і мікросервісної архітектури. У контексті K2 ERP API-first означає, що ERP не є “закритою коробкою”, а має зрозумілі API-контракти для обміну з сайтом, CRM, банком, складом, виробництвом, Power BI, зовнішніми сервісами, міграційними інструментами та AI-рішеннями.

Головне. API-first — це підхід, коли інтеграції не додаються “потім якось прикрутимо”, а проєктуються одразу: з описом методів, форматів, статусів, помилок, прав доступу, версій, обмежень і прикладів запитів.

Практичний приклад. Якщо інтернет-магазин має створювати замовлення в ERP, API-first означає, що ще до розробки інтеграції погоджують контракт: POST /orders, поля клієнта, товари, ціни, знижки, оплату, доставку, зовнішній ID, можливі помилки й відповідь ERP.

Важливо. API-first не означає “зробити багато endpoint-ів”. Хороший API має бути стабільним, документованим, безпечним, версіонованим, тестованим, зрозумілим для бізнесу й технічних команд.

Що таке API-first

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

Замість того щоб спочатку створити інтерфейс, базу даних або внутрішню логіку, а потім “якось” відкрити доступ назовні, команда спочатку описує:

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

Простий приклад API-first

Компанія впроваджує ERP і хоче інтегрувати її з інтернет-магазином.

Без API-first часто буває так:

Спочатку розробили ERP-модуль замовлень.
Потім розробили сайт.
Потім згадали про інтеграцію.
Виявилося, що в ERP немає зовнішнього ID.
У сайту інший формат товарів.
Оплата передається окремо.
Статуси не збігаються.
Доводиться терміново переробляти обидві сторони.

З API-first процес інший:

Спочатку описали API замовлення.
Погодили поля.
Погодили статуси.
Погодили помилки.
Погодили зовнішні ID.
Погодили правила дублювання.
Сайт і ERP розробляються паралельно за одним контрактом.

Для чого потрібен API-first

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

Підхід допомагає:

прискорити інтеграції;
зменшити хаос у даних;
скоротити ручні обміни;
паралельно розробляти фронтенд і бекенд;
спростити мобільні застосунки;
підключати партнерів;
будувати мікросервіси;
створювати зрозумілі контракти;
тестувати API до завершення реалізації;
зменшити кількість переробок;
підготувати ERP до масштабування;
полегшити міграцію з BAS або старих систем;
підтримувати Power BI, AI, Service Desk і зовнішні сервіси.

API-first і API

API — це інтерфейс, через який одна система взаємодіє з іншою.

API може дозволяти:

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

Пов’язана сторінка: API для ERP

API-first і contract-first

API-first часто пов’язаний із підходом contract-first.

Contract-first означає, що спочатку описують контракт API, а потім пишуть код.

Контракт може включати:

URL endpoint-ів;
HTTP-методи;
структуру запиту;
структуру відповіді;
коди помилок;
авторизацію;
приклади;
обмеження;
версію API;
опис полів.

Приклад API-контракту

Для створення замовлення може бути описаний endpoint:

POST /api/v1/orders

Тіло запиту:

{
  "external_order_id": "WEB-10425",
  "customer": {
    "name": "ТОВ Клієнт Плюс",
    "phone": "+380XXXXXXXXX",
    "email": "info@example.com"
  },
  "items": [
    {
      "sku": "USB-C-1M-BLK",
      "quantity": 2,
      "price": 180.00
    }
  ],
  "payment_status": "paid",
  "delivery_service": "courier"
}

Відповідь:

{
  "order_id": "ERP-000145",
  "external_order_id": "WEB-10425",
  "status": "created"
}

Чим API-first відрізняється від code-first

Підхід	Що роблять спочатку	Ризик
Code-first	Спочатку пишуть код, потім описують API	API може вийти випадковим і незручним
API-first	Спочатку описують API-контракт	Потрібна дисципліна проєктування
Integration-last	Інтеграції роблять наприкінці	Високий ризик переробок
Contract-first	Спочатку погоджують контракт	Потрібна участь усіх сторін

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

Приклад code-first проблеми

Команда ERP створила поле:

client_id

Команда сайту використовує:

customer_phone

Команда CRM використовує:

contact_external_id

Після запуску інтеграції виявилося:

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

API-first вирішує це через погоджений мапінг і контракт.

API-first і OpenAPI

OpenAPI — це формат опису REST API. Його часто використовують разом зі Swagger.

OpenAPI дозволяє описати:

endpoint-и;
методи;
параметри;
схеми даних;
відповіді;
помилки;
авторизацію;
приклади;
версії;
документацію.

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

paths:
  /orders:
    post:
      summary: Create order
      requestBody:
        required: true
      responses:
        '201':
          description: Order created
        '400':
          description: Validation error

Такий опис можна використовувати для документації, генерації клієнтів, тестів і mock-серверів.

API-first і Swagger

Swagger часто використовується як інтерфейс для перегляду й тестування API.

Swagger допомагає:

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

API-first і REST

REST API — один із найпоширеніших стилів API.

У REST ресурси представлені через URL.

Приклади:

GET /customers
GET /customers/15
POST /orders
PUT /orders/145
DELETE /drafts/20

REST добре підходить для ERP, CRM, сайтів, мобільних застосунків і інтеграцій.

Приклад REST API для ERP

Метод	Endpoint	Призначення
GET	/api/v1/products	Отримати список товарів
GET	/api/v1/products/{sku}	Отримати товар за артикулом
POST	/api/v1/orders	Створити замовлення
GET	/api/v1/orders/{id}	Отримати замовлення
PATCH	/api/v1/orders/{id}/status	Оновити статус
GET	/api/v1/stock	Отримати залишки

API-first і GraphQL

GraphQL — це підхід, де клієнт сам запитує потрібну структуру даних.

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

query {
  customer(id: 15) {
    name
    orders {
      number
      totalAmount
    }
  }
}

GraphQL може бути корисним, коли різним клієнтам потрібні різні набори полів.

REST чи GraphQL

Підхід	Перевага	Коли доречний
REST	Простий і зрозумілий	ERP-інтеграції, CRUD, стандартні обміни
GraphQL	Гнучкий вибір полів	Складні фронтенди, багато різних клієнтів
Webhooks	Події в реальному часі	Статуси, сповіщення, інтеграції
Batch API	Масова передача	Міграція, синхронізація, великі довідники

API-first і webhooks

Webhook — це спосіб повідомити іншу систему про подію.

Наприклад, ERP може надіслати повідомлення сайту:

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

Приклад webhook

Подія:

order.shipped

Payload:

{
  "event": "order.shipped",
  "order_id": "ERP-000145",
  "external_order_id": "WEB-10425",
  "tracking_number": "TTN-123456789",
  "shipped_at": "2026-05-15T10:30:00"
}

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

API-first і події

У сучасній архітектурі API-first часто поєднується з event-driven підходом.

Події можуть бути:

order.created;
order.paid;
order.shipped;
payment.received;
invoice.created;
stock.changed;
customer.updated;
contract.expired;
approval.completed;
ticket.created.

Події допомагають системам реагувати без постійного опитування API.

API-first і ERP

В ERP API-first означає, що ключові бізнес-об’єкти доступні через стабільні API.

Приклади об’єктів:

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

Приклад API-first в ERP

Компанія хоче, щоб мобільний застосунок складу працював з ERP.

API-first передбачає методи:

Метод	Призначення
GET /stock/tasks	Отримати завдання комірника
POST /stock/scan	Передати сканування штрихкоду
POST /stock/move	Оформити переміщення
POST /stock/inventory	Передати результат інвентаризації
GET /products/{barcode}	Знайти товар за штрихкодом

До розробки мобільного застосунку й ERP-модуля команди погоджують ці методи.

API-first і K2 ERP

У K2 ERP API-first може бути основою інтеграційної архітектури.

Через API можна підключати:

сайт;
інтернет-магазин;
CRM;
WMS;
MES;
TMS;
банк;
Power BI;
електронний документообіг;
мобільний застосунок;
AI-асистента;
партнерський кабінет;
сервісний портал;
міграційні інструменти;
зовнішні довідники.

API-first і сайт

Для сайту API-first означає, що сайт не “лізе в базу ERP напряму”, а працює через зрозумілі методи.

Типові API:

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

Приклад API сайту й ERP

Напрям	Дані	API
ERP → сайт	Товари	GET /products
ERP → сайт	Залишки	GET /stock
ERP → сайт	Ціни	GET /prices
Сайт → ERP	Замовлення	POST /orders
Сайт → ERP	Оплата	POST /payments
ERP → сайт	Статус	Webhook order.status_changed

API-first і CRM

API-first допомагає синхронізувати CRM та ERP.

Сценарії:

CRM створює ліда;
CRM передає клієнта в ERP;
ERP повертає рахунок;
ERP повертає статус оплати;
ERP повертає дебіторку;
CRM показує менеджеру статус відвантаження;
ERP отримує прогноз продажів із CRM.

Пов’язана сторінка: CRM для продажів

API-first і банк

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

API-first для банку має описувати:

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

Пов’язана сторінка: Казначейство

API-first і Power BI

Для Power BI API-first означає, що аналітика отримує дані через стабільний, контрольований шар.

Можна робити API для:

продажів;
залишків;
платежів;
дебіторки;
кредиторки;
бюджетів;
виробництва;
Service Desk;
користувачів;
контрольних сум;
довідників.

Пов’язана сторінка: Power BI

Приклад API для Power BI

GET /api/v1/analytics/sales?date_from=2026-05-01&date_to=2026-05-31

Відповідь може містити:

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

API-first і AI

AI-рішенням потрібен контрольований доступ до даних.

API-first дозволяє AI-асистенту отримувати:

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

Пов’язана сторінка: AI

Приклад AI + API-first

Користувач питає AI:

Які заявки на оплату потрібно погодити сьогодні?

AI не читає базу напряму. Він звертається до API:

GET /api/v1/approvals?assignee=current_user&status=pending

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

API-first і мобільні застосунки

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

Приклади:

мобільний склад;
мобільні продажі;
сервісний інженер;
кур’єр;
керівник із погодженнями;
HR-застосунок;
Service Desk;
польовий аудит;
інвентаризація.

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

API-first і Service Desk

Service Desk може використовувати API для інтеграції із ERP, CRM, поштою, Telegram-ботом або порталом користувача.

Сценарії:

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

Пов’язана сторінка: Service Desk

API-first і документообіг

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

API може дозволяти:

створити договір;
передати файл;
отримати статус підписання;
отримати підписаний PDF;
перевірити контрагента;
передати акт;
зв’язати документ із замовленням;
нагадати про строк дії.

Пов’язана сторінка: ERP для документообігу

API-first і WMS

WMS-система потребує API для складу.

Обмін може включати:

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

Пов’язана сторінка: WMS система

API-first і MES

MES-система потребує API для виробництва.

Обмін може включати:

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

Пов’язана сторінка: MES система

API-first і BAS

Під час заміни BAS або інтеграції з BAS API-first допомагає не переносити старий хаос у нову систему.

Потрібно описати:

які дані йдуть з BAS;
які дані йдуть у BAS;
які зовнішні ID використовуються;
які обробки запускають обмін;
які права має користувач обміну;
які журнали помилок є;
які API потрібні в K2 ERP;
які старі обміни потрібно вимкнути.

Пов’язана сторінка: Інтеграція з BAS

API-first і міграція даних

API-first корисний при міграції даних.

Через API можна:

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

Пов’язана сторінка: Міграція даних

Приклад міграції через API

Під час переходу з BAS у K2 ERP потрібно завантажити контрагентів.

API:

POST /api/v1/customers/import

Запит:

{
  "external_id": "BAS-CUST-00077",
  "name": "ТОВ Постачальник",
  "edrpou": "12345678",
  "type": "supplier",
  "active": true
}

Відповідь:

{
  "customer_id": "K2-CUST-00991",
  "external_id": "BAS-CUST-00077",
  "status": "imported"
}

API-first і зовнішні ID

Зовнішній ID — це ідентифікатор об’єкта в іншій системі.

API-first має одразу передбачати зовнішні ID для:

замовлень сайту;
клієнтів CRM;
платежів банку;
товарів WMS;
виробничих завдань MES;
документів BAS;
міграційних записів;
ТТН доставки.

Приклад зовнішнього ID

Якщо сайт двічі передасть одне замовлення:

external_order_id = WEB-10425

ERP має не створити дублікат, а повернути відповідь:

{
  "status": "already_exists",
  "order_id": "ERP-000145"
}

API-first і ідемпотентність

Ідемпотентність означає, що повторний однаковий запит не створює небажаних дублювань.

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

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

Приклад ідемпотентності

Сайт відправив замовлення, але не отримав відповідь через збій мережі. Він відправляє замовлення ще раз.

Поганий API:

створює два замовлення.

Хороший API-first:

перевіряє external_order_id;
повертає вже створене замовлення;
не дублює товарний резерв.

API-first і версіонування

API змінюється з часом, тому потрібне версіонування.

Приклади:

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

Версіонування потрібне, щоб:

не ламати старі інтеграції;
поступово переводити клієнтів;
тестувати нові поля;
підтримувати партнерів;
контролювати зміни;
документувати deprecated-методи.

Приклад зміни версії API

У v1 замовлення має поле:

delivery_address

У v2 адресу розділили:

delivery_city
delivery_street
delivery_postcode

Якщо просто змінити API без версії, сайт або CRM можуть зламатися.

API-first і backward compatibility

Backward compatibility означає, що нові зміни не ламають старих клієнтів.

Безпечні зміни:

додати необов’язкове поле;
додати новий endpoint;
додати новий статус із документацією;
розширити відповідь без видалення старих полів.

Небезпечні зміни:

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

API-first і помилки

Хороший API має повертати зрозумілі помилки.

Приклад:

{
  "error_code": "PRODUCT_NOT_FOUND",
  "message": "Product with SKU USB-C-1M-BLK was not found",
  "field": "items[0].sku"
}

Це краще, ніж:

Error 500

бо інтеграція може автоматично зрозуміти, що саме потрібно виправити.

Типові коди помилок API

Код	Що означає	Приклад
400	Некоректний запит	Не заповнене обов’язкове поле
401	Не авторизований	Немає токена
403	Заборонено	Немає прав на документ
404	Не знайдено	Немає товару з таким SKU
409	Конфлікт	Замовлення вже існує
422	Помилка валідації	Сума має бути більшою за 0
429	Забагато запитів	Перевищено ліміт
500	Внутрішня помилка	Непередбачена помилка сервера

API-first і валідація

API має перевіряти дані до збереження.

Приклади валідації:

обов’язковий зовнішній ID;
кількість більша за 0;
ціна не від’ємна;
валюта з довідника;
клієнт має телефон або ЄДРПОУ;
SKU існує;
договір активний;
дата не в закритому періоді;
користувач має право на дію.

Приклад валідації замовлення

Запит:

{
  "external_order_id": "WEB-10425",
  "items": [
    {
      "sku": "",
      "quantity": 0
    }
  ]
}

Відповідь:

{
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "items[0].sku",
      "message": "SKU is required"
    },
    {
      "field": "items[0].quantity",
      "message": "Quantity must be greater than 0"
    }
  ]
}

API-first і безпека

API-first має включати безпеку з першого етапу.

Потрібно продумати:

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

API-first і права доступу

API має враховувати права користувача або сервісу.

Приклади:

сайт може створювати замовлення, але не бачить зарплату;
Power BI може читати аналітичні дані, але не змінює документи;
WMS може змінювати складські операції, але не фінанси;
AI-асистент бачить тільки дозволені користувачу дані;
банк-інтеграція працює тільки з платежами.

Пов’язана сторінка: Права доступу в ERP

Приклад обмеження API-користувача

Користувач:

api_site

Дозволено:

створювати замовлення;
читати залишки;
читати ціни;
отримувати статуси.

Заборонено:

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

API-first і аудит дій

API має логувати важливі дії.

Потрібно фіксувати:

хто зробив запит;
коли зробив запит;
який endpoint викликав;
який об’єкт змінив;
який external_id використав;
який статус відповіді;
яка помилка виникла;
який IP або сервіс;
який correlation_id;
хто підтвердив критичну дію.

Пов’язана сторінка: Аудит дій

API-first і correlation ID

Correlation ID — це ідентифікатор запиту або процесу, який допомагає відстежити ланцюг подій у різних системах.

Наприклад:

X-Correlation-ID: 9f7a-2026-05-15-web-10425

Цей ID може пройти через:

сайт;
API Gateway;
ERP;
банк;
WMS;
журнал інтеграції;
Service Desk.

API-first і rate limiting

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

Це потрібно, щоб:

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

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

{
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Try again later."
}

API-first і документація

Документація API — обов’язкова частина API-first.

Вона має містити:

опис endpoint-ів;
приклади запитів;
приклади відповідей;
коди помилок;
правила авторизації;
ліміти;
версії;
статуси;
поля;
типи даних;
сценарії використання;
changelog;
контакт підтримки.

Приклад документації endpoint-а

Поле	Опис
Endpoint	POST /api/v1/orders
Призначення	Створення замовлення клієнта
Авторизація	Bearer token
Обов’язкові поля	external_order_id, customer, items
Успішна відповідь	201 Created
Типові помилки	PRODUCT_NOT_FOUND, DUPLICATE_ORDER, VALIDATION_ERROR

API-first і mock API

Mock API — це імітація API, яка працює ще до готової реалізації.

Mock допомагає:

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

Приклад mock API

Ще до готової ERP-логіки mock повертає відповідь:

{
  "order_id": "MOCK-000001",
  "status": "created"
}

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

API-first і тестування

API потрібно тестувати окремо.

Типи тестів:

contract tests;
unit tests;
integration tests;
security tests;
performance tests;
regression tests;
negative tests;
load tests;
end-to-end tests.

Приклад тестів API

Для POST /orders потрібно перевірити:

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

API-first і CI/CD

API-first добре поєднується з CI/CD.

У пайплайні можна автоматично перевіряти:

чи валідний OpenAPI-файл;
чи не зламався контракт;
чи проходять contract tests;
чи відповідає реалізація документації;
чи немає небезпечних змін;
чи оновлено changelog;
чи проходять security-тести.

API-first і мікросервіси

У мікросервісній архітектурі API-first особливо важливий, бо сервіси взаємодіють між собою через контракти.

Приклади сервісів:

customer-service;
order-service;
payment-service;
warehouse-service;
notification-service;
analytics-service;
identity-service;
approval-service.

Кожен сервіс має мати зрозумілий API.

API-first і моноліт

API-first корисний не тільки для мікросервісів. Навіть монолітна ERP може мати API.

Переваги:

мобільний застосунок;
сайт;
CRM;
WMS;
Power BI;
партнери;
AI;
міграційні інструменти;
інтеграції без прямого доступу до бази.

API-first і база даних

API-first не означає відкривати базу даних напряму.

Поганий підхід:

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

Кращий підхід:

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

API-first і ORM

У бекенді API часто працює разом з ORM.

Ланцюг:

API отримує запит.
Перевіряє авторизацію.
Валідує дані.
Викликає бізнес-сервіс.
ORM читає або записує дані.
API повертає відповідь.

Важливо, щоб API не був просто “обгорткою над таблицями”. Він має відображати бізнес-операції.

API-first і SQLite

SQLite може використовуватися в API-first архітектурі як локальне або проміжне сховище.

Приклади:

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

Але для основного API великої ERP частіше потрібна серверна СУБД.

API-first і API Gateway

API Gateway — це шар, через який проходять API-запити.

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

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

API-first і моніторинг

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

Метрики:

кількість запитів;
час відповіді;
кількість помилок;
кількість 4xx;
кількість 5xx;
найповільніші endpoint-и;
rate limit;
використання API-ключів;
кількість повторних спроб;
кількість дублікатів;
статуси інтеграцій.

Приклад моніторингу API

Endpoint	Запитів за день	Помилок	Середній час
POST /orders	12 400	35	180 мс
GET /stock	48 000	12	95 мс
POST /payments	1 200	5	220 мс
GET /analytics/sales	320	0	900 мс

API-first і логування помилок

Помилки API мають бути видимими.

Потрібно логувати:

endpoint;
метод;
тіло запиту або безпечний фрагмент;
код відповіді;
error_code;
користувача;
external_id;
correlation_id;
час;
IP;
повторну спробу;
результат.

API-first і підтримка

API-first полегшує підтримку, якщо є:

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

API-first і sandbox

Sandbox — це тестове середовище API.

Воно потрібне, щоб партнери або команди могли:

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

API-first і staging

Staging — це середовище, максимально схоже на production.

У staging перевіряють:

нові версії API;
інтеграції;
продуктивність;
міграції;
права доступу;
webhook-и;
моніторинг;
логування;
сумісність із клієнтами.

API-first і бізнес-команди

API-first — це не тільки технічна тема. Бізнес має погоджувати зміст API.

Наприклад, для замовлення бізнес має визначити:

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

API-first і словник термінів

Щоб API був зрозумілий, потрібен єдиний словник.

Наприклад:

Термін	Значення
Customer	Клієнт або контрагент
Order	Замовлення клієнта
Invoice	Рахунок на оплату
Payment	Оплата
Shipment	Відвантаження
SKU	Артикул товару
External ID	Ідентифікатор у зовнішній системі

Без єдиного словника API швидко стає незрозумілим.

API-first і статуси

Статуси мають бути чітко описані.

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

Статус	Що означає
new	Замовлення створене
confirmed	Замовлення підтверджене
paid	Оплата отримана
reserved	Товар зарезервований
shipped	Замовлення відвантажене
cancelled	Замовлення скасоване

API-first і дата/час

API має мати єдиний формат дат.

Рекомендовано одразу погодити:

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

Приклад:

2026-05-15T10:30:00Z

API-first і валюти

Для фінансових API потрібно чітко описувати валюту й суму.

Приклад:

{
  "amount": 24500.00,
  "currency": "UAH"
}

Краще не передавати суму без валюти, особливо якщо система працює з UAH, USD, EUR або іншими валютами.

API-first і грошові значення

Для грошей потрібно погодити:

кількість знаків після коми;
правила округлення;
валюту;
ПДВ;
знижки;
суму з податком;
суму без податку;
ціну рядка;
загальну суму;
формат у JSON.

API-first і файли

API може працювати з файлами:

рахунками;
актами;
договорами;
PDF;
фото;
сертифікатами;
накладними;
документами доставки;
вкладеннями Service Desk.

Потрібно описати:

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

API-first і bulk API

Bulk API потрібен для масових операцій.

Наприклад:

імпорт 100 000 товарів;
оновлення 50 000 цін;
передача залишків;
міграція контрагентів;
завантаження історії продажів;
синхронізація довідників.

Приклад bulk API

POST /api/v1/products/bulk

Запит містить масив товарів:

{
  "items": [
    {
      "external_id": "BAS-T-001",
      "sku": "USB-C-1M-BLK",
      "name": "Кабель USB-C 1 м"
    },
    {
      "external_id": "BAS-T-002",
      "sku": "COFFEE-1KG",
      "name": "Кава арабіка 1 кг"
    }
  ]
}

Відповідь має показати, які записи успішні, а які з помилками.

API-first і частковий успіх

При bulk-операціях важливо підтримувати частковий успіх.

Приклад:

{
  "total": 1000,
  "success": 980,
  "failed": 20,
  "errors": [
    {
      "external_id": "BAS-T-077",
      "error_code": "SKU_EMPTY",
      "message": "SKU is required"
    }
  ]
}

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

API-first і пагінація

API не має повертати мільйони записів одним запитом.

Потрібна пагінація.

Приклад:

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

Або cursor-based:

GET /api/v1/products?cursor=abc123&limit=100

API-first і фільтри

Фільтри дозволяють отримувати тільки потрібні дані.

Приклад:

GET /api/v1/orders?status=paid&date_from=2026-05-01&date_to=2026-05-31

Це краще, ніж вивантажувати всі замовлення й фільтрувати на стороні клієнта.

API-first і сортування

Сортування має бути передбачене контрактом.

Приклад:

GET /api/v1/products?sort=name
GET /api/v1/orders?sort=-created_at

Мінус може означати сортування за спаданням.

API-first і інкрементальна синхронізація

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

Приклад:

GET /api/v1/products/changes?updated_after=2026-05-15T10:00:00Z

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

Power BI;
WMS;
мобільних застосунків;
кешів;
інтеграцій;
міграційних перевірок.

API-first і changed_at

Для інкрементального обміну об’єкти мають мати поля:

created_at;
updated_at;
deleted_at;
version;
change_id.

Без цих полів інтеграції часто змушені щоразу забирати всі дані.

API-first і soft delete

Якщо об’єкт видалений або деактивований, API має передавати це зовнішнім системам.

Наприклад:

{
  "sku": "USB-C-1M-BLK",
  "active": false,
  "deleted_at": "2026-05-15T10:30:00Z"
}

Інакше сайт може продовжити продавати товар, який уже неактивний в ERP.

API-first і SLA

Для критичних API потрібен SLA.

Потрібно визначити:

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

API-first і продуктивність

API має бути проєктований з урахуванням навантаження.

Потрібно врахувати:

частоту запитів;
обсяг даних;
кешування;
індекси;
пагінацію;
batch-операції;
асинхронні задачі;
черги;
таймаути;
retry-логіку;
rate limiting.

API-first і асинхронні задачі

Довгі операції краще виконувати асинхронно.

Наприклад, імпорт 100 000 товарів.

API може повернути:

{
  "job_id": "JOB-2026-0001",
  "status": "accepted"
}

Потім клієнт перевіряє статус:

GET /api/v1/jobs/JOB-2026-0001

API-first і черги

Черги корисні для:

обробки великих імпортів;
відправки повідомлень;
синхронізації з WMS;
webhook-ів;
повторних спроб;
банківських операцій;
інтеграцій із нестабільними сервісами.

API-first і retry-логіка

Інтеграції мають вміти повторювати запити.

Потрібно визначити:

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

Приклад retry

Банк тимчасово недоступний.

API повертає:

503 Service Unavailable

Інтеграція:

не створює новий платіж;
повторює запит через 1 хвилину;
потім через 5 хвилин;
потім створює задачу в Service Desk.

API-first і idempotency key

Для критичних операцій використовують idempotency key.

Приклад:

Idempotency-Key: WEB-10425-create-order

Якщо клієнт повторить той самий запит із тим самим ключем, API не створить дубль.

API-first і інтеграційні журнали

Для API-first важливо мати журнал інтеграцій.

Журнал має містити:

систему-джерело;
систему-приймач;
endpoint;
external_id;
request_id;
correlation_id;
статус;
помилку;
час;
повторні спроби;
відповідального.

API-first і карта інтеграцій

Карта інтеграцій описує, хто з ким обмінюється даними.

Система	API	Дані	Напрям
Сайт	/orders, /stock, /prices	Замовлення, залишки, ціни	Двосторонній
CRM	/customers, /invoices	Клієнти, рахунки, статуси	Двосторонній
Банк	/payments, /statements	Платежі, виписки	Двосторонній
Power BI	/analytics	Продажі, фінанси, склад	ERP → BI
WMS	/warehouse	Приймання, відвантаження, залишки	Двосторонній

API-first і внутрішні команди

API-first допомагає розділити роботу команд:

frontend чекає контракт, а не готовий backend;
backend реалізує контракт;
QA пише тести по контракту;
DevOps налаштовує gateway і моніторинг;
бізнес погоджує поля й статуси;
партнери отримують документацію;
аналітики знають джерела даних.

API-first і partner API

Partner API — це API для зовнішніх партнерів.

Приклади:

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

API-first і public API

Public API доступний зовнішнім розробникам або клієнтам.

Для нього особливо важливі:

документація;
стабільність;
версіонування;
rate limiting;
sandbox;
API-ключі;
приклади;
підтримка;
changelog;
політика deprecated-версій.

API-first і internal API

Internal API використовується всередині компанії.

Воно теж має бути документованим, бо внутрішні API часто стають критичними для:

мобільних застосунків;
BI;
інтеграцій;
мікросервісів;
AI;
автоматизації;
Service Desk;
розробки нових модулів.

API-first і direct database access

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

Ризики:

обхід бізнес-логіки;
обхід прав доступу;
немає аудиту;
залежність від структури таблиць;
складні оновлення;
ризик пошкодження даних;
немає стабільного контракту;
Power BI або інтеграція можуть зламатися після зміни схеми.

API-first і бізнес-правила

API має враховувати бізнес-правила.

Наприклад, при створенні платежу API має перевірити:

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

API-first і доменна модель

API має відображати бізнес-домен, а не випадкову структуру бази.

Погано:

POST /table_145/insert

Краще:

POST /orders
POST /payment-requests
POST /stock-transfers
POST /service-tickets

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

API-first і naming conventions

Потрібні правила іменування.

Наприклад:

endpoint-и в множині: /orders, /customers;
поля в snake_case або camelCase;
статуси в нижньому регістрі;
коди помилок у верхньому регістрі;
однакові назви для однакових сутностей;
не змішувати client, customer, counterparty без словника.

API-first і локалізація

API краще передавати стабільні коди, а не локалізовані тексти.

Наприклад:

"status": "paid"

А не:

"status": "Оплачено"

Текст “Оплачено” можна відобразити в інтерфейсі, але API краще працює з кодами.

API-first і формат відповіді

Потрібно уніфікувати відповіді.

Приклад успіху:

{
  "data": {
    "id": "ERP-000145",
    "status": "created"
  }
}

Приклад помилки:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": []
  }
}

API-first і статуси HTTP

HTTP-статуси мають використовуватися послідовно.

Приклади:

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

API-first і changelog

Changelog потрібен, щоб команди бачили зміни API.

Він має містити:

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

API-first і deprecated API

Deprecated означає, що метод застарів, але ще тимчасово працює.

Потрібно повідомити:

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

API-first і governance

API governance — це правила керування API в компанії.

Включає:

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

API-first і API Catalog

API Catalog — це каталог усіх API компанії.

Він може містити:

назву API;
опис;
власника;
версію;
документацію;
статус;
середовища;
endpoint-и;
права доступу;
SLA;
changelog.

API-first і DevOps

DevOps у API-first відповідає за:

середовища;
gateway;
деплой;
секрети;
моніторинг;
логування;
CI/CD;
сертифікати;
rate limiting;
масштабування;
резервування;
аварійне відновлення.

API-first і секрети

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

Потрібно:

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

API-first і персональні дані

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

Потрібно обмежувати:

ПІБ;
телефони;
email;
адреси;
ІПН;
зарплату;
кадрові дані;
банківські реквізити;
історію дій;
документи працівників.

API-first і фінансові дані

Фінансові API мають бути особливо захищені.

Приклади чутливих даних:

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

API-first і відповідальність

Для кожного API потрібен власник.

Власник відповідає за:

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

API-first при впровадженні ERP

Під час впровадження ERP API-first потрібно включити в план проєкту.

Етапи:

описати всі системи;
зробити карту інтеграцій;
визначити джерела правди;
описати API-контракти;
погодити статуси;
погодити довідники;
визначити зовнішні ID;
створити mock API;
написати тести;
налаштувати безпеку;
запустити sandbox;
провести інтеграційне тестування;
увімкнути моніторинг.

API-first і джерело правди

Джерело правди — це система, яка є головною для певних даних.

Приклад:

Дані	Джерело правди
Номенклатура	ERP
Залишки	ERP або WMS, залежно від процесу
Ліди	CRM
Платежі	Банк / казначейство
Договори	ERP або документообіг
Аналітика	BI-сховище

Якщо джерело правди не визначене, системи починають перезаписувати одна одну.

API-first і мапінг даних

Мапінг описує відповідність полів між системами.

Приклад:

Сайт	API ERP	Коментар
order_id	external_order_id	Зовнішній номер замовлення
customer_phone	customer.phone	Пошук клієнта
sku	items.sku	Пошук товару
delivery_type	delivery.service	Служба доставки
paid	payment_status	Статус оплати

API-first і контрольні суми

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

Контроль може включати:

кількість замовлень;
суму замовлень;
кількість оплат;
суму оплат;
кількість товарів;
залишки;
кількість помилок;
кількість зовнішніх ID;
кількість дублів;
кількість успішних webhook-ів.

Приклад контрольних сум API

Показник	Сайт	ERP	Статус
Замовлення за день	240	240	Збігається
Сума оплат	780 000 грн	780 000 грн	Збігається
Дублі зовнішніх ID	0	0	Збігається
Помилки інтеграції	12	12	Потрібне виправлення

API-first і паралельний запуск ERP

Під час паралельного запуску ERP API-first допомагає контролювати обмін між старою і новою системою.

Потрібно визначити:

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

API-first і заміна BAS

При заміні BAS API-first допомагає не переносити залежність від старих зовнішніх обробок.

Потрібно:

описати старі інтеграції BAS;
знайти зовнішні обробки;
знайти API або файли обміну;
описати зовнішні ID;
створити нові API в K2 ERP;
протестувати обмін;
перенести Power BI;
вимкнути старі інтеграції після запуску.

Пов’язана сторінка: Заміна BAS

API-first і технічний борг

API-first зменшує технічний борг, але тільки якщо його дотримуються.

Ознаки технічного боргу в API:

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

Типові помилки API-first

Поширені помилки:

назвати підхід API-first, але не писати контракт;
створювати API після готової системи;
не залучати бізнес;
не описувати помилки;
не робити версіонування;
не враховувати права доступу;
не робити sandbox;
не логувати запити;
не тестувати контракти;
не мати зовнішніх ID;
не мати мапінгу;
не контролювати навантаження;
не документувати зміни.

Типові помилки в ERP API

Для ERP особливо небезпечні:

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

Впровадження API-first

Впровадження API-first можна робити поетапно.

Етапи:

описати бізнес-процеси;
визначити системи;
зробити карту інтеграцій;
визначити джерела правди;
описати доменні об’єкти;
створити API-контракти;
погодити OpenAPI;
створити mock API;
написати тести;
реалізувати backend;
підключити frontend і інтеграції;
налаштувати безпеку;
увімкнути моніторинг;
вести changelog.

Що підготувати перед API-first проєктом

Потрібно підготувати:

список систем;
список інтеграцій;
бізнес-процеси;
довідники;
статуси;
мапінг полів;
список зовнішніх ID;
вимоги безпеки;
права доступу;
вимоги до продуктивності;
вимоги до аналітики;
сценарії помилок;
приклади запитів;
тестові дані;
власників API.

Переваги API-first

Переваги:

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

Недоліки API-first

Недоліки або складності:

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

API-first у малому бізнесі

Малий бізнес може використовувати API-first для простих задач:

сайт → ERP;
CRM → ERP;
банк → облік;
Power BI → звіти;
мобільний застосунок → склад;
Telegram-бот → заявки.

Навіть невеликий API-контракт краще, ніж ручний Excel-обмін без правил.

API-first у середньому бізнесі

Середній бізнес зазвичай має кілька систем:

ERP;
CRM;
сайт;
банк;
склад;
BI;
документообіг;
Service Desk.

API-first допомагає зробити інтеграції керованими, а не залежними від випадкових файлів і ручних обробок.

API-first у великому бізнесі

У великому бізнесі API-first стає частиною корпоративної архітектури.

Потрібні:

API Gateway;
API Catalog;
governance;
security policy;
versioning policy;
monitoring;
sandbox;
developer portal;
SLA;
інтеграційна команда;
архітектурний review.

API-first і майбутнє ERP

ERP-системи все більше стають платформами, а не окремими закритими програмами.

API-first дозволяє ERP бути:

інтегрованою;
модульною;
готовою до мобільності;
готовою до AI;
готовою до Power BI;
готовою до партнерських сервісів;
готовою до хмарної архітектури;
готовою до швидких змін бізнесу.

Пов’язані сторінки

FAQ

Що таке API-first простими словами?

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

Для чого потрібен API-first?

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

Чим API-first відрізняється від code-first?

У code-first спочатку пишуть код, а API описують пізніше. В API-first спочатку погоджують контракт API, поля, помилки, версії та правила обміну.

Що таке API-контракт?

API-контракт — це опис endpoint-ів, методів, полів, форматів, відповідей, помилок, авторизації, статусів і прикладів використання API.

Що таке OpenAPI?

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

Чому API-first важливий для ERP?

ERP часто інтегрується із сайтом, CRM, банком, WMS, MES, Power BI, AI і зовнішніми сервісами. API-first допомагає зробити ці обміни стабільними й контрольованими.

Чому не варто давати інтеграціям прямий доступ до бази?

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

Що таке ідемпотентність API?

Ідемпотентність означає, що повторний однаковий запит не створить дублікат. Це особливо важливо для замовлень, платежів, імпорту й webhook-ів.

Як API-first допомагає при переході з BAS у K2 ERP?

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

Який результат правильного API-first підходу?

Результат — стабільні API, зрозумілі інтеграції, менше ручної роботи, краща безпека, контроль помилок, якісна аналітика й готовність ERP до розвитку.

Коротко

Питання	Відповідь
Що таке API-first?	Підхід, коли API проєктують першим як контракт між системами.
Для чого потрібен?	Для стабільних інтеграцій, паралельної розробки, документації, безпеки й меншої кількості переробок.
Що описує API-контракт?	Endpoint-и, поля, формати, відповіді, помилки, авторизацію, версії, статуси й приклади.
Де використовується?	В ERP, CRM, сайтах, мобільних застосунках, банках, WMS, MES, Power BI, AI й інтеграціях.
Що важливо?	OpenAPI, версіонування, права доступу, зовнішні ID, ідемпотентність, аудит, моніторинг і тестування.
Які ризики?	Відсутність документації, хаотичні endpoint-и, прямий доступ до бази, дублікати, слабка безпека й зламані інтеграції.
Який результат?	Керована цифрова архітектура, стабільні обміни, швидші інтеграції й готовність до K2 ERP, BI та AI.