API ja webhookit

Mistä sen löytää

Jos toimistosi asiakirjat saavat alkunsa jossain muualla kuin DocuTractissa, kyseinen järjestelmä voi keskustella kanssamme suoraan. Avaa oikean yläkulman valikko, jossa näkyy osoitteesi, ja valitse Integraatiot: siellä luodaan tunnus, jolla järjestelmäsi kutsuu meitä, ja siellä lisätään osoite, johon ilmoitamme valmiista asiakirjoista.

Näkymä alkaa valmiilla CRM-yhteyksillä (CRM-integraatiot); tässä kuvatut tunnukset ja webhookit ovat niiden alla osiossa API ja webhookit.

Tunnus

Paina Luo tunnus, anna sille nimi, jonka tunnistat myöhemmin (jotta tiedät, mikä järjestelmä sitä käyttää), ja valitse, mitä sillä saa tehdä: lukea malleja, luoda asiakirjoja, käsitellä toimeksiantoja.

Itse tunnus näytetään kerran, heti luomisen jälkeen: tallennamme siitä vain tiivisteen, joten emme pysty näyttämään sitä toista kertaa edes itse. Kopioi se suoraan järjestelmäsi asetuksiin.

Luettelossa näkyvät kunkin tunnuksen ensimmäiset merkit, mitä sillä saa tehdä ja milloin sitä on viimeksi käytetty. Mitätöi poistaa tunnuksen käytöstä välittömästi; tieto siitä säilyy, joten näkyy, että se on ollut olemassa ja milloin se lakkasi toimimasta.

Mitä API:lla voi tehdä

Järjestelmäsi voi:

• avata toimeksiannon ja ladata siihen skannauksia;
• luoda asiakirjan mallista valmiiksi täytetyin arvoin;
• kysyä, mihin vaiheeseen asiakirja on edennyt;
• hakea jokaisen arvon yhdessä sen skannauksen kanssa, josta se luettiin;
• saada lyhytikäisen linkin valmiiseen tiedostoon.

Jokaisen osoitteen ja kentän täydellinen kuvaus luodaan suoraan koodista ja julkaistaan avoimesti: API-kuvaus.

Webhookit

Sen sijaan että kysyisit meiltä, onko asiakirja valmis, anna meille osoite, niin me kirjoitamme sinulle. Lisää se kohdassa Webhookit ja valitse tapahtumat: asiakirja valmis, asiakirja epäonnistui, toimeksianto valmis, ristiriita löytyi, asiakas lähetti tiedoston.

Jokainen pyyntö allekirjoitetaan X-DocuTract-Signature-otsakkeella, ja allekirjoituksen varmentava salaisuus näytetään kerran, kuten tunnus. Järjestelmäsi on tarkistettava allekirjoitus ja vastattava 2xx-koodilla. Jos se vastaa jotain muuta tai ei vastaa lainkaan, yritämme uudelleen: minuutin, viiden minuutin, puolen tunnin, kahden tunnin ja kymmenen tunnin kuluttua, ja sitten lopetamme.

Kun jotain ei saapunut

Toimitukset-painike näyttää lokin: minkä tapahtuman lähetimme, milloin, montako kertaa, mikä vastauskoodi tuli takaisin ja vastauksen rungon alku. Se on vastaus väitteeseen ”järjestelmämme ei saanut mitään”: siinä lukee mustaa valkoisella, että se vastasi 500 neljä kertaa kello 14.12.

Lähetä testi lähettää osoitteeseen ping-viestin heti odottamatta oikeaa tapahtumaa, joten vastaanottajan voi määrittää ennen kuin sen kautta kulkee oikeaa työtä. Epäonnistuneen toimituksen vieressä oleva Yritä uudelleen tekee yhden uuden yrityksen välittömästi.

Zapier, Make ja n8n

No-code-alustat (palvelut, joissa integraatio kootaan ohjelmoimatta) tilaavat tapahtumamme itse API:n REST hooks -osan kautta, joten kenenkään ei tarvitse kopioida niiden osoitteita DocuTractiin. Anna alustalle tunnus, jolla on oikeudet webhooks:read ja webhooks:write sekä ne, joita sen toiminnot tarvitsevat (esimerkiksi templates:read ja documents:write).

• POST /api/v1/hooks tiedoilla {"event": "document.ready", "target_url": "https://…"} tilaa osoitteelle yhden tapahtuman. Vastaus sisältää tilauksen id:n ja kerran sen allekirjoitus-secret:n.
• GET /api/v1/hooks luettelee näin luodut tilaukset; DELETE /api/v1/hooks/{id} poistaa yhden.
• GET /api/v1/hooks/events luettelee tapahtumat: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} palauttaa esimerkin sisällöstä, jonka alusta näyttää ”testilaukaisimessaan” ennen kuin yhtään todellista tapahtumaa on ollut.

Tilaus on tavallinen webhook-osoite: se allekirjoitetaan, sitä yritetään uudelleen ja se kirjataan samalla tavalla, ja se näkyy luettelossa Webhookit. Se lakkaa, kun sen luonut tunnus perutaan tai vanhenee tai kun alusta vastaa toimitukseen koodilla 410 Gone.

Tältä näyttää 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"
}

ja tältä 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"
}

Mallin kentät

GET /api/v1/templates/{id}/fields (oikeus templates:read) luettelee, mitä malli tarvitsee: kunkin kentän key (jonka mukaan values annetaan kutsussa POST /api/v1/documents), sen label, mistä se täytetään, ja fillable, joka on false kentälle, jonka DocuTract täyttää itse, kuten päivämäärälle. Zapierin tai Maken lomake rakennetaan tästä luettelosta, joten se vastaa aina mallia sellaisena kuin se on nyt.

Haut

Muutama kutsu on olemassa, jotta järjestelmä tai no-code-alusta löytää tarvitsemansa arvailematta:

• GET /api/v1/me (ei oikeutta) palauttaa työtilan, johon tunnus kuuluu, sen tilauksen sekä tunnuksen oman nimen ja oikeudet. Se on helpoin tapa tarkistaa, että tunnus toimii.
• GET /api/v1/documents (oikeus documents:read) listaa asiakirjat uusimmat ensin. Rajaa parametreilla reference (tarkka DOC-…-viite), status tai template_id; limit on enintään 100, oletuksena 25.
• GET /api/v1/cases (oikeus cases:read) listaa uusimmat toimeksiannot, halutessasi vain yhden status-arvon mukaiset, samalla limit-arvolla. Jokaisella toimeksiannolla on nyt myös created_at.
• GET /api/v1/case-types (oikeus cases:read) listaa toimeksiantotyypit, joista toimeksiannon voi avata.
• GET /api/v1/templates?name=… jättää vain mallit, joiden nimessä teksti esiintyy, kirjainkoosta välittämättä.

Sivutusta ei ole tarkoituksella: listat on tehty uusimpien löytämiseen, ei koko työtilan viemiseen.

Mikä paketti

API ja webhookit kuuluvat Team-pakettiin. Kaikissa muissa paketeissa jo luomasi tunnukset ja osoitteet pysyvät näkyvissä ja ne voi mitätöidä, mutta uusia ei myönnetä, eikä tunnuksella tehtyihin kutsuihin enää vastata. Vertaile paketteja hinnoittelusivulla.