Kirjekuoret ja vastaanottajat

Kirjekuori on yksi sopimus matkalla allekirjoitetuksi: muuttujillasi renderöity malliversio, vastaanottajat, jotka toimivat sen parissa, ja todisteet kaikesta, mitä tapahtuu. Luo kirjekuori kutsulla POST /v1/envelopes.

Kirjekuoren luominen

Kenttä	Tyyppi	Huomautukset
`template`	`tpl_…`	Pakollinen
`version`	luku tai `"latest"`	Oletus `latest`; ratkaistaan ja lukitaan luontihetkellä. Täytyy olla julkaistu
`variables`	objekti	Validoidaan version JSON Schemaa vasten
`recipients`	taulukko	Yksi roolia kohden (`role`, `name`, `email`; valinnaisesti `externalUserId`, `verification`, `fields` esitäyttöön kentän tunnuksen mukaan, `order` allekirjoitusjärjestyksen muuttamiseen)
`subject`, `message`	merkkijono	Käytetään allekirjoitussähköposteissa ja näytetään allekirjoitussivulla
`delivery`	`email` · `embedded` · `none`	Oletus `email`
`expiresAt`	RFC 3339	Täytyy olla tulevaisuudessa; kirjekuori vanhenee silloin, ja allekirjoitus- ja katselijalinkit lakkaavat toimimasta
`cc`	taulukko	Ylimääräiset CC-vastaanottajat (`name`, `email`) mallin CC-roolien lisäksi; enintään 50
`viewers`	taulukko	Henkilöt, jotka seuraavat kirjekuorta allekirjoittamatta (`name`, `email`, valinnaisesti `notifyOnSignature`); määrä kirjekuorta kohden rajoitettu paketin mukaan
`viewerDocumentAccess`	totuusarvo	Anna katselijoiden avata asiakirja tilasivullaan. Oletus `false` (vain tila); Team-paketista alkaen
`reminders`	objekti	`{ "enabled": false }` poistaa muistutukset käytöstä; `{ "enabled": true, "intervalHours": 24 }` muuttaa väliä (1–720)
`externalId`	merkkijono	Oma tunnuksesi, enintään 200 merkkiä
`dedupeOn`	`"external_id"`	Palauta olemassa oleva kirjekuori, jolla on tämä `externalId`, uuden luomisen sijaan
`metadata`	merkkijono-objekti	Enintään 500 merkkiä arvoa kohden; palautetaan kirjekuoressa ja webhookeissa

Jokaisella vastaanottajalla on oltava jokin version rooli; jokaisella muulla kuin CC-roolilla on oltava täsmälleen yksi vastaanottaja. Virheet raportoidaan yhdessä osoittimilla, kuten /recipients/1/role tai /recipients/0/fields/start_date.

Vastaukset: 201 kirjekuoren ja Location-otsakkeen kanssa; 200 olemassa olevan kirjekuoren ja otsakkeen x-deduplicated: true kanssa, kun dedupeOn löysi osuman; 200 kuiva-ajon yhteenvedon kanssa, kun käytetään ?dry_run=true; 402, kun Free-työtila on käyttänyt sisältyvät kirjekuorensa; 403 plan-upgrade-required, kun katselijoita on enemmän kuin paketti sallii tai viewerDocumentAccess ei sisälly pakettiin (Paketit ja rajat). Kuiva-ajot tarkistavat myös paketin rajat.

Jokainen ensimmäisen julkaisun jälkeen lisätty kenttä on valinnainen: pyyntö ilman niitä toimii täsmälleen kuten ennen.

Lähetyshetken asetukset

Malli määrittää, kuka allekirjoittaa missäkin järjestyksessä. Yksittäiselle kirjekuorelle voit muuttaa tätä koskematta malliin:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

