УКЦ API v2.7 — Документація

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

Кожен запит має передавати токен доступу. Рекомендований спосіб — заголовок Authorization: Bearer <client-token>. Також підтримується X-Api-Token.

Рекомендовано:
Authorization: Bearer YOUR_TOKEN

Для зворотної сумісності може бути увімкнений legacy-режим передачі токена через query-параметр ?token=... або path-формат /api/{token}/{method}. Токени керуються в БД api.clients.

Спосіб	Статус	Приклад
`Authorization: Bearer`	рекомендовано	`curl -H "Authorization: Bearer YOUR_TOKEN" ...`
`X-Api-Token`	підтримується	`X-Api-Token: YOUR_TOKEN`
`?token=...`	legacy	`/v1/appeals?token=YOUR_TOKEN`
`/api/{token}/{method}`	legacy / опційно	`/api/YOUR_TOKEN/get_appeals`

Debug: query-параметр ?debug=1 працює тільки якщо адміністратор явно увімкнув APP_ALLOW_QUERY_DEBUG. За замовчуванням debug через query вимкнений.

GET /v1/appeals — Нові звернення

GET /v1/appeals

Повертає перелік звернень, прив’язаних до вашого виконавця, за останні 60 днів. У блоці FILES повертаються абсолютні URL для скачування вкладень через /v1/files/....

У CRM-proxy режимі endpoint коректно розпаковує різні форми CRM-відповідей: прямий масив, envelope з data, envelope з result, а також wrapper-об’єкти з numeric keys.

Параметр	Тип	Опис	Приклад
`debug`	0\|1	Необов’язковий режим налагодження, працює лише якщо увімкнено адміністратором	`1`

Важливо щодо дат: поля START_DATE, END_DATE, start_date, end_date нормалізуються до legacy-формату DD-MON-YY, наприклад 19-MAY-26. Це прибирає різницю між відповідями тестового та production CRM.

Додаткові поля у відповіді:

Поле	Опис
`PRIORITY_NAME`	Пріоритет, зокрема першочерговий розгляд
`CUSTOMER_CATEGORY`	Категорія заявника
`CUSTOMER_SOCIAL_STATUS`	Соціальний стан
`CUSTOMER_GENDER`	Стать

Фрагмент відповіді:

{
  "count": 2,
  "data": [{
    "INTERACTION_REQUEST_ID": "21245075",
    "DESTINATION_NAME": "Міністерство оборони України",
    "REQUEST_STATE_ID": "569",
    "START_DATE": "19-MAY-26",
    "END_DATE": "19-MAY-26",
    "SF_FULL_NAME": "Барилюк Павло Валерійович",
    "PRIORITY_NAME": "Першочерговий",
    "CUSTOMER_CATEGORY": "...",
    "CUSTOMER_SOCIAL_STATUS": "...",
    "CUSTOMER_GENDER": "...",
    "FILES": [
      "https://api-ovv-v2.ukc.gov.ua/v1/files/%D0%92%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%8C.pdf?appeal_id=21245075"
    ]
  }]
}

POST /v1/appeals/{id}/accept — Прийняти звернення

POST /v1/appeals/21245075/accept

Переводить звернення вашого підрозділу зі статусу 569 у 568.

Після успішної операції в картці звернення в УКЦ додається коментар від UKC/api_ovv.

Відповідь:

{
  "success": true
}

POST /v1/appeals/batch-accept — Пакетне прийняття

POST /v1/appeals/batch-accept

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

Тіло запиту:

{
  "appeal_ids": ["21245075", "21245076", "21245077"]
}

Відповідь:

{
  "success": true,
  "updated": 3
}

POST /v1/appeals/{id}/complete — Прикріпити відповідь

POST /v1/appeals/21245075/complete

Зберігає файл відповіді. У CRM-proxy режимі використовується multipart upload у CRM API. У legacy Oracle fallback файл зберігається через PKG_FILE.p_save з src="form"; login для upload налаштовується через ORACLE_FILE_UPLOAD_LOGIN.

Поведінка параметра kind:

kind=intermediate — проставляє атрибут 525 “Проміжна відповідь (файл)”, статус не змінюється;
kind=final — проставляє атрибут 407 “Остаточна відповідь (файл)” і переводить статус звернення у 570;
без kind — лише прикріплює файл без зміни атрибутів/статусу.

Поле	Тип	Опис
`file`	multipart/form-data	Файл відповіді: PDF, DOCX, ZIP, JPG тощо
`kind`	string, optional	`intermediate` \| `final` \| пусто

Після успішного збереження файлу додається коментар українською з описом дії. Автор: UKC/api_ovv.

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

{
  "success": true,
  "message": "Відповідь прикріплено, статус \"Розглянуто\"",
  "appeal_id": "21245075",
  "file_id": 14801760,
  "file_name": "reply.pdf",
  "download_url": "https://api-ovv-v2.ukc.gov.ua/v1/files/reply.pdf?appeal_id=21245075",
  "src": "form"
}

GET /v1/files/{filename} — Скачати файл

GET /v1/files/<filename>?appeal_id=<id>

