Maler, roller og felt

En mal er en gjenbrukbar kontrakt. Den har et navn, ett enkelt utkast og et hvilket som helst antall publiserte versjoner. Konvolutter opprettes alltid fra en publisert versjon, og den kan ikke endres: å redigere en mal betyr å lagre et nytt utkast og publisere det som neste versjon. Konvolutter som allerede er sendt, beholder versjonen de låste.

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

ID-er er strenger med prefiks (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); tidsstempler er RFC 3339 i UTC.

To måter å lage en mal på

Overleggsmodus (source: "pdf") tar utgangspunkt i et opplastet dokument. Felt er rektangler som plasseres på sidene i PDF-punkter (1/72 tomme), med origo øverst til venstre på siden og sideindeks fra 0. En opplastet .docx konverteres til PDF én gang (LibreOffice, med Word-oppsettet bevart; skrifter som ikke er innebygd i filen, kan bli erstattet), og fra da av er den en PDF som alle andre: filen oppgir convertedFrom: "docx". Versjoner i overleggsmodus kan også inneholde innholdsendringer (tekst redigert på stedet, overdekking, tekstbokser, bilder, sideoperasjoner) som tas i bruk når versjonen publiseres.

Dokumentmodus (source: "document") lagrer selve kontrakten som rik tekst (ProseMirror JSON) med variabelbrikker som {{client.name}}, innebygde feltblokker, betingede avsnitt (beholdes bare når et showIf-uttrykk er sant) og gjentakende avsnitt og tabellrader (én per element i en matrisevariabel). Hver konvolutt rendrer sin egen PDF, og feltenes posisjoner leses fra den renderingen. I dashbordet heter dokumentmodus «Start fra et tomt dokument». Via API-et kan en Word-fil også importeres til dokumentmodus med POST /v1/templates/{id}/import: {{tags}} blir variabler eller felt, og signaturlinjer («Signature: ____», «By: ____», «Date: ____») blir feltblokker.

I dashbordet

Ny mal gir to måter å starte på:

Last opp dokument: én slippsone for .pdf- og .docx-filer på opptil 25 MB. Word-filer konverteres til PDF og åpnes i designeren med en påminnelse om å kontrollere det konverterte oppsettet før du plasserer felt. Små rettelser gjøres direkte i PDF-en («Rediger innhold»); for en større omskriving endrer du Word-filen og laster den opp på nytt.
Start fra et tomt dokument: skriv kontrakten i dokumentmodus.

Innholdsendringer

Designerens modus Rediger innhold endrer det signatarene ser, uten å røre den opplastede filen. Standardverktøyet, Rediger tekst, uthever sidens tekstblokker (linjer og avsnitt gruppert fra PDF-ens tekstlag); klikk på en, eller gå til den med Tab og trykk Enter, for å redigere den på stedet med samme posisjon, størrelse, farge, justering og skrift. Ctrl/Cmd+Enter lagrer, Esc avbryter, og hver endring kan tilbakestilles fra endringslisten. Endringer kan angres som alle andre endringer. De andre verktøyene legger til overdekking, tekstbokser og bilder, og setter inn, sletter, endrer rekkefølgen på eller roterer sider.

En tekstendring på stedet lagres som to elementer med samme group: en overdekking over den opprinnelige blokken (i sidens bakgrunnsfarge) og et tekstelement som settes inn i blokken, med blokkens linjehøyde og første grunnlinje:

[
  { "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 velger skriften: PDF-ens innebygde skrift når den kan tegne alle tegnene i den nye teksten, ellers en medfølgende metrisk kompatibel skrift (sans Arimo for Helvetica/Arial, serif Tinos for Times, mono Cousine for Courier, carlito Carlito for Calibri) med tilsvarende vekt og stil. Teksten brytes innenfor blokken; når den trenger flere linjer enn originalen, vokser endringen inn i ledig plass under, og designeren nekter å lagre den når det ikke finnes plass («teksten får ikke plass – forkort den eller lag mer plass»). Designeren og API-et deler koden for oppsett og skrift, så den publiserte PDF-en samsvarer linje for linje med forhåndsvisningen.

Endringer kan bare gjøres i et utkast. Publiseringen tar dem i bruk på en ny grunn-PDF, der SHA-256-verdien er versjonens documentHash (hashen av det signatarene ser); den opplastede originalen beholdes som versjonens sourceFile, og neste utkast starter fra den med de samme endringene. Overdekking skjuler innhold visuelt; den opprinnelige teksten ligger fortsatt i filen under, så det er ikke en sikker sladding.

Roller

Roller er partene i kontrakten. Mottakerne av en konvolutt knyttes til roller via key.

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

Egenskap	Betydning
`key`	Identifikator med små bokstaver (`^[a-z][a-z0-9_]*$`) som brukes av felt og av konvoluttens mottakere
`kind`	`signer` (må ha et signatur- eller initialfelt), `approver`, `form_filler` eller `cc` (mottar, signerer aldri)
`order`	Rutingrekkefølge fra 1. Roller med samme rekkefølge signerer parallelt; neste rekkefølge starter når de er ferdige
`verification`	Hvordan rollens mottaker beviser hvem de er: `none` (standard: bare den unike signeringslenken) eller `email_otp` (lenken pluss en kode på e-post). En mottaker kan overstyre den; se verifisering av signatarer

passkey, id_check og sms_otp finnes i skjemaet, men er ikke tilgjengelige for signering ennå: en mal som bruker passkey eller id_check, kan ikke publiseres, og SMS-koder leveres ikke ennå.

Felt

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

Felttyper: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp og variable_text (fylles ut fra en variabel av avsenderen, ikke av en signatar). Felt kan også ha:

variable: en JSON Pointer inn i variablene (/client/name) for å binde eller forhåndsutfylle feltet;
options for radio og dropdown;
validation: pattern, min, max, maxLength eller et format (email, phone, date, number, currency);
showIf: en betingelse over variabler og andre felt, for eksempel plan != "free";
formula: en beregnet, skrivebeskyttet verdi;
overflow: hva som skjer når en verdi ikke får plass i boksen: shrink (standard), wrap eller reject.

Variabler

En versjons variables er et JSON Schema (draft 2020-12) for dataene du sender med hver konvolutt; versjonens sampleVariables er et eksempel. POST /v1/envelopes validerer variables mot det og rapporterer hvert problem med en JSON Pointer:

{
  "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'." }
  ]
}

For å se resultatet før du sender, kan du rendre en forhåndsvisning med vannmerke av en hvilken som helst versjon med POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF), eller opprette konvolutten med ?dry_run=true.

Bygge en mal med API-et

De fleste team utformer maler i dashbordets designer. Alt den gjør, er tilgjengelig via API-et:

POST /v1/templates med { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files med PDF-en (eller .docx) som brødtekst (Content-Type: application/pdf) eller som multipart-feltet file. Opptil 25 MB. Svaret inneholder fil-ID-en (tfl_…), antall sider og sidestørrelser.
PUT /v1/templates/{id}/draft med roles, fields, variables (og file, eller source: "document" med content). Utkast lagres som de er; ingenting kontrolleres ennå.
POST /v1/templates/{id}/publish. Publiseringen kontrollerer utkastet: rollen til hvert felt finnes, hver signatarrolle har et signaturfelt, feltene får plass på sidene sine, radio- og nedtrekksfelt har alternativer, uttrykkene kan tolkes. Problemer returneres som 422 med pekere som /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

Versjonsendepunkter godtar et tall, latest eller draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (grunn-PDF-en). En mal som aldri er brukt av en konvolutt eller en signeringslenke, kan slettes; ellers svarer DELETE med 409 in-use.