Järjestys: recipients[].order on vaihe, jossa vastaanottaja allekirjoittaa; vastaanottajat, joilla on sama numero, allekirjoittavat samaan aikaan. Ilman sitä käytetään mallin roolin order-arvoa. Järjestykset ovat positiivisia kokonaislukuja; CC-rooleille ei voi antaa järjestystä; jokainen rooli tarvitsee silti vastaanottajansa (jotta mallin kentillä säilyy allekirjoittajansa); vähintään yhden vastaanottajan on allekirjoitettava. Tapahtuma envelope.created tallentaa tiedon routingOverridden: true.
CC: ylimääräiset CC-vastaanottajat saavat valmiin asiakirjan sähköpostin eivätkä koskaan allekirjoita. Ne näkyvät recipients-luettelossa arvolla kind: "cc" ja roolilla _cc.
Muistutukset: vuorossa olevalle lähetetään muistutus intervalHours tunnin välein (oletus: asennuksen REMINDER_INTERVAL_HOURS, 72), enintään kolme kertaa; enabled: false ei lähetä yhtään. Muistutukset koskevat email-toimitusta.
Allekirjoittajan todennus on vastaanottajakohtainen: verification ohittaa roolin menetelmän. none (pelkkä yksilöllinen allekirjoituslinkki, oletus rooleille, jotka eivät määritä menetelmää) ja email_otp (linkki sekä sähköpostitse lähetetty koodi) ovat käytettävissä nyt; passkey ja id_check hylätään, koska ne eivät ole vielä käytettävissä. Katso allekirjoittajan vahvistus.
Kieli: locale vastaanottajalla, CC:llä tai katselijalla (tai kirjekuorella kaikille, joilla ei ole omaa) määrittää hänen allekirjoitussivunsa ja sähköpostiensa kielen, joka on jokin 50 allekirjoituskielestä. Ilman sitä allekirjoitussivu seuraa selainta ja sähköpostit ovat englanniksi.

Hallintapaneelin lähetysnäkymässä on samat vaihtoehdot: siirrä vaiheita aiemmaksi tai myöhemmäksi, valitse Allekirjoita samaan aikaan, lisää CC-vastaanottajia ja katselijoita, valitse kunkin allekirjoittajan todennus (Vain sähköpostilinkki tai Sähköpostilinkki + koodi) ja kieli sekä aseta vanhenemispäivä ja muistutusaikataulu.

Toimitus

email: jokaiselle vastaanottajalle lähetetään sähköpostitse linkki isännöidylle allekirjoitussivulle, kun on hänen vuoronsa. Vastaanottajat, jotka eivät ole allekirjoittaneet, saavat muistutuksen muutaman päivän välein (enintään kolme), ja kaikille lähetetään sähköposti, kun kirjekuori valmistuu.
embedded: ei sähköpostia allekirjoittajille. Luo allekirjoitusistunto, kun allekirjoittaja on tuotteessasi. Katselijoille lähetetään silti tilalinkki sähköpostitse.
none: ei lainkaan sähköpostia (ei myöskään katselijoille); käytä tätä, kun toimitat linkit itse (isännöidyt istunnot).

POST /v1/envelopes/{id}/recipients/{recipient}/resend lähettää uuden linkin sähköpostitse vastaanottajalle, jonka vuoro on (enintään kerran minuutissa).

Elinkaari

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

`status`	Merkitys
`rendering`	Valmistellaan
`sent`	Käynnissä: vastaanottajat allekirjoittavat reititysjärjestyksessä
`completed`	Kaikki vastaanottajat ovat valmiita. Sinetöinti alkaa
`declined`	Vastaanottaja kieltäytyi; kirjekuori päättyy
`voided`	Mitätöit sen (`{ "reason": "…" }`); avoimet allekirjoitusistunnot lakkaavat toimimasta
`expired`	`expiresAt` umpeutui ennen valmistumista

seal seuraa sinetöityä PDF:ää: not_started, pending (valmis, sinetöidään), sealed tai failed. Sinetöinti ei koskaan estä valmistumista: kirjekuori valmistuu ensin ja sinetöidään heti sen jälkeen.

Vastaanottajat ja reititys

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

Vastaanottajan status on pending (ei vielä hänen vuoronsa), sent, viewed, completed tai declined, ja kind on roolin signer, approver, form_filler tai cc. Reititys perustuu order-arvoon (roolin tai lähetyshetken ohituksen): kaikki alimman keskeneräisen järjestysnumeron vastaanottajat toimivat rinnakkain, ja seuraava ryhmä aloittaa, kun he ovat valmiita. CC-vastaanottajat eivät koskaan estä reititystä.

Katselijat

Katselija seuraa kirjekuorta allekirjoittamatta: esihenkilö, lakiavustaja, asiakkaan puolen tilivastaava. Katselijat eivät ole vastaanottajia. Heillä ei ole roolia eikä vuoroa, he eivät koskaan estä tai viimeistele mitään, eivätkä he koskaan näy todistuksen allekirjoittajaluettelossa.

