API agus crúcaí gréasáin

Cá bhfaighidh tú é

Má thosaíonn doiciméid i d’oifig áit éigin seachas DocuTract, is féidir leis an gcóras sin labhairt linn go díreach. Oscail an roghchlár le do sheoladh sa chúinne ar barr ar dheis agus roghnaigh Comhtháthuithe: sin an áit a n-eisítear comhartha a úsáideann do chóras chun glaoch orainn, agus an áit a gcuireann tú leis an seoladh a gcuirimid scéala chuige faoi dhoiciméid chríochnaithe.

Tosaíonn an scáileán leis na naisc réamhdhéanta le CRManna (Comhtháthuithe CRM); tá na comharthaí agus na crúcaí gréasáin a bhfuil cur síos orthu anseo thíos fúthu, sa chuid API agus crúcaí gréasáin.

An comhartha

Brúigh Cruthaigh comhartha, tabhair ainm dó a aithneoidh tú níos déanaí (ionas go mbeidh a fhios agat cén córas atá á úsáid), agus cuir tic leis an méid a bhfuil cead aige a dhéanamh: teimpléid a léamh, doiciméid a chruthú, oibriú le cásanna.

Taispeántar an comhartha féin uair amháin, díreach tar éis é a chruthú: ní stórálaimid ach haiseáil de, mar sin ní féidir fiú linne é a thaispeáint an dara huair. Cóipeáil díreach isteach i socruithe do chórais é.

Taispeánann an liosta na chéad charachtair de gach comhartha, an méid atá ceadaithe dó, agus cathain a úsáideadh é go deireanach. Múchann Cúlghair comhartha láithreach; fanann an taifead air, ionas go mbeidh sé le feiceáil go raibh sé ann agus cathain a stop sé ag obair.

Cad is féidir leis an API a dhéanamh

Is féidir le do chóras:

• cás a oscailt agus scananna a uaslódáil isteach ann;
• doiciméad a chruthú ó theimpléad agus na luachanna líonta isteach cheana;
• fiafraí cén chéim ag a bhfuil doiciméad;
• gach luach a fháil in éineacht leis an scanadh ar léadh é as;
• nasc gearrshaolach chuig an gcomhad críochnaithe a fháil.

Gintear an cur síos iomlán ar gach seoladh agus réimse ón gcód féin agus foilsítear go hoscailte é: cur síos an API.

Crúcaí gréasáin

In áit fiafraí dínn an bhfuil doiciméad réidh, tabhair seoladh dúinn agus scríobhfaimid chugat. Cuir leis é faoi Crúcaí gréasáin agus cuir tic leis na teagmhais: doiciméad réidh, theip ar dhoiciméad, cás réidh, easaontas aimsithe, chuir cliant comhad.

Síníonn an ceanntásc X-DocuTract-Signature gach iarratas, agus taispeántar an rún a fhíoraíonn an síniú uair amháin, díreach mar an comhartha. Caithfidh do chóras an síniú a sheiceáil agus cód 2xx a thabhairt mar fhreagra. Má fhreagraíonn sé aon rud eile, nó mura bhfreagraíonn sé ar chor ar bith, déanaimid iarracht arís: tar éis nóiméid, tar éis cúig nóiméad, tar éis leathuair an chloig, tar éis dhá uair an chloig agus tar éis deich n-uaire an chloig, agus ansin stopaimid.

Nuair nár tháinig rud éigin

Taispeánann an cnaipe Seachadtaí an logchomhad: cén teagmhas a sheolamar, cathain, cé mhéad uair, cén cód freagartha a tháinig ar ais agus tús chorp an fhreagra. Sin an freagra ar “ní bhfuair ár gcóras faic”: tá sé ann i scríbhinn gur fhreagair sé 500 ceithre huaire ag 14:12.

Cuireann Seol tástáil ping chuig an seoladh láithreach, gan fanacht le teagmhas fíor, ionas gur féidir glacadóir a shocrú sula dtéann aon obair tríd. Déanann Triail arís, in aice le seachadadh a theip, iarracht amháin eile láithreach.

