API ir webhook'ai

Kur tai rasti

Jei dokumentai jūsų biure atsiranda ne DocuTract, o kitoje sistemoje, ta sistema gali bendrauti su mumis tiesiogiai. Atidarykite meniu su savo adresu viršutiniame dešiniajame kampe ir pasirinkite Integracijos: čia išduodamas prieigos raktas, kuriuo jūsų sistema kreipsis į mus, ir čia pridedate adresą, kuriuo pranešime apie paruoštus dokumentus.

Ekranas prasideda paruoštais CRM ryšiais (CRM integracijos); čia aprašyti prieigos raktai ir webhook'ai yra po jais, skiltyje API ir webhook'ai.

Prieigos raktas

Paspauskite Sukurti prieigos raktą, suteikite jam pavadinimą, kurį vėliau atpažinsite (kad žinotumėte, kuri sistema jį naudoja), ir pažymėkite, ką jam leidžiama daryti: skaityti šablonus, kurti dokumentus, dirbti su bylomis.

Pats raktas parodomas vieną kartą, iškart po sukūrimo: saugome tik jo maišos reikšmę (hash), todėl parodyti jį antrą kartą negalime net mes. Nukopijuokite jį tiesiai į savo sistemos nustatymus.

Sąraše matyti kiekvieno rakto pirmieji simboliai, ką jis gali daryti ir kada buvo paskutinį kartą naudotas. Atšaukti iškart išjungia raktą; įrašas apie jį lieka, todėl matyti, kad jis egzistavo ir kada nustojo veikti.

Ką galima daryti per API

Jūsų sistema gali:

• atidaryti bylą ir įkelti į ją skenus;
• sukurti dokumentą iš šablono su jau užpildytomis reikšmėmis;
• sužinoti, kuriame etape yra dokumentas;
• gauti visas reikšmes kartu su skenu, iš kurio kiekviena buvo nuskaityta;
• gauti trumpalaikę nuorodą į paruoštą failą.

Išsamus kiekvieno adreso ir lauko aprašas generuojamas tiesiai iš kodo ir skelbiamas viešai: API aprašas.

Webhook'ai

Užuot klausę mūsų, ar dokumentas jau paruoštas, nurodykite adresą – ir mes jums parašysime patys. Pridėkite jį skiltyje Webhook'ai ir pažymėkite įvykius: dokumentas paruoštas, dokumento nepavyko parengti, byla paruošta, rastas neatitikimas, klientas atsiuntė failą.

Kiekviena užklausa pasirašoma antrašte X-DocuTract-Signature, o slaptas raktas parašui patikrinti parodomas vieną kartą, kaip ir prieigos raktas. Jūsų sistema turi patikrinti parašą ir atsakyti 2xx kodu. Jei ji atsako kitaip arba visai neatsako, bandome dar kartą: po minutės, po penkių, po pusvalandžio, po dviejų valandų ir po dešimties, o tada liaujamės.

Kai kas nors neatėjo

Mygtukas Pristatymai rodo žurnalą: kokį įvykį išsiuntėme, kada, kiek kartų, koks atsakymo kodas grįžo ir atsakymo turinio pradžia. Tai ir yra atsakymas į „mūsų sistema nieko negavo“: čia juodu ant balto parašyta, kad 14:12 ji keturis kartus atsakė 500.

Siųsti bandomąjį iškart išsiunčia ping tuo adresu, nelaukiant tikro įvykio, todėl gavėją galima paruošti dar prieš pradedant per jį dirbti. Bandyti dar kartą šalia nepavykusio pristatymo iškart atlieka dar vieną bandymą.

Zapier, Make ir n8n

No-code platformos (paslaugos, kuriose integracija sudedama neprogramuojant) pačios užsiprenumeruoja mūsų įvykius per API REST hooks dalį, todėl niekam nereikia kopijuoti jų adresų į DocuTract. Suteikite platformai prieigos raktą su leidimais webhooks:read ir webhooks:write, taip pat tais, kurių reikia jos veiksmams (pavyzdžiui, templates:read ir documents:write).

• POST /api/v1/hooks su {"event": "document.ready", "target_url": "https://…"} užprenumeruoja adresą vienam įvykiui. Atsakyme yra prenumeratos id ir vieną kartą jos parašo secret.
• GET /api/v1/hooks išvardija taip sukurtas prenumeratas; DELETE /api/v1/hooks/{id} vieną pašalina.
• GET /api/v1/hooks/events išvardija įvykius: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} grąžina turinio pavyzdį, kurį platforma rodo savo „bandomajame paleidiklyje“ dar prieš įvykstant tikram įvykiui.

Prenumerata yra įprastas webhook'o adresas: taip pat pasirašomas, kartojamas ir registruojamas žurnale bei matomas sąraše Webhook'ai. Ji baigiasi, kai ją sukūręs prieigos raktas atšaukiamas ar nustoja galioti arba kai platforma į pristatymą atsako kodu 410 Gone.

Taip atrodo 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"
}

o taip 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"
}

Šablono laukai

GET /api/v1/templates/{id}/fields (leidimas templates:read) išvardija, ko reikia šablonui: kiekvieno lauko key (pagal jį nurodomos values užklausoje POST /api/v1/documents), jo label, iš kur jis pildomas, ir fillable, kuris lygus false laukui, kurį DocuTract užpildo pats, pavyzdžiui, datai. Forma Zapier ar Make kuriama iš šio sąrašo, todėl visada atitinka šabloną tokį, koks jis yra dabar.

Paieška

Keli iškvietimai yra tam, kad sistema ar no-code platforma rastų, ko reikia, nespėliodama:

• GET /api/v1/me (leidimo nereikia) grąžina darbo sritį, kuriai priklauso prieigos raktas, jos planą ir paties rakto pavadinimą bei leidimus. Tai paprasčiausias būdas patikrinti, ar raktas veikia.
• GET /api/v1/documents (leidimas documents:read) rodo dokumentus, naujausius pirmiau. Susiaurinkite parametrais reference (tikslus DOC-… numeris), status arba template_id; limit – iki 100, numatytasis 25.
• GET /api/v1/cases (leidimas cases:read) rodo naujausias bylas, jei norite – tik su vienu status, su tuo pačiu limit. Kiekviena byla dabar turi ir created_at.
• GET /api/v1/case-types (leidimas cases:read) išvardija bylų tipus, iš kurių galima atidaryti bylą.
• GET /api/v1/templates?name=… palieka tik šablonus, kurių pavadinime yra šis tekstas, neatsižvelgiant į raidžių dydį.

Puslapiavimo sąmoningai nėra: šie sąrašai skirti naujausiems įrašams rasti, o ne visai darbo sričiai eksportuoti.

Kuris planas

API ir webhook'ai yra Team plano dalis. Taikant bet kurį kitą planą jau sukurti prieigos raktai ir adresai lieka matomi ir juos galima atšaukti, tačiau nauji neišduodami, o užklausos su prieigos raktu nebeaptarnaujamos. Palyginkite planus kainų puslapyje.