Mallar, roller och fält

En mall är ett återanvändbart avtal. Den har ett namn, ett enda utkast och valfritt antal publicerade versioner. Kuvert skapas alltid från en publicerad version, som inte kan ändras: att redigera en mall innebär att spara ett nytt utkast och publicera det som nästa version. Kuvert som redan har skickats behåller den version 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:n är strängar med prefix (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); tidsstämplar anges enligt RFC 3339 i UTC.

Två sätt att skapa

Överlagringsläge (source: "pdf") utgår från ett uppladdat dokument. Fälten är rektanglar som placeras på dess sidor i PDF-punkter (1/72 tum), med origo i sidans övre vänstra hörn och sidindex från 0. En uppladdad .docx konverteras till PDF en gång (LibreOffice, med Word-layouten bevarad; teckensnitt som filen inte bäddar in kan ersättas), och därefter är den en PDF som alla andra: filen rapporterar convertedFrom: "docx". Versioner i överlagringsläge kan också innehålla innehållsredigeringar (text som redigerats på plats, överskylning, textrutor, bilder, sidåtgärder) som tillämpas när versionen publiceras.

Dokumentläge (source: "document") lagrar själva avtalet som formaterad text (ProseMirror JSON) med variabelchips som {{client.name}}, infogade fältblock, villkorade avsnitt (behålls bara när ett showIf-uttryck är sant) och upprepade avsnitt och tabellrader (en per element i en arrayvariabel). Varje kuvert renderar sin egen PDF, och fältens positioner läses från den renderingen. I instrumentpanelen heter dokumentläget ”Börja från ett tomt dokument”. Via API:et kan en Word-fil också importeras till dokumentläge med POST /v1/templates/{id}/import: {{tags}} blir variabler eller fält, och signaturrader (”Signature: ____”, ”By: ____”, ”Date: ____”) blir fältblock.

I instrumentpanelen

Ny mall erbjuder två sätt att börja:

Ladda upp dokument: en släppzon för .pdf- och .docx-filer på upp till 25 MB. Word-filer konverteras till PDF och öppnas i designern med en påminnelse om att kontrollera den konverterade layouten innan du placerar fält. Små korrigeringar görs direkt i PDF:en (”Redigera innehåll”); för en större omarbetning ändrar du Word-filen och laddar upp den igen.
Börja från ett tomt dokument: skriv avtalet i dokumentläge.

Innehållsredigeringar

Designerns läge Redigera innehåll ändrar vad undertecknarna ser utan att röra den uppladdade filen. Dess standardverktyg, Redigera text, markerar sidans textblock (rader och stycken som grupperats från PDF:ens textlager); klicka på ett, eller tabba dit och tryck på Retur, för att redigera det på plats med samma position, storlek, färg, justering och teckensnitt. Ctrl/Cmd+Retur sparar, Esc avbryter, och varje redigering kan återställas från listan över redigeringar. Redigeringar kan ångras som alla andra ändringar. De övriga verktygen lägger till överskylning, textrutor och bilder och infogar, tar bort, ordnar om eller roterar sidor.

En textredigering på plats lagras som två objekt som delar en group: en överskylning över det ursprungliga blocket (i sidans bakgrundsfärg) och ett textobjekt som layoutas i blocket, med blockets radhöjd och första baslinje:

[
  { "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 väljer teckensnittet: PDF:ens inbäddade teckensnitt när det kan rita varje tecken i den nya texten, annars ett medföljande metriskt kompatibelt teckensnitt (sans Arimo för Helvetica/Arial, serif Tinos för Times, mono Cousine för Courier, carlito Carlito för Calibri) med matchande vikt och stil. Texten radbryts inom blocket; när den behöver fler rader än originalet växer redigeringen ned i ledigt utrymme under blocket, och designern vägrar spara den när det inte finns något (”texten får inte plats – korta den eller lägg till utrymme”). Designern och API:et delar layout- och teckensnittskoden, så den publicerade PDF:en stämmer med förhandsgranskningen rad för rad.

Redigeringar kan bara ändra ett utkast. Publiceringen tillämpar dem på en ny bas-PDF vars SHA-256 är versionens documentHash (hashen av det undertecknarna ser); det uppladdade originalet behålls som versionens sourceFile, och nästa utkast utgår från det med samma redigeringar. Överskylning döljer innehåll visuellt; den ursprungliga texten finns kvar i filen under, så det är ingen säker maskering.

Roller

Roller är avtalets parter. Ett kuverts mottagare matchas mot roller via key.

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

Egenskap	Betydelse
`key`	Identifierare med gemener (`^[a-z][a-z0-9_]*$`) som används av fält och av kuvertets mottagare
`kind`	`signer` (måste ha ett signatur- eller initialfält), `approver`, `form_filler` eller `cc` (tar emot, signerar aldrig)
`order`	Dirigeringsordning från 1. Roller med samma ordning signerar parallellt; nästa ordning startar när de är klara
`verification`	Hur rollens mottagare bevisar vem hen är: `none` (standard: enbart den unika signeringslänken) eller `email_otp` (länken plus en kod via e-post). En mottagare kan åsidosätta det; se verifiering av undertecknare

passkey, id_check och sms_otp finns i schemat men är inte tillgängliga för signering än: en mall som använder passkey eller id_check kan inte publiceras, och sms-koder levereras inte än.

Fält

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

Fälttyper: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp och variable_text (fylls i från en variabel av avsändaren, inte av en undertecknare). Fält kan också ha:

variable: en JSON Pointer in i variablerna (/client/name) för att binda eller förifylla fältet;
options för radio och dropdown;
validation: pattern, min, max, maxLength eller ett format (email, phone, date, number, currency);
showIf: ett villkor över variabler och andra fält, till exempel plan != "free";
formula: ett beräknat, skrivskyddat värde;
overflow: vad som händer när ett värde inte får plats i rutan: shrink (standard), wrap eller reject.

Variabler

En versions variables är ett JSON Schema (draft 2020-12) för de data du skickar med varje kuvert; versionens sampleVariables är ett exempel. POST /v1/envelopes validerar dina variables mot det och rapporterar varje 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'." }
  ]
}

Om du vill se resultatet innan du skickar kan du rendera en vattenmärkt förhandsgranskning av valfri version med POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF), eller skapa kuvertet med ?dry_run=true.

Bygga en mall med API:et

De flesta team utformar mallar i instrumentpanelens designer. Allt den gör finns också via API:et:

POST /v1/templates med { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files med PDF:en (eller .docx) som brödtext (Content-Type: application/pdf) eller som multipart-fältet file. Upp till 25 MB. Svaret innehåller filens id (tfl_…), antal sidor och sidstorlekar.
PUT /v1/templates/{id}/draft med roles, fields, variables (och file, eller source: "document" med content). Utkast sparas som de är; ingenting kontrolleras än.
POST /v1/templates/{id}/publish. Publiceringen lintar utkastet: varje fälts roll finns, varje undertecknarroll har ett signaturfält, fälten får plats på sina sidor, radio- och listrutefält har alternativ, uttrycken kan tolkas. Problem returneras som 422 med pekare 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

Versionsslutpunkterna accepterar ett nummer, latest eller draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (bas-PDF:en). En mall som aldrig har använts av ett kuvert eller en signeringslänk kan tas bort; annars svarar DELETE med 409 in-use.