API și webhookuri

Unde le găsiți

Dacă documentele din biroul dvs. pornesc din alt loc decât DocuTract, acel sistem poate comunica direct cu noi. Deschideți meniul cu adresa dvs. din colțul din dreapta sus și alegeți Integrări: acolo se emite un token cu care sistemul dvs. ne apelează și acolo adăugați adresa pe care o anunțăm despre documentele finalizate.

Ecranul începe cu conexiunile gata făcute cu CRM-uri (Integrări cu CRM); tokenurile și webhookurile descrise aici sunt dedesubt, în secțiunea API și webhookuri.

Tokenul

Apăsați Creați un token, dați-i un nume pe care îl veți recunoaște mai târziu (ca să știți ce sistem îl folosește) și bifați ce are voie să facă: să citească șabloane, să creeze documente, să lucreze cu dosare.

Tokenul însuși este afișat o singură dată, imediat după creare: stocăm doar un hash al lui, așa că nici măcar noi nu îl putem afișa a doua oară. Copiați-l direct în setările sistemului dvs.

Lista arată primele caractere ale fiecărui token, ce are voie să facă și când a fost folosit ultima dată. Revocați dezactivează imediat un token; înregistrarea lui rămâne, astfel încât se vede că a existat și când a încetat să funcționeze.

Ce poate face API-ul

Sistemul dvs. poate:

• să deschidă un dosar și să încarce scanări în el;
• să creeze un document dintr-un șablon cu valorile deja completate;
• să întrebe în ce stadiu a ajuns un document;
• să preia fiecare valoare împreună cu scanarea din care a fost citită;
• să obțină un link cu durată scurtă către fișierul finalizat.

Descrierea completă a fiecărei adrese și a fiecărui câmp este generată din codul însuși și publicată deschis: descrierea API.

Webhookuri

În loc să ne întrebați dacă un document este gata, dați-ne o adresă și vă scriem noi. Adăugați-o la Webhookuri și bifați evenimentele: document gata, document eșuat, dosar gata, neconcordanță găsită, un client a trimis un fișier.

Fiecare cerere este semnată cu antetul X-DocuTract-Signature, iar secretul care verifică semnătura este afișat o singură dată, ca și tokenul. Sistemul dvs. trebuie să verifice semnătura și să răspundă cu un cod 2xx. Dacă răspunde altceva sau nu răspunde deloc, încercăm din nou: după un minut, după cinci, după o jumătate de oră, după două ore și după zece, apoi ne oprim.

Când ceva nu a ajuns

Butonul Livrări afișează jurnalul: ce eveniment am trimis, când, de câte ori, ce cod de răspuns a venit înapoi și începutul corpului răspunsului. Acesta este răspunsul la „sistemul nostru nu a primit nimic”: scrie negru pe alb că a răspuns 500 de patru ori la 14:12.

Trimiteți un test trimite chiar acum un ping la adresă, fără să aștepte un eveniment real, astfel încât un receptor poate fi configurat înainte să treacă vreo lucrare prin el. Reîncercați, lângă o livrare eșuată, face imediat încă o încercare.

Zapier, Make și n8n

Platformele no-code (servicii în care o integrare se construiește fără programare) se abonează singure la evenimentele noastre, prin partea de REST hooks a API-ului, așa că nimeni nu trebuie să le copieze adresele în DocuTract. Dați platformei un token cu permisiunile webhooks:read și webhooks:write, plus cele de care au nevoie acțiunile ei (de exemplu, templates:read și documents:write).

• POST /api/v1/hooks cu {"event": "document.ready", "target_url": "https://…"} abonează o adresă la un eveniment. Răspunsul conține id-ul abonamentului și, o singură dată, secret-ul lui de semnătură.
• GET /api/v1/hooks listează abonamentele create astfel; DELETE /api/v1/hooks/{id} elimină unul.
• GET /api/v1/hooks/events listează evenimentele: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} întoarce un exemplu de conținut, pe care platforma îl arată în „declanșatorul de test” înainte să fi avut loc vreun eveniment real.

Un abonament este o adresă de webhook obișnuită: semnată, reîncercată și înregistrată la fel și vizibilă în lista Webhookuri. Se oprește când tokenul care l-a creat este revocat sau expiră, ori când platforma răspunde la o livrare cu 410 Gone.

Așa arată 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"
}

și așa 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"
}

Câmpurile unui șablon

GET /api/v1/templates/{id}/fields (permisiunea templates:read) listează de ce are nevoie un șablon: key-ul fiecărui câmp (după care se dau values în POST /api/v1/documents), label-ul lui, de unde se completează și fillable, care este false pentru un câmp pe care DocuTract îl completează singur, cum ar fi o dată. Un formular în Zapier sau Make se construiește din această listă, așa că se potrivește mereu cu șablonul așa cum este acum.

Căutări

Câteva apeluri există pentru ca un sistem, sau o platformă no-code, să găsească ce îi trebuie fără să ghicească:

• GET /api/v1/me (fără permisiune) întoarce spațiul de lucru căruia îi aparține tokenul, planul lui, precum și numele și permisiunile tokenului însuși. Este cea mai simplă cale de a verifica dacă un token funcționează.
• GET /api/v1/documents (permisiunea documents:read) listează documentele, cele mai noi primele. Restrângeți cu reference (numărul DOC-… exact), status sau template_id; limit merge până la 100, implicit 25.
• GET /api/v1/cases (permisiunea cases:read) listează cele mai noi dosare, la nevoie doar pe cele cu un anumit status, cu același limit. Fiecare dosar are acum și câmpul created_at.
• GET /api/v1/case-types (permisiunea cases:read) listează tipurile de dosar din care se poate deschide un dosar.
• GET /api/v1/templates?name=… păstrează doar șabloanele al căror nume conține textul, fără a ține cont de majuscule.

Paginarea lipsește intenționat: aceste liste servesc la găsirea celor mai noi elemente, nu la exportul unui întreg spațiu de lucru.

Ce plan

API-ul și webhookurile fac parte din planul Team. În orice alt plan, tokenurile și adresele deja create rămân vizibile și pot fi revocate, dar nu se mai emit altele noi, iar apelurile făcute cu un token nu mai sunt servite. Comparați planurile pe pagina de prețuri.