API u webhooks

Fejn issibha

Jekk id-dokumenti fl-uffiċċju tiegħek jibdew x'imkien ieħor minflok DocuTract, dik is-sistema tista' titkellem magħna direttament. Iftaħ il-menu bl-indirizz tiegħek fil-kantuniera ta' fuq fuq il-lemin u agħżel Integrazzjonijiet: hemmhekk joħroġ token li bih is-sistema tiegħek issejħilna, u hemmhekk iżżid l-indirizz li fuqu ngħarrfuha bid-dokumenti lesti.

L-iskrin jibda bil-konnessjonijiet lesti mas-CRMs (Integrazzjonijiet mas-CRM); it-tokens u l-webhooks deskritti hawn jinsabu taħthom, fit-taqsima API u webhooks.

It-token

Agħfas Oħloq token, agħtih isem li tagħrfu aktar tard (biex tkun taf liema sistema qed tużah), u mmarka x'inhu permess jagħmel: jaqra l-mudelli, joħloq dokumenti, jaħdem bil-każijiet.

It-token innifsu jintwera darba, eżatt wara li jinħoloq: aħna nżommu biss hash tiegħu, għalhekk li nuruh it-tieni darba huwa xi ħaġa li lanqas aħna ma nistgħu nagħmlu. Ikkopjah dritt fis-settings tas-sistema tiegħek.

Il-lista turi l-ewwel karattri ta' kull token, x'jista' jagħmel, u meta ntuża l-aħħar darba. Irrevoka itfi token minnufih; ir-rekord tiegħu jibqa', biex jidher li kien jeżisti u meta waqaf jaħdem.

X'tista' tagħmel l-API

Is-sistema tiegħek tista':

• tiftaħ każ u ttella' skans fih;
• toħloq dokument minn mudell bil-valuri diġà mimlija;
• tistaqsi f'liema stadju wasal dokument;
• tieħu kull valur flimkien mal-iskan minn fejn inqara;
• tikseb link ta' ħajja qasira għall-fajl lest.

Id-deskrizzjoni sħiħa ta' kull indirizz u qasam tiġi ġġenerata mill-kodiċi nnifsu u ppubblikata b'mod miftuħ: id-deskrizzjoni tal-API.

Webhooks

Minflok ma tistaqsina jekk dokument huwiex lest, agħtina indirizz u aħna niktbulek. Żidu taħt Webhooks u mmarka l-avvenimenti: dokument lest, dokument falla, każ lest, nstabet diskrepanza, klijent bagħat fajl.

Kull talba hija ffirmata bl-header X-DocuTract-Signature, u s-sigriet li jivverifika l-firma jintwera darba, bħat-token. Is-sistema tiegħek trid tiċċekkja l-firma u twieġeb b'kodiċi 2xx. Jekk twieġeb b'xi ħaġa oħra, jew ma twieġeb xejn, nerġgħu nippruvaw: wara minuta, wara ħamsa, wara nofs siegħa, wara sagħtejn u wara għaxra, u mbagħad nieqfu.

Meta xi ħaġa ma waslitx

Il-buttuna Kunsinni turi r-reġistru: liema avveniment bgħatna, meta, kemm-il darba, liema kodiċi ta' tweġiba ġie lura u l-bidu tal-ġisem tat-tweġiba. Dik hija t-tweġiba għal «is-sistema tagħna ma rċeviet xejn»: hemm bil-miktub li wieġbet 500 erba' darbiet fl-14:12.

Ibgħat test jibgħat ping lill-indirizz issa stess, mingħajr ma jistenna avveniment reali, biex riċevitur ikun jista' jitwaqqaf qabel ma jgħaddi xi xogħol minnu. Erġa' pprova, ħdejn kunsinna li falliet, jagħmel tentattiv ieħor minnufih.

Zapier, Make u n8n

Il-pjattaformi no-code (servizzi fejn integrazzjoni tinbena mingħajr programmar) jabbonaw waħedhom għall-avvenimenti tagħna, permezz tal-parti REST hooks tal-API, għalhekk ħadd m'għandu għalfejn jikkopja l-indirizzi tagħhom f'DocuTract. Agħti lill-pjattaforma token bil-permessi webhooks:read u webhooks:write, flimkien ma' dawk li jeħtieġu l-azzjonijiet tagħha (pereżempju templates:read u documents:write).

• POST /api/v1/hooks b'{"event": "document.ready", "target_url": "https://…"} jabbona indirizz għal avveniment wieħed. It-tweġiba fiha l-id tal-abbonament u, darba biss, is-secret tal-firma tiegħu.
• GET /api/v1/hooks jelenka l-abbonamenti maħluqa b'dan il-mod; DELETE /api/v1/hooks/{id} ineħħi wieħed.
• GET /api/v1/hooks/events jelenka l-avvenimenti: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} jagħti eżempju tal-kontenut, li l-pjattaforma turi fit-"trigger tat-test" tagħha qabel ma jkun seħħ xi avveniment veru.

Abbonament huwa indirizz tal-webhook normali: iffirmat, ripetut u reġistrat bl-istess mod, u jidher fil-lista Webhooks. Jieqaf meta t-token li ħolqu jiġi revokat jew jiskadi, jew meta l-pjattaforma twieġeb kunsinna b'410 Gone.

Hekk jidher 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"
}

u hekk 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"
}

L-oqsma ta' mudell

GET /api/v1/templates/{id}/fields (permess templates:read) jelenka dak li jeħtieġ mudell: il-key ta' kull qasam (li bih jingħataw il-values f'POST /api/v1/documents), il-label tiegħu, minn fejn jimtela, u fillable, li huwa false għal qasam li DocuTract jimla waħdu, bħal data. Formola f'Zapier jew Make tinbena minn din il-lista, għalhekk dejjem taqbel mal-mudell kif inhu issa.

Tfittxijiet

Xi sejħiet jeżistu biex sistema, jew pjattaforma no-code, issib dak li għandha bżonn mingħajr ma taqta' b'moħħha:

• GET /api/v1/me (bla permess) jagħti l-ispazju tax-xogħol li jappartjeni għalih it-token, il-pjan tiegħu, u l-isem u l-permessi tat-token innifsu. Huwa l-aktar mod sempliċi biex tiċċekkja li token jaħdem.
• GET /api/v1/documents (permess documents:read) jelenka d-dokumenti, l-aktar ġodda l-ewwel. Naqqas il-lista b'reference (ir-referenza DOC-… eżatta), status jew template_id; limit jasal sa 100, 25 b'mod awtomatiku.
• GET /api/v1/cases (permess cases:read) jelenka l-aktar każijiet ġodda, jekk trid dawk b'status wieħed biss, bl-istess limit. Kull każ issa għandu wkoll created_at.
• GET /api/v1/case-types (permess cases:read) jelenka t-tipi ta' każ li minnhom jista' jinfetaħ każ.
• GET /api/v1/templates?name=… iżomm biss il-mudelli li isimhom fih it-test, irrispettivament mill-ittri kbar u żgħar.

M'hemmx paġnar apposta: dawn il-listi huma biex issib l-aħħar elementi, mhux biex tesporta spazju tax-xogħol sħiħ.

Liema pjan

L-API u l-webhooks huma parti mill-pjan Team. Fuq kull pjan ieħor, it-tokens u l-indirizzi li diġà ħloqt jibqgħu jidhru u jistgħu jiġu rrevokati, iżda ma joħorġux oħrajn ġodda, u s-sejħiet magħmula b'token ma jibqgħux jiġu moqdija. Qabbel il-pjanijiet fuq il-paġna tal-prezzijiet.