API судових даних і MCP

Підключення

MCP

1. Додайте віддалений MCP-сервер https://api.sudovispravy.com.ua/mcp із транспортом Streamable HTTP.
2. Підключіться, увійдіть через браузер і підтвердьте доступ.

Потрібен клієнт із підтримкою віддаленого MCP та OAuth. MCP приймає лише OAuth-токени. Для REST використовуйте API-ключ у заголовку Authorization: Bearer.

Доступ до судових даних також дозволяє переглядати виконавчі провадження. Для ваших збережених засідань, завдань, непереглянутих та обраних документів і відстежуваних виконавчих проваджень потрібен окремий дозвіл personal_data:read. Наявні ключі й підключення не отримують його автоматично: створіть ключ із цим дозволом або повторно підключіть і авторизуйте MCP-клієнт.

REST

Створіть API-ключ на сторінці Доступ до API та збережіть його як секрет. Базова адреса REST: https://api.sudovispravy.com.ua/api/v1.

Для публічних справ, засідань, документів, виконавчих проваджень і ваших відстежуваних справ потрібен дозвіл court_data:read та активна підписка Pro. Для GET /usage і get_usage потрібен usage:read; перегляд використання не потребує активної Pro та не витрачає операцій. Особисті засідання, завдання, непереглянуті й обрані документи та відстежувані провадження потребують personal_data:read і активної Pro.

export COURT_DATA_API_KEY='pdc_...'
curl -G 'https://api.sudovispravy.com.ua/api/v1/cases' \
  -H "Authorization: Bearer $COURT_DATA_API_KEY" \
  --data-urlencode 'case_number=123/456/26'

Операції

Для пошуку вкажіть case_number — частину номера справи від 3 до 100 символів. Пошук не враховує регістр. Широкий запит може не охопити всі збіги, тому уточнюйте номер. Повний номер також можна використати для пошуку. Номер справи передавайте як параметр запиту, навіть якщо він містить косі риски.

Усі списки REST і MCP приймають limit (типово 20, максимум 50; 0 також означає 20) і offset (типово 0). Зміщення має бути цілим числом від 0 до 2 147 483 596; для GET /cases і search_cases максимум — 2 001. Параметр cursor у REST не підтримується й повертає помилку. Порожні списки мають items: []. Якщо has_more дорівнює true, передайте next_offset як offset для наступної сторінки та повторіть фільтри. Пагінація не містить ідентифікаторів рядків. Зміни даних або часу для майбутніх засідань можуть зсувати результати між сторінками, спричиняючи повтори або пропуски. При зміні фільтрів починайте з offset=0. Повний опис параметрів і відповідей — у специфікації OpenAPI.

GET /cases і search_cases повертають case_number, court_name, last_event_date та latest_stage. Невідомі метадані мають значення null. GET /case-sessions і list_case_sessions приймають точний case_number довжиною до 100 символів і повертають публічні засідання від новіших дат до старіших, із недатованими засіданнями наприкінці.

Усі операції з документами повертають source_document_id, case_number, court_name, judgment_form, adjudication_date, publication_date та source_url. Невідомі поля, крім номера справи, мають значення null. Відсутнє або некоректне посилання також повертається як source_url: null. Текст документів не повертається.

GET /documents і list_case_documents приймають точний case_number довжиною до 100 символів. Документи впорядковані за датою рішення від новіших до старіших, із недатованими наприкінці. Відсутність документів повертає успішну порожню сторінку. GET /documents/{source_document_id} і get_document використовують ідентифікатор реєстру з поля source_document_id — рядок від 1 до 100 символів після видалення пробілів із країв. У REST закодуйте його як один сегмент URL; у MCP передайте аргумент source_document_id як рядок. Якщо це поле має значення null, документ доступний у списку, але його неможливо отримати за ідентифікатором джерела. Відсутній або неактивний документ у запиті одного запису повертає 404.

GET /user-cases і MCP-інструмент list_user_cases повертають відстежувані справи користувача, автентифікованого API-ключем або OAuth, в усіх статусах, включно з архівними. Параметри: limit (типово 20, максимум 50) та offset. Кожна справа містить case_number, вашу назву case_name, статус відстеження status і необов’язкову назву категорії category. Якщо категорію не призначено, поле відсутнє. Вибрати іншого користувача неможливо. Кожна успішна сторінка, навіть порожня, витрачає одну операцію Pro.

GET /user-enforcement-proceedings і list_user_enforcement потребують personal_data:read. Повертаються окремі рядки для ваших відстежуваних боржників із пов’язаними імпортованими провадженнями, боржників без збігів та очікуваних номерів ВП. Збіг вимагає точного збереженого імені та дати народження; відсутня дата збігається лише з відсутньою. Очікуваний номер повертається з pending: true і без даних боржника до обробки застосунком. Для оброблених відстежень pending дорівнює false; невідомі необов’язкові поля відсутні. Це імпортовані дані, а не перевірка реєстру наживо. Параметри: limit (20, максимум 50) і offset. Боржники передують очікуваним номерам; новіші відстеження й провадження йдуть першими. Кожна успішна сторінка, включно з порожньою, витрачає одну операцію.