Zapier, Make agus n8n

Liostálann ardáin gan chód (seirbhísí ina gcuirtear comhtháthú le chéile gan ríomhchlárú) lenár dteagmhais iad féin, trí chuid REST hooks an API, mar sin ní gá do dhuine ar bith a seoltaí a chóipeáil isteach in DocuTract. Tabhair comhartha don ardán leis na ceadanna webhooks:read agus webhooks:write, chomh maith leo siúd a theastaíonn óna ghníomhartha (mar shampla templates:read agus documents:write).

• Liostálann POST /api/v1/hooks le {"event": "document.ready", "target_url": "https://…"} seoladh le haghaidh teagmhais amháin. Tá id an tsíntiúis sa fhreagra agus, uair amháin, a secret sínithe.
• Liostaíonn GET /api/v1/hooks na síntiúis a cruthaíodh ar an mbealach seo; baineann DELETE /api/v1/hooks/{id} ceann acu.
• Liostaíonn GET /api/v1/hooks/events na teagmhais: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• Tugann GET /api/v1/hooks/samples/{event} sampla den ábhar ar ais, a thaispeánann an t-ardán ina "truicear tástála" sula dtarlaíonn aon teagmhas fíor.

Is gnáthsheoladh crúca gréasáin é síntiús: sínítear, atriailtear agus logáiltear é ar an mbealach céanna, agus tá sé le feiceáil sa liosta Crúcaí gréasáin. Stopann sé nuair a chúlghairtear an comhartha a chruthaigh é nó nuair a théann sé in éag, nó nuair a fhreagraíonn an t-ardán seachadadh le 410 Gone.

Seo mar atá 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"
}

agus 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"
}

Réimsí teimpléid

Liostaíonn GET /api/v1/templates/{id}/fields (cead templates:read) a bhfuil de dhíth ar theimpléad: key gach réimse (an eochair do na values in POST /api/v1/documents), a label, cá háit a líontar é, agus fillable, atá false do réimse a líonann DocuTract féin, ar nós dáta. Tógtar foirm in Zapier nó in Make ón liosta seo, mar sin bíonn sí i gcónaí ag teacht leis an teimpléad mar atá sé anois.

Cuardaigh

Tá roinnt glaonna ann ionas go n-aimseoidh córas, nó ardán gan chód, an rud a theastaíonn uaidh gan buille faoi thuairim:

• Tugann GET /api/v1/me (gan chead) an spás oibre lena mbaineann an comhartha, a phlean, agus ainm agus ceadanna an chomhartha féin. Is é an bealach is simplí é le seiceáil go n-oibríonn comhartha.
• Liostaíonn GET /api/v1/documents (cead documents:read) na doiciméid, na cinn is nuaí ar dtús. Caolaigh é le reference (an tagairt DOC-… chruinn), status nó template_id; glacann limit le suas le 100, 25 de réir réamhshocraithe.
• Liostaíonn GET /api/v1/cases (cead cases:read) na cásanna is nuaí, más mian leat iad siúd le status amháin, leis an limit céanna. Tá created_at ag gach cás anois freisin.
• Liostaíonn GET /api/v1/case-types (cead cases:read) na cineálacha cáis ar féidir cás a oscailt uathu.
• Ní choinníonn GET /api/v1/templates?name=… ach na teimpléid a bhfuil an téacs ina n-ainm, gan aird ar chás na litreacha.

Níl leathanú ann d'aon ghnó: is chun na míreanna is déanaí a aimsiú atá na liostaí seo, ní chun spás oibre iomlán a easpórtáil.

Cén plean

Is cuid den phlean Team iad an API agus na crúcaí gréasáin. Ar aon phlean eile fanann na comharthaí agus na seoltaí a chruthaigh tú cheana le feiceáil agus is féidir iad a chúlghairm, ach ní eisítear cinn nua, agus ní fhreastalaítear a thuilleadh ar ghlaonna a dhéantar le comhartha. Cuir na pleananna i gcomparáid ar an leathanach praghsála.