API і вебхуки

Де це налаштовується

Якщо документи у вашому офісі починаються не в DocuTract, а в іншій системі, її можна підключити напряму. Відкрийте меню з вашою адресою у правому верхньому куті і виберіть Інтеграції: там видається токен, яким ваша система звертається до нас, і додається адреса, на яку ми повідомляємо їй про готові документи.

Сторінка починається з готових підключень до CRM (Інтеграції з CRM); токени й вебхуки, про які тут ідеться, розташовані нижче, у розділі API і вебхуки.

Токен

Натисніть Створити токен, дайте йому назву, за якою ви потім упізнаєте, хто ним користується, і позначте, що йому дозволено: читати шаблони, створювати документи, працювати зі справами. Готовий токен показується один раз, відразу після створення: ми зберігаємо лише його хеш (незворотний «відбиток»), тож показати його вдруге не можемо навіть ми. Скопіюйте його одразу в налаштування вашої системи.

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

Що вміє API

Ваша система може створити справу й завантажити в неї скани, створити документ із шаблона одразу зі значеннями, спитати, на якій він стадії, забрати всі значення разом із тим, з якого скана кожне прочитано, і отримати короткочасне посилання на готовий файл. Повний опис усіх адрес і полів ми генеруємо з самого коду і публікуємо відкрито: опис API.

Вебхуки

Вебхук — це адреса у вашій системі, на яку ми самі надсилаємо повідомлення про подію. Замість того щоб питати нас, чи готовий документ, дайте адресу, на яку ми напишемо самі. Додайте її в розділі Вебхуки кнопкою Додати адресу і позначте події: документ готовий, документ не згенерувався, справа готова, знайдено розбіжність, клієнт надіслав файл.

Кожен запит ми підписуємо заголовком X-DocuTract-Signature, а секрет для перевірки підпису показуємо один раз, як і токен. Ваша система має перевірити підпис і відповісти кодом 2xx. Якщо вона відповіла інакше або не відповіла зовсім, ми повторимо: через хвилину, через п'ять, через півгодини, через дві години і через десять, а потім припинимо.

Коли щось не дійшло

Кнопка Доставки показує журнал: яку подію ми надсилали, коли, скільки разів, який код відповіді отримали і початок тіла відповіді. Це і є відповідь на «наша система нічого не отримала»: видно, що вона відповідала 500 чотири рази о 14:12.

Тест надсилає на адресу пробний запит ping просто зараз, не чекаючи справжньої події, тож налаштувати приймач можна до того, як через нього піде робота. Повторити біля невдалої доставки робить ще одну спробу негайно.

Zapier, Make і n8n

No-code платформи (сервіси, де інтеграцію збирають без програмування) підписуються на наші події самі, через частину API для REST-хуків, тож нікому не треба копіювати їхні адреси в DocuTract. Дайте платформі токен із дозволами webhooks:read і webhooks:write, а також тими, що потрібні її діям (наприклад, templates:read і documents:write).

• POST /api/v1/hooks з {"event": "document.ready", "target_url": "https://…"} підписує адресу на одну подію. Відповідь містить id підписки і, один раз, її secret для підпису.
• GET /api/v1/hooks показує підписки, створені так; DELETE /api/v1/hooks/{id} видаляє одну з них.
• GET /api/v1/hooks/events перелічує події: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} повертає приклад вмісту події, який платформа показує в «тестовому тригері», ще до першої справжньої події.

Підписка це звичайна адреса вебхука: так само підписується, повторюється і записується в журнал, і її видно у списку Вебхуки. Вона припиняє діяти, коли токен, що її створив, відкликано або він закінчився, або коли платформа відповідає на доставку кодом 410 Gone.

Так виглядає document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

а так case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

Поля шаблону

GET /api/v1/templates/{id}/fields (дозвіл templates:read) показує, що потрібно шаблону: key кожного поля (за ним ключуються values у POST /api/v1/documents), його label, звідки воно заповнюється, і fillable, яке дорівнює false для поля, що його DocuTract заповнює сам, як-от дата. Форма в Zapier чи Make будується з цього списку, тож завжди відповідає шаблону в його поточному вигляді.

Пошук і довідники

Кілька викликів існують для того, щоб система чи no-code платформа знаходила потрібне без здогадок:

• GET /api/v1/me (без дозволу) повертає робочий простір, якому належить токен, його тариф, а також назву й дозволи самого токена. Це найпростіший спосіб перевірити, що токен працює.
• GET /api/v1/documents (дозвіл documents:read) показує документи, найновіші першими. Звузити список можна параметрами reference (точний номер DOC-…), status або template_id; limit — до 100, за замовчуванням 25.
• GET /api/v1/cases (дозвіл cases:read) показує найновіші справи, за бажанням лише з одним status, з тим самим limit. Кожна справа тепер має й поле created_at.
• GET /api/v1/case-types (дозвіл cases:read) перелічує типи справ, з яких можна відкрити справу.
• GET /api/v1/templates?name=… залишає лише шаблони, у назві яких є цей текст, без огляду на регістр.

Посторінкового виведення немає навмисно: ці списки — щоб знайти останнє, а не щоб вивантажити весь робочий простір.

Тариф

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