Mallit, roolit ja kentät

Malli on uudelleenkäytettävä sopimus. Sillä on nimi, yksi luonnos ja mikä tahansa määrä julkaistuja versioita. Kirjekuoret luodaan aina julkaistusta versiosta, jota ei voi muuttaa: mallin muokkaaminen tarkoittaa uuden luonnoksen tallentamista ja sen julkaisemista seuraavana versiona. Jo lähetetyt kirjekuoret säilyttävät lukitsemansa version.

{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

Tunnukset ovat etuliitteellisiä merkkijonoja (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); aikaleimat ovat RFC 3339 -muotoisia UTC-ajassa.

Kaksi tapaa laatia malli

Peittotila (source: "pdf") lähtee ladatusta asiakirjasta. Kentät ovat suorakulmioita, jotka sijoitetaan sen sivuille PDF-pisteinä (1/72 tuumaa), origo sivun vasemmassa yläkulmassa ja sivuindeksi alkaen 0:sta. Ladattu .docx muunnetaan PDF:ksi kerran (LibreOffice säilyttää Wordin asettelun; fontit, joita tiedostoon ei ole upotettu, voidaan korvata), ja siitä eteenpäin se on PDF siinä missä muutkin: tiedosto ilmoittaa convertedFrom: "docx". Peittotilan versioissa voi olla myös sisältömuokkauksia (paikallaan muokattua tekstiä, peittoa, tekstiruutuja, kuvia, sivutoimintoja), jotka otetaan käyttöön, kun versio julkaistaan.

Asiakirjatila (source: "document") tallentaa itse sopimuksen muotoiltuna tekstinä (ProseMirror JSON), jossa on muuttujasiruja, kuten {{client.name}}, tekstinsisäisiä kenttälohkoja, ehdollisia osioita (säilytetään vain, kun showIf-lauseke on tosi) sekä toistuvia osioita ja taulukon rivejä (yksi taulukkomuuttujan kutakin alkiota kohden). Jokainen kirjekuori renderöi oman PDF:nsä, ja kenttien sijainnit luetaan siitä renderöinnistä. Hallintapaneelissa asiakirjatila on ”Aloita tyhjästä asiakirjasta”. API:n kautta Word-tiedoston voi myös tuoda asiakirjatilaan kutsulla POST /v1/templates/{id}/import: {{tags}} muuttuvat muuttujiksi tai kentiksi, ja allekirjoitusrivit (”Signature: ____”, ”By: ____”, ”Date: ____”) muuttuvat kenttälohkoiksi.

Hallintapaneelissa

Uusi malli tarjoaa kaksi aloitustapaa:

Lataa asiakirja: yksi pudotusalue enintään 25 Mt:n .pdf- ja .docx-tiedostoille. Word-tiedostot muunnetaan PDF:ksi ja avataan editorissa muistutuksella tarkistaa muunnettu asettelu ennen kenttien sijoittamista. Pienet korjaukset tehdään suoraan PDF:ään (”Muokkaa sisältöä”); laajempaa uudelleenkirjoitusta varten muuta Word-tiedostoa ja lataa se uudelleen.
Aloita tyhjästä asiakirjasta: kirjoita sopimus asiakirjatilassa.

Sisältömuokkaukset

Editorin Muokkaa sisältöä -tila muuttaa sitä, mitä allekirjoittajat näkevät, koskematta ladattuun tiedostoon. Sen oletustyökalu, Muokkaa tekstiä, korostaa sivun tekstilohkot (PDF:n tekstikerroksesta ryhmitellyt rivit ja kappaleet); napsauta lohkoa tai siirry siihen sarkaimella ja paina Enter muokataksesi sitä paikallaan samassa sijainnissa, koossa, värissä, tasauksessa ja fontissa. Ctrl/Cmd+Enter tallentaa, Esc peruuttaa, ja jokaisen muokkauksen voi palauttaa muokkausluettelosta. Muokkaukset voi kumota kuten minkä tahansa muun muutoksen. Muut työkalut lisäävät peittoa, tekstiruutuja ja kuvia sekä lisäävät, poistavat, järjestävät uudelleen tai kiertävät sivuja.

Paikallaan tehty tekstimuokkaus tallennetaan kahtena kohteena, joilla on yhteinen group: peitto alkuperäisen lohkon päällä (sivun taustavärissä) ja tekstikohde, joka asetellaan lohkoon lohkon rivinkorkeudella ja ensimmäisellä perusviivalla:

[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face valitsee fontin: PDF:n upotetun fontin, kun se pystyy piirtämään uuden tekstin kaikki merkit, muuten mukana toimitetun metrisesti yhteensopivan fontin (sans Arimo Helvetican/Arialin tilalle, serif Tinos Timesin tilalle, mono Cousine Courierin tilalle, carlito Carlito Calibrin tilalle) vastaavalla painolla ja tyylillä. Teksti rivittyy lohkon sisällä; kun se tarvitsee enemmän rivejä kuin alkuperäinen, muokkaus laajenee sen alla olevaan vapaaseen tilaan, ja editori kieltäytyy tallentamasta sitä, jos tilaa ei ole (”teksti ei mahdu – lyhennä sitä tai lisää tilaa”). Editori ja API jakavat asettelu- ja fonttikoodin, joten julkaistu PDF vastaa esikatselua rivi riviltä.

Muokkaukset voivat muuttaa vain luonnosta. Julkaisu soveltaa ne uuteen perus-PDF:ään, jonka SHA-256 on version documentHash (sen tiiviste, mitä allekirjoittajat näkevät); ladattu alkuperäinen säilytetään version sourceFile-tiedostona, ja seuraava luonnos alkaa siitä samoilla muokkauksilla. Peitto peittää sisällön visuaalisesti; alkuperäinen teksti jää tiedostoon sen alle, joten se ei ole turvallinen tietojen poisto.

Roolit

Roolit ovat sopimuksen osapuolet. Kirjekuoren vastaanottajat yhdistetään rooleihin key-arvon perusteella.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }

Ominaisuus	Merkitys
`key`	Pienaakkosinen tunniste (`^[a-z][a-z0-9_]*$`), jota kentät ja kirjekuoren vastaanottajat käyttävät
`kind`	`signer` (on oltava allekirjoitus- tai nimikirjainkenttä), `approver`, `form_filler` tai `cc` (vastaanottaa, ei koskaan allekirjoita)
`order`	Reititysjärjestys alkaen 1:stä. Saman järjestyksen roolit allekirjoittavat rinnakkain; seuraava järjestys alkaa, kun ne ovat valmiita
`verification`	Miten roolin vastaanottaja todistaa henkilöllisyytensä: `none` (oletus: pelkkä yksilöllinen allekirjoituslinkki) tai `email_otp` (linkki sekä sähköpostitse lähetetty koodi). Vastaanottaja voi ohittaa sen; katso allekirjoittajan vahvistus

passkey, id_check ja sms_otp esiintyvät skeemassa, mutta ne eivät ole vielä käytettävissä allekirjoitukseen: mallia, joka käyttää menetelmää passkey tai id_check, ei voi julkaista, eikä SMS-koodeja vielä toimiteta.

Kentät

{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

Kenttätyypit: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp ja variable_text (lähettäjä täyttää muuttujasta, ei allekirjoittaja). Kentillä voi olla myös:

variable: JSON Pointer muuttujiin (/client/name) kentän sitomiseksi tai esitäyttämiseksi;
options kentille radio ja dropdown;
validation: pattern, min, max, maxLength tai format (email, phone, date, number, currency);
showIf: ehto muuttujien ja muiden kenttien perusteella, esimerkiksi plan != "free";
formula: laskettu, vain luku -arvo;
overflow: mitä tehdään, kun arvo ei mahdu ruutuun: shrink (oletus), wrap tai reject.

Muuttujat

Version variables on JSON Schema (draft 2020-12) datalle, jonka lähetät jokaisen kirjekuoren mukana; version sampleVariables on esimerkki. POST /v1/envelopes validoi variables-arvosi sitä vasten ja raportoi jokaisen ongelman JSON Pointerilla:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

Nähdäksesi tuloksen ennen lähettämistä renderöi vesileimattu esikatselu mistä tahansa versiosta kutsulla POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) tai luo kirjekuori parametrilla ?dry_run=true.

Mallin rakentaminen API:lla

Useimmat tiimit suunnittelevat mallit hallintapaneelin editorissa. Kaikki, mitä se tekee, on käytettävissä API:n kautta:

POST /v1/templates rungolla { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files, jonka runkona on PDF (tai .docx) (Content-Type: application/pdf) tai multipart-kenttä file. Enintään 25 Mt. Vastauksessa on tiedoston tunnus (tfl_…), sivumäärä ja sivukoot.
PUT /v1/templates/{id}/draft kentillä roles, fields, variables (ja file tai source: "document" yhdessä content-kentän kanssa). Luonnokset tallennetaan sellaisinaan; mitään ei vielä tarkisteta.
POST /v1/templates/{id}/publish. Julkaisu tarkistaa luonnoksen: jokaisen kentän rooli on olemassa, jokaisella allekirjoittajaroolilla on allekirjoituskenttä, kentät mahtuvat sivuilleen, valinta- ja pudotusvalikkokentillä on vaihtoehdot, lausekkeet jäsentyvät. Ongelmat palautetaan 422-vastauksena osoittimilla, kuten /fields/3/rect.

curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

Versiopäätepisteet hyväksyvät numeron, arvon latest tai draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (perus-PDF). Mallin, jota mikään kirjekuori tai allekirjoituslinkki ei ole koskaan käyttänyt, voi poistaa; muuten DELETE vastaa 409 in-use.