API i webhookovi

Gdje se nalazi

Ako dokumenti u vašem uredu nastaju negdje drugdje, a ne u DocuTractu, taj sustav može izravno komunicirati s nama. Otvorite izbornik sa svojom adresom u gornjem desnom kutu i odaberite Integracije: ondje se izdaje token kojim nas vaš sustav poziva i ondje dodajete adresu na koju mu javljamo o gotovim dokumentima.

Zaslon počinje gotovim vezama s CRM-ovima (Integracije s CRM-om); tokeni i webhookovi opisani ovdje nalaze se ispod njih, u odjeljku API i webhookovi.

Token

Pritisnite Izradi token, dajte mu naziv koji ćete kasnije prepoznati (kako biste znali koji ga sustav koristi) i označite što smije raditi: čitati predloške, izrađivati dokumente, raditi s predmetima.

Sam token prikazuje se samo jednom, odmah nakon izrade: pohranjujemo samo njegov sažetak (hash) pa ga ni mi ne možemo prikazati drugi put. Kopirajte ga odmah u postavke svojeg sustava.

Popis prikazuje prve znakove svakog tokena, što smije raditi i kada je posljednji put korišten. Opozovi odmah isključuje token; zapis o njemu ostaje, pa se vidi da je postojao i kada je prestao raditi.

Što API može

Vaš sustav može:

• otvoriti predmet i učitati skenove u njega;
• izraditi dokument iz predloška s već upisanim vrijednostima;
• provjeriti u kojoj je fazi dokument;
• preuzeti sve vrijednosti zajedno sa skenom iz kojeg je svaka pročitana;
• dobiti kratkotrajnu poveznicu na gotovu datoteku.

Potpuni opis svake adrese i svakog polja generira se iz samog koda i javno je objavljen: opis API-ja.

Webhookovi

Umjesto da nas pitate je li dokument spreman, dajte nam adresu i mi ćemo vam se javiti. Dodajte je pod Webhookovi i označite događaje: dokument spreman, dokument nije uspio, predmet spreman, pronađeno neslaganje, klijent je poslao datoteku.

Svaki je zahtjev potpisan zaglavljem X-DocuTract-Signature, a tajni ključ kojim se potpis provjerava prikazuje se samo jednom, kao i token. Vaš sustav mora provjeriti potpis i odgovoriti kodom 2xx. Ako odgovori bilo čime drugim ili uopće ne odgovori, pokušavamo ponovno: nakon jedne minute, nakon pet, nakon pola sata, nakon dva sata i nakon deset, a zatim prestajemo.

Kad nešto nije stiglo

Gumb Isporuke prikazuje zapisnik: koji smo događaj poslali, kada, koliko puta, koji je kod odgovora vraćen i početak tijela odgovora. To je odgovor na „naš sustav nije ništa primio“: crno na bijelo piše da je četiri puta odgovorio s 500 u 14:12.

Pošalji test odmah šalje ping na adresu, bez čekanja na stvarni događaj, pa se primatelj može postaviti prije nego što kroz njega prođe ikakav posao. Pokušaj ponovno, pokraj neuspjele isporuke, odmah radi još jedan pokušaj.

Zapier, Make i n8n

No-code platforme (usluge u kojima se integracija slaže bez programiranja) same se pretplaćuju na naše događaje putem dijela API-ja za REST hooks, pa nitko ne mora kopirati njihove adrese u DocuTract. Dajte platformi token s dozvolama webhooks:read i webhooks:write te onima koje trebaju njezine radnje (na primjer templates:read i documents:write).

• POST /api/v1/hooks s {"event": "document.ready", "target_url": "https://…"} pretplaćuje adresu na jedan događaj. Odgovor sadrži id pretplate i, jednom, njezin secret za potpis.
• GET /api/v1/hooks navodi pretplate izrađene na taj način; DELETE /api/v1/hooks/{id} uklanja jednu.
• GET /api/v1/hooks/events navodi događaje: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} vraća primjer sadržaja, koji platforma prikazuje u svom „testnom okidaču” prije nego što se dogodi ijedan stvarni događaj.

Pretplata je obična adresa webhooka: jednako se potpisuje, ponavlja i bilježi u dnevnik te je vidljiva na popisu Webhookovi. Prestaje kad se token koji ju je izradio opozove ili istekne, ili kad platforma na isporuku odgovori kodom 410 Gone.

Ovako izgleda 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"
}

a ovako 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"
}

Polja predloška

GET /api/v1/templates/{id}/fields (dozvola templates:read) navodi što predložak treba: key svakog polja (po njemu se zadaju values u POST /api/v1/documents), njegov label, odakle se popunjava i fillable, koji je false za polje koje DocuTract popunjava sam, poput datuma. Obrazac u Zapieru ili Makeu gradi se iz tog popisa, pa uvijek odgovara predlošku u njegovu trenutačnom obliku.

Pretraživanje

Nekoliko poziva postoji kako bi sustav ili no-code platforma pronašli ono što im treba bez nagađanja:

• GET /api/v1/me (bez dopuštenja) vraća radni prostor kojem token pripada, njegov paket te naziv i dopuštenja samog tokena. To je najjednostavniji način da provjerite radi li token.
• GET /api/v1/documents (dopuštenje documents:read) prikazuje dokumente, najnovije prve. Suzite popis parametrima reference (točan broj DOC-…), status ili template_id; limit je najviše 100, zadano 25.
• GET /api/v1/cases (dopuštenje cases:read) prikazuje najnovije predmete, po želji samo one s jednim status, s istim limit. Svaki predmet sada ima i created_at.
• GET /api/v1/case-types (dopuštenje cases:read) navodi vrste predmeta iz kojih se može otvoriti predmet.
• GET /api/v1/templates?name=… zadržava samo predloške čiji naziv sadrži tekst, bez obzira na velika i mala slova.

Straničenja namjerno nema: ovi popisi služe za pronalaženje najnovijeg, a ne za izvoz cijelog radnog prostora.

Koji plan

API i webhookovi dio su plana Team. U svakom drugom planu tokeni i adrese koje ste već izradili ostaju vidljivi i mogu se opozvati, ali novi se ne izdaju, a pozivi upućeni tokenom više se ne poslužuju. Usporedite planove na stranici s cijenama.