GET /user-sessions і list_user_sessions потребують дозволу personal_data:read та повертають ваші збережені засідання для неархівних справ за датою у зростаючому порядку. Внутрішній ідентифікатор використовується лише для стабільного порядку однакових дат і не повертається. Необов’язкові параметри: точний case_number, status (active, completed, canceled), date_from і date_to у форматі YYYY-MM-DD, limit (20, максимум 50) і offset. Без фільтрів дат за відсутнього статусу або зі статусом active повертаються лише активні засідання від часу кожного запиту; засідання, які вже почалися між сторінками, пропускаються. Явні дати дозволяють переглядати історію й усі статуси, якщо статус не задано. Статуси completed або canceled без дат також включають історію. Обидві календарні дати включні в часовому поясі Europe/Kyiv. Коментар і звіт повертаються за наявності; порожні необов’язкові поля відсутні. Пагінація за зміщенням охоплює засідання з однаковим часом, якщо результати не змінилися. Повторюйте потрібні фільтри в кожному запиті. Власник визначається лише автентифікацією. Успішна порожня сторінка також витрачає одну операцію.

GET /user-tasks і list_user_tasks потребують personal_data:read та повертають ваші завдання для неархівних справ: title, status, case_number, case_name та за наявності text і deadline. Необов’язкові фільтри: точний case_number, status (active або done), включні дати deadline_from і deadline_to у форматі YYYY-MM-DD за Europe/Kyiv. Ідентифікатори завдань не повертаються. Завдання впорядковані за дедлайном та внутрішнім ідентифікатором у зростаючому порядку; завдання без дедлайну йдуть останніми та не потрапляють у фільтр дат. limit типово 20, максимум 50; offset типово 0. Успішна порожня сторінка також витрачає одну операцію Pro.

GET /user-documents/unreviewed і list_unreviewed_documents потребують personal_data:read та повертають метадані чинних непереглянутих документів ваших відстежуваних справ у всіх статусах, включно з архівними. Відсутня, порожня або хибна власна позначка перегляду означає непереглянутий документ; за суперечливих дублікатів позначка перегляду має перевагу. Перегляди інших користувачів не впливають на список. Необов’язкові параметри: точний case_number, limit (типово 20, максимум 50) і offset. Документи впорядковано за внутрішнім ідентифікатором від новіших до старіших. Текст документів не повертається, а запит не позначає їх переглянутими. Успішна порожня сторінка витрачає одну операцію.

GET /user-documents/favorites і list_favorite_documents потребують personal_data:read та повертають метадані активних документів, які ви додали до обраного. Відстежувати їхні справи не потрібно. Повторні збереження не дублюють результати; неактивні й відсутні документи пропускаються. Параметри: необов’язковий точний case_number, limit (20, максимум 50), offset. Порядок — за внутрішнім ідентифікатором документа у спадному напрямку. Успішна порожня сторінка витрачає одну операцію. Текст документів не завантажується. За отриманим source_document_id можна окремо викликати get_document з дозволом court_data:read, щоб переглянути метадані й посилання на джерело.

Пошук проваджень потребує точного імені боржника (debtor_name, 3–255 символів, без урахування регістру). Необов’язкове debtor_birthdate має формат YYYY-MM-DD. Без дати пошук охоплює записи з невідомою датою; із датою — лише записи за цей календарний день. Збіг імені не доводить тотожність людини. Результати впорядковано за номером провадження; номер не є номером судової справи.

curl -G 'https://api.sudovispravy.com.ua/api/v1/enforcement-proceedings' \
  -H "Authorization: Bearer $COURT_DATA_API_KEY" \
  --data-urlencode 'debtor_name=Іван Петренко' \
  --data-urlencode 'debtor_birthdate=2001-01-02'

Ліміт і джерела

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

Відповідь документа містить метадані й, за наявності, посилання на джерело. Перевіряйте документ за цим посиланням, перш ніж посилатися на його зміст.

Відомості про виконавчі провадження імпортовані: статус не означає поточний стан у реєстрі. Час оновлення джерела та посилання на окремий запис не повертаються, оскільки їх не підтверджено. Відсутність результату не доводить відсутність проваджень.

Помилки REST

Помилка містить code, message та request_id. Значення request_id також повертається в заголовку X-Request-ID.

Для rate_limited REST повертає Retry-After: 60 і retry_after_seconds: 60. Для quota_exhausted ці значення та period_end повертаються, якщо вдалося прочитати період використання. Не повторюйте запити після вичерпання місячного ліміту до його оновлення.