API и вебхуки — Справка

Где это настраивается

Если документы в вашем офисе начинаются не в DocuTract, а в другой системе, её можно подключить напрямую. Откройте меню с вашим адресом в правом верхнем углу и выберите Интеграции: там выдаётся токен, которым ваша система обращается к нам, и добавляется адрес, на который мы сообщаем ей о готовых документах.

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

Раздел «Интеграции»: токены 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. На другом тарифе токены и адреса, которые вы уже создали, остаются видимыми, и их можно отозвать, но новые не создаются, а обращения по токену мы больше не обслуживаем. Сравнение тарифов — в статье Тарифы и оплата.