REST API UBD: огляд для інтеграторів

REST API UBD — точка інтеграції з зовнішніми системами. На відміну від веб-інтерфейсу, API працює без UX-припущень: інтегратор повинен явно надсилати всі параметри, обробляти всі помилки, керувати своїми токенами. Стаття описує базовий рівень для інтегратора, який вперше підключається до UBD.

Огляд API

API UBD спроєктований як RESTful, з основними принципами:

• Ресурсо-орієнтований: URL описує об’єкт (/api/v1/documents/123), метод описує дію (GET/POST/PUT/DELETE).
• JSON як основний формат запиту і відповіді.
• HTTPS обов’язково (HTTP блокується).
• Stateless: кожен запит несе власну автентифікацію, серверний стан не зберігається між запитами.
• Версіонований у URL (/api/v1/, /api/v2/).

API сертифіковано як частина експертного висновку Г-3 — функції безпеки, доступні через API, ідентичні функціям веб-інтерфейсу.

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

Підтримуються два механізми:

JWT (для прикладних інтеграцій)

Інтегратор отримує access token через endpoint /api/v1/auth/login з логіном/паролем сервісного облікового запису. Token живе 1 годину. Refresh token використовується для отримання нового access token без повторної автентифікації — живе 24 години.

Усі подальші запити несуть header Authorization: Bearer {token}.

OAuth 2.0 (для third-party інтеграцій)

Стандартний OAuth 2.0 з authorization code flow. Клієнтське застосування реєструється у UBD як OAuth-клієнт, отримує client_id і client_secret. Користувач явно авторизує доступ через свій обліковий запис.

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

Rate limits

API обмежує кількість запитів для запобігання DoS і нерівномірному навантаженню:

Перевищення → відповідь 429 Too Many Requests з header Retry-After, що вказує, через скільки секунд повторити.

Адміністратор UBD може налаштовувати ліміти індивідуально на токен для критичних інтеграцій.

Базові endpoints

CRUD на записи

Стандартний патерн для будь-якої таблиці моделі:

• GET /api/v1/{entity}/ — список записів з фільтрацією, пагінацією, сортуванням.
• GET /api/v1/{entity}/{id} — отримання конкретного запису.
• POST /api/v1/{entity}/ — створення.
• PUT /api/v1/{entity}/{id} — оновлення (повне).
• PATCH /api/v1/{entity}/{id} — часткове оновлення.
• DELETE /api/v1/{entity}/{id} — видалення.

Виконання дій

Не CRUD-операції, а конкретні дії над об’єктом: затвердити документ, відмінити транзакцію, надіслати на узгодження.

POST /api/v1/{entity}/{id}/actions/{action} з тілом, що містить параметри дії.

Метадані

Запит структури таблиці (для динамічних інтеграторів):

GET /api/v1/metadata/{entity} — повертає JSON Schema моделі: поля, типи, обов’язковість, обмеження.

Формат запиту-відповіді

Стандартизовано на JSON Schema. Кожна відповідь має передбачувану структуру:

Успішна відповідь зі списком:

{
  "data": [...],
  "meta": { "total": 1234, "page": 1, "per_page": 50 }
}

Успішна відповідь з одним об’єктом:

{
  "data": {...}
}

Помилкова відповідь:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Поле name обов'язкове",
    "details": [...]
  }
}

Error handling

HTTP-статуси відповідають семантиці:

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

Версія API — частина URL: /api/v1/, /api/v2/. UBD підтримує дві версії одночасно: поточну та попередню. При випуску v3 версія v1 deprecated за 6 місяців.

Зміни всередині однієї версії — тільки сумісні: додавання полів, додавання endpoint’ів. Зміни типу полів, видалення полів, перейменування — тільки у наступну версію.

Приклади викликів

# Логін
curl -X POST https://api.example.com/api/v1/auth/login 
  -H "Content-Type: application/json" 
  -d '{"login":"service_account","password":"..."}'

# Запит списку документів
curl https://api.example.com/api/v1/documents/?status=active&page=1 
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Створення документа
curl -X POST https://api.example.com/api/v1/documents/ 
  -H "Authorization: Bearer ..." 
  -H "Content-Type: application/json" 
  -d '{"title":"Договір №123","type":"contract"}'