API и уебхукове

Къде да го намерите

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

Екранът започва с готовите връзки с CRM (Интеграции с CRM); описаните тук токени и уебхукове са под тях, в раздела API и уебхукове.

Токенът

Натиснете Създай токен, дайте му име, което ще разпознаете по-късно (за да знаете коя система го използва), и отметнете какво му е позволено: да чете шаблони, да създава документи, да работи с дела.

Самият токен се показва веднъж, веднага след създаването: пазим само хеш от него, така че да го покажем втори път не можем дори ние. Копирайте го направо в настройките на системата си.

Списъкът показва първите знаци на всеки токен, какво може да прави и кога е използван за последно. Отмени изключва токена незабавно; записът за него остава, така че се вижда, че е съществувал и кога е спрял да работи.

Какво може API

Вашата система може:

• да отвори дело и да качи сканове в него;
• да създаде документ от шаблон с вече попълнени стойности;
• да попита до кой етап е стигнал документът;
• да вземе всяка стойност заедно със скана, от който е прочетена;
• да получи краткотраен линк към готовия файл.

Пълното описание на всеки адрес и поле се генерира от самия код и се публикува открито: описанието на API.

Уебхукове

Вместо да ни питате дали документът е готов, дайте ни адрес и ние ще ви пишем. Добавете го в Уебхукове и отметнете събитията: документът е готов, документът е неуспешен, делото е готово, открито е разминаване, клиент е изпратил файл.

Всяка заявка е подписана със заглавката X-DocuTract-Signature, а тайният ключ, с който се проверява подписът, се показва веднъж, както токенът. Системата ви трябва да провери подписа и да отговори с код 2xx. Ако отговори с нещо друго или изобщо не отговори, опитваме отново: след минута, след пет, след половин час, след два часа и след десет, а след това спираме.

Когато нещо не е пристигнало

Бутонът Доставки показва журнала: кое събитие сме изпратили, кога, колко пъти, какъв код на отговор се е върнал и началото на тялото на отговора. Това е отговорът на „нашата система не получи нищо“: там черно на бяло пише, че тя е отговорила с 500 четири пъти в 14:12.

Изпрати тест изпраща ping до адреса веднага, без да чака реално събитие, така че получателят да може да се настрои, преди през него да мине каквато и да е работа. Опитай отново до неуспешна доставка прави още един опит незабавно.

Zapier, Make и n8n

No-code платформите (услуги, в които интеграция се сглобява без програмиране) сами се абонират за нашите събития чрез частта на API за REST hooks, така че никой не трябва да копира адресите им в 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. На всеки друг план токените и адресите, които вече сте създали, остават видими и могат да бъдат отменени, но нови не се издават, а заявките с токен вече не се обслужват. Сравнете плановете на страницата с цените.