API in spletni kavlji

Kje to najdete

Če dokumenti v vaši pisarni nastajajo kje drugje kot v DocuTract, lahko ta sistem z nami komunicira neposredno. Odprite meni z vašim naslovom v zgornjem desnem kotu in izberite Integracije: tam izdate žeton, s katerim nas bo vaš sistem klical, in dodate naslov, na katerem ga bomo obveščali o končanih dokumentih.

Zaslon se začne s pripravljenimi povezavami s sistemi CRM (Integracije s CRM); tukaj opisani žetoni in spletni kavlji so pod njimi, v razdelku API in spletni kavlji.

Žeton

Pritisnite Ustvari žeton, mu dajte ime, ki ga boste pozneje prepoznali (da boste vedeli, kateri sistem ga uporablja), in označite, kaj sme početi: brati predloge, ustvarjati dokumente, delati z zadevami.

Sam žeton je prikazan samo enkrat, takoj ko je ustvarjen: shranimo le njegovo zgoščeno vrednost, zato ga drugič ne moremo prikazati niti mi. Kopirajte ga naravnost v nastavitve svojega sistema.

Seznam prikazuje prve znake vsakega žetona, kaj sme početi in kdaj je bil nazadnje uporabljen. Prekliči žeton takoj izklopi; zapis o njem ostane, tako da je razvidno, da je obstajal in kdaj je prenehal delovati.

Kaj zmore API

Vaš sistem lahko:

• odpre zadevo in vanjo naloži skene;
• ustvari dokument iz predloge z že izpolnjenimi vrednostmi;
• povpraša, v kateri fazi je dokument;
• prevzame vse vrednosti skupaj s skenom, iz katerega je bila vsaka prebrana;
• dobi kratkotrajno povezavo do končane datoteke.

Celoten opis vseh naslovov in polj se ustvari neposredno iz kode in je javno objavljen: opis API.

Spletni kavlji

Namesto da nas sprašujete, ali je dokument pripravljen, nam dajte naslov in pisali vam bomo mi. Dodajte ga v razdelku Spletni kavlji in označite dogodke: dokument je pripravljen, dokument ni uspel, zadeva je pripravljena, najdeno je neskladje, stranka je poslala datoteko.

Vsaka zahteva je podpisana z glavo X-DocuTract-Signature, skrivnost, s katero preverite podpis, pa je tako kot žeton prikazana samo enkrat. Vaš sistem mora preveriti podpis in odgovoriti s kodo 2xx. Če odgovori s čim drugim ali sploh ne odgovori, poskusimo znova: čez minuto, čez pet minut, čez pol ure, čez dve uri in čez deset ur, nato pa nehamo.

Ko nekaj ni prispelo

Gumb Dostave prikaže dnevnik: kateri dogodek smo poslali, kdaj, kolikokrat, katera odzivna koda se je vrnila in začetek telesa odgovora. To je odgovor na „naš sistem ni prejel ničesar“: črno na belem piše, da je ob 14.12 štirikrat odgovoril s kodo 500.

Pošlji preizkus takoj pošlje ping na naslov, ne da bi čakali na resničen dogodek, tako da lahko prejemnika nastavite, še preden skozenj steče kakršno koli delo. Poskusi znova ob neuspeli dostavi takoj izvede še en poskus.

Zapier, Make in n8n

Platforme no-code (storitve, v katerih se integracija sestavi brez programiranja) se na naše dogodke naročijo same, prek dela API-ja za REST hooks, zato nikomur ni treba kopirati njihovih naslovov v DocuTract. Platformi dajte žeton z dovoljenji webhooks:read in webhooks:write ter s tistimi, ki jih potrebujejo njena dejanja (na primer templates:read in documents:write).

• POST /api/v1/hooks z {"event": "document.ready", "target_url": "https://…"} naroči naslov na en dogodek. Odgovor vsebuje id naročnine in enkrat njen secret za podpis.
• GET /api/v1/hooks navede tako ustvarjene naročnine; DELETE /api/v1/hooks/{id} eno odstrani.
• GET /api/v1/hooks/events navede dogodke: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} vrne primer vsebine, ki ga platforma pokaže v svojem »preizkusnem sprožilcu«, še preden se zgodi pravi dogodek.

Naročnina je običajen naslov spletnega kavlja: enako se podpisuje, ponavlja in beleži ter je vidna na seznamu Spletni kavlji. Preneha, ko je žeton, ki jo je ustvaril, preklican ali poteče, ali ko platforma na dostavo odgovori s kodo 410 Gone.

Tako je videti 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"
}

in tako 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 predloge

GET /api/v1/templates/{id}/fields (dovoljenje templates:read) navede, kaj predloga potrebuje: key vsakega polja (po njem se podajajo values v POST /api/v1/documents), njegov label, od kod se izpolni, in fillable, ki je false za polje, ki ga DocuTract izpolni sam, na primer datum. Obrazec v Zapierju ali Maku se zgradi iz tega seznama, zato se vedno ujema s predlogo v njeni trenutni obliki.

Iskanje

Nekaj klicev obstaja zato, da sistem ali platforma no-code najde, kar potrebuje, brez ugibanja:

• GET /api/v1/me (brez dovoljenja) vrne delovni prostor, ki mu žeton pripada, njegov paket ter ime in dovoljenja samega žetona. To je najpreprostejši način, da preverite, ali žeton deluje.
• GET /api/v1/documents (dovoljenje documents:read) izpiše dokumente, najnovejše najprej. Zožite ga s parametri reference (natančna številka DOC-…), status ali template_id; limit je največ 100, privzeto 25.
• GET /api/v1/cases (dovoljenje cases:read) izpiše najnovejše zadeve, po želji samo tiste z enim status, z enakim limit. Vsaka zadeva ima zdaj tudi created_at.
• GET /api/v1/case-types (dovoljenje cases:read) našteje vrste zadev, iz katerih lahko odprete zadevo.
• GET /api/v1/templates?name=… obdrži samo predloge, katerih ime vsebuje besedilo, ne glede na velike in male črke.

Straničenja namenoma ni: ti seznami so za iskanje najnovejšega, ne za izvoz celotnega delovnega prostora.

Kateri paket

API in spletni kavlji so del paketa Team. V vseh drugih paketih ostanejo že ustvarjeni žetoni in naslovi vidni in jih je mogoče preklicati, novih pa ni mogoče izdati, klici z žetonom pa se ne izvajajo več. Pakete primerjajte na strani s cenami.