Kun kirjekuori lähetetään (tai kun lisäät heidät myöhemmin kutsulla POST /v1/envelopes/{id}/viewers), jokainen katselija saa brändätyn sähköpostin, jossa on linkki vain luku -tilasivulle: kirjekuoren otsikko, lähettäjä, jokainen vaihe vastaanottajien nimineen, rooleineen, tiloineen ja aikaleimoineen, reaaliaikaisesti ihmisten allekirjoittaessa. Vastaanottajien sähköpostiosoitteita ei näytetä.
Katselijoille lähetetään sähköposti uudelleen, kun kirjekuori valmistuu, siitä kieltäydytään tai se mitätöidään, sekä jokaisen allekirjoituksen jälkeen, jos notifyOnSignature on true (oletuksena pois).
Asiakirja on sivulla vain, kun asetat viewerDocumentAccess: true (Team-paketista alkaen): alkuperäinen kesken ollessa, sinetöity PDF sinetöinnin jälkeen. Muuten katselijat näkevät vain tilan.
DELETE /v1/envelopes/{id}/viewers/{viewer} peruuttaa katselijan: jokainen hänelle lähetetty linkki lakkaa toimimasta välittömästi.
Linkit ovat henkilökohtaisia valtuutus-URL-osoitteita. Jokaisesta linkkitunnuksesta tallennetaan vain SHA-256. Linkki toimii, kunnes kirjekuori vanhenee (enintään 90 päivää), 30 päivää kirjekuoren päättymisen jälkeen, eikä enää lainkaan, kun katselija on peruutettu.
Lisääminen, avaaminen (sivun ja asiakirjan ensimmäinen katselu) ja peruuttaminen tallennetaan kirjausketjuun tapahtumina viewer.added, viewer.viewed, viewer.document_viewed ja viewer.revoked, ja siten myös todistukseen.

Yksittäisen kirjekuoren vastaukset (luonti, haku, mitätöinti) luettelevat heidät:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

Katselijoiden määrä kirjekuorta kohden riippuu paketista (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform rajaton); CC-vastaanottajia ei lasketa. Peruutetut katselijat vapauttavat paikkansa.

Asiakirjat

GET /v1/envelopes/{id}/document?version=… lataa PDF:n, ja sen SHA-256 on otsakkeessa x-document-sha256:

`version`	Tiedosto
`original` (oletus)	Renderöity asiakirja sellaisena kuin se lähetettiin allekirjoitettavaksi
`sealed`	Lopullinen PDF: arvot litistetty, valmistumistodistus liitetty, asiakirja-aikaleima. Tapahtuman `envelope.sealed` jälkeen
`certificate`	Pelkkä valmistumistodistus

Kirjekuoren documentHash on alkuperäisen asiakirjan SHA-256 ja sealedDocumentHash sinetöidyn tiedoston SHA-256; niitä tarkistus hakee.

Kirjausketju

Jokainen toiminto on tapahtuma kirjekuorikohtaisessa tiivisteketjussa: hash = SHA-256(prevHash ‖ canonical JSON of the event), jossa ensimmäinen prevHash on 64 nollaa. GET /v1/envelopes/{id}/events palauttaa tapahtumat ja tarkistaa ketjun:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Webhookien tapahtumatyyppien lisäksi ketjussa on vain kirjausketjuun kuuluvia merkintöjä, kuten session.created, recipient.verified, recipient.reminded ja katselijoiden tapahtumat (toimijatyyppi viewer, kun katselija avaa sivunsa).

Reaaliaikaista tilaa varten käyttöliittymässä GET /v1/envelopes/{id}/events/stream on server-sent events -virta: kunkin kehyksen tapahtumanimi on tapahtuman type ja tunnus on seq; yhdistä uudelleen otsakkeella Last-Event-ID jatkaaksesi.

Luettelointi

GET /v1/envelopes suodattaa arvoilla status, seal, template ja q (vapaa teksti vastaanottajien nimistä ja sähköpostiosoitteista, externalId-arvosta ja kirjekuoren tunnuksesta). Kuten kaikki luettelot, se sivutetaan kursorilla:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Lähetä nextCursor takaisin parametrina cursor; limit on 1–100 (oletus 20).