API резерву законодавства

Версія 1 · базова адреса https://zakon.automatizer.online/api/v1

Авторизація

Створіть ключ у розділі «Доступ до API» після корпоративного входу. Передавайте його в заголовку Authorization: Bearer zk_…. Ключ може діяти 1–90 днів або без обмеження строку. Його можна відкликати у будь-який момент. У запиті створення days: null означає безстроковий ключ; відповідь має expires: null. Не передавайте ключ у URL.

curl --get 'https://zakon.automatizer.online/api/v1/documents' \
  --header "Authorization: Bearer $ZAKON_API_KEY" \
  --data-urlencode 'q=медична практика' \
  --data-urlencode 'mode=title'

Законодавство

Потрібен дозвіл laws:read. Читання через API не додає записи до історії автоматично.

Метод і шлях	Призначення
`GET /documents`	Пошук і список карток
`GET /documents/{id}`	Картка, походження та доступні варіанти тексту
`GET /documents/{id}/texts/{text_id}`	Текст у JSON; `format=txt` — завантаження з відомостями про джерело
`GET /status`	Дата джерела, покриття й стан оновлення
`GET /documents/{id}/editions`	Підтверджені редакції; поле `coverage` вказує повноту даних
`GET /events`	Підтверджені події за `date_from` та `date_to`

Параметри пошуку

q — до 300 символів; слова поєднуються умовою «і», фраза в подвійних лапках шукається цілком. mode=title — назва, mode=all — повний текст і реквізити. Повнотекстовий індекс охоплює лише однозначно пов’язані картки й тексти.

number — точний номер; publisher — слова з назви органу; kind — точний вид акта; date_from, date_to — дати прийняття у форматі YYYY-MM-DD. sort: relevance, newest, oldest.

Сторінки: limit — 1–100, типово 20; offset — 0–10 000. Відповідь містить items, total, offset, limit і відбиток знімка snapshot. Це API для інтеграцій; масове вивантаження всього набору через пагінацію не передбачене.

Особисті дані

Ключ бачить лише історію та закладки свого власника. Для читання потрібен personal:read, для запису — personal:write.

Метод і шлях	Дія
`GET /history`	Історія, до 100 записів на сторінку
`POST /history`	Додати пошук або перегляд; поля kind, query, document_id, filters
`DELETE /history`	Очистити власну історію
`GET /bookmarks`	Закладки; необов’язкові folder, document_id, offset, limit
`POST /bookmarks`	Створити або оновити; поля document_id, folder, note
`DELETE /bookmarks/{id}`	Видалити власну закладку

Походження та обмеження даних

Джерело — відкритий набір Мін’юсту. source_modified_at — дата ресурсу, downloaded_at — дата отримання, currentness=not_verified — редакцію та чинність окремо не підтверджено.

binding=unique_code означає єдину картку й текст за кодом реєстру; ambiguous_code — кілька кандидатів, належність яких не підтверджено; missing_text — текст відсутній. Дублікати не вважаються редакціями.

Порожній список редакцій або подій із coverage=not_verified не означає, що інших редакцій чи подій немає. Повнота цих відомостей у першій версії не підтверджена.

Обмеження й помилки

До 180 авторизованих запитів за хвилину на користувача, спільно для його ключів і браузерних сеансів. Максимальний розмір запиту — 64 КБ. HTTPS обов’язковий. Міждоменний доступ із браузерів не ввімкнено.

401 — немає чинного доступу; 403 — бракує дозволу; 404 — запис не знайдено; 422 — неправильні параметри; 429 — перевищено частоту запитів; 503 — база або запит тимчасово недоступні. Текст пояснення міститься в полі detail.