Параметр appeal_id рекомендований — звужує пошук, пришвидшує віддачу і допомагає уникати 504 Gateway Timeout.

Назва файлу проходить валідацію: заборонені traversal-послідовності, control chars та некоректні значення.

Приклад:

https://api-ovv-v2.ukc.gov.ua/v1/files/%D0%92%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%8C.pdf?appeal_id=21245075

GET /v1/appeals/{id}/card-pdf — Скачати картку звернення

GET /v1/appeals/<id>/card-pdf

Повертає друковану картку звернення у форматі PDF окремим методом. Цей файл не додається у загальний масив FILES endpoint-у GET /v1/appeals.

CRM-proxy та Oracle fallback

З 19.05.2026 runtime усіх основних OVV endpoint-ів може працювати через crm-api із JWT. Публічний контракт api-ovv-v2 для клієнтів збережено.

Endpoint	CRM-proxy	Примітка
`GET /v1/appeals`	так	Повертає `count + data`, нормалізує `FILES` і дати.
`POST /v1/appeals/{id}/accept`	так	Зберігає legacy-відповідь `{"success": true}`.
`POST /v1/appeals/batch-accept`	так	Підтримує JSON body з `appeal_ids`.
`POST /v1/appeals/{id}/complete`	так	Multipart upload, повернення публічного `download_url`.
`GET /v1/appeals/{id}/card-pdf`	так	Binary download через CRM, fallback лише за визначених умов.
`GET /v1/files/{filename}`	так	Binary download support.

Безпека та обробка помилок

Oracle fallback не використовується для 401/403.
Fallback блокується для CRM-відповідей із маркерами forbidden / access denied, навіть якщо backend повернув 5xx.
Для binary endpoint-ів некоректна 2xx відповідь без файлу вважається backend-помилкою, а не маскується під 404.
Побудова публічних URL спирається на BASE_URL або server name без довіри до довільного Host header.
_diag.php і _test.php заблоковані для web-викликів і можуть запускатися тільки з CLI.
Exception handler не повертає сирі помилки клієнту; у відповіді повертається контрольований request_id.
У логах маскуються токени в URI та legacy path-сегментах.
На auth layer діє базовий rate-limit і перевірка формату/довжини токена.

Сумісність зі старим API

Підтримуються legacy-запити у вигляді /api/{token}/{method}, якщо цей режим увімкнений у конфігурації:

get_appeals → аналог GET /v1/appeals;
accept_appeal&id=... → аналог POST /v1/appeals/{id}/accept;
batch_accept&ids=1,2,3 → аналог POST /v1/appeals/batch-accept.

Legacy get_appeals також використовує актуальну нормалізацію CRM payload і дат.

Приклади cURL

# 1) Отримати нові звернення
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api-ovv-v2.ukc.gov.ua/v1/appeals" -o appeals.json

# 2) Прийняти одне звернення
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api-ovv-v2.ukc.gov.ua/v1/appeals/21245075/accept"

# 3) Пакетне прийняття
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api-ovv-v2.ukc.gov.ua/v1/appeals/batch-accept" \
  -d '{"appeal_ids":["21245075","21245076"]}'

# 4) Прикріпити проміжну відповідь
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api-ovv-v2.ukc.gov.ua/v1/appeals/21245075/complete" \
  -F "file=@/path/reply.pdf;type=application/pdf" \
  -F "kind=intermediate"

# 5) Прикріпити остаточну відповідь, переводить статус у 570
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api-ovv-v2.ukc.gov.ua/v1/appeals/21245075/complete" \
  -F "file=@/path/reply.pdf;type=application/pdf" \
  -F "kind=final"

# 6) Завантажити файл, рекомендовано з appeal_id
curl -L -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api-ovv-v2.ukc.gov.ua/v1/files/reply.pdf?appeal_id=21245075" -o reply.pdf

# 7) Завантажити картку звернення у PDF
curl -L -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api-ovv-v2.ukc.gov.ua/v1/appeals/21245075/card-pdf" -o card.pdf

Коментарі в CRM

При зміні статусу або прикріпленні файлу через API у картці звернення автоматично створюється коментар через PKG_INTERACTION_COMMENT.p_add_comment. Автор: UKC/api_ovv.

Метод	Що фіксується в коментарі
`accept` / `batch-accept`	Прийняття до розгляду: статус `569` → `568`.
`complete` + `kind=intermediate`	Проміжна відповідь, файл, атрибут `525`; статус не змінюється.
`complete` + `kind=final`	Остаточна відповідь, файл, атрибут `407`; статус → `570`.
`complete` без `kind`	Файл прикріплено; статус не змінюється.

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

API ОВВ: Прикріплено остаточну відповідь (файл).
Файл: «reply.pdf» (ід. 14801760).
Зміна статусу: → 570 (Розглянуто).

Якщо запис коментаря не вдався, основна операція не відкочується — помилка фіксується в серверному логі.

Стани звернень

569 — Нове / Надіслано
568 — Прийнято до розгляду
570 — Розглянуто, за умови kind=final