Gå til indhold
bona fidedocs

Skabeloner, roller og felter

En skabelon er en genanvendelig kontrakt. Den har et navn, én kladde og et vilkårligt antal udgivne versioner. Kuverter oprettes altid fra en udgivet version, som ikke kan ændres: at redigere en skabelon betyder at gemme en ny kladde og udgive den som næste version. Kuverter, der allerede er sendt, beholder den version, de har fastlåst.

GET /v1/templates/tpl_…
{
  "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 strenge med præfiks (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); tidsstempler er RFC 3339 i UTC.

To måder at oprette på

Sektion kaldt “To måder at oprette på”

Overlejringstilstand (source: "pdf") tager udgangspunkt i et uploadet dokument. Felterne er rektangler, der placeres på dets sider i PDF-punkter (1/72 tomme), med origo i sidens øverste venstre hjørne og sideindeks fra 0. En uploadet .docx konverteres til PDF én gang (LibreOffice, med Word-layoutet bevaret; skrifttyper, som filen ikke indlejrer, kan blive erstattet), og derefter er den en PDF som alle andre: filen rapporterer convertedFrom: "docx". Versioner i overlejringstilstand kan også indeholde indholdsredigeringer (tekst redigeret på stedet, overdækning, tekstfelter, billeder, sidehandlinger), som anvendes, når versionen udgives.

Dokumenttilstand (source: "document") gemmer selve kontrakten som formateret tekst (ProseMirror JSON) med variabelchips som {{client.name}}, indsatte feltblokke, betingede afsnit (bevares kun, når et showIf-udtryk er sandt) og gentagne afsnit og tabelrækker (én pr. element i en arrayvariabel). Hver kuvert renderer sin egen PDF, og feltpositionerne aflæses fra den rendering. I dashboardet hedder dokumenttilstand ”Start fra et tomt dokument”. Via API’et kan en Word-fil også importeres til dokumenttilstand med POST /v1/templates/{id}/import: {{tags}} bliver til variabler eller felter, og underskriftslinjer (”Signature: ____”, ”By: ____”, ”Date: ____”) bliver til feltblokke.

I dashboardet

Sektion kaldt “I dashboardet”

Ny skabelon giver to måder at starte på:

  • Upload dokument: én dropzone til .pdf- og .docx-filer på op til 25 MB. Word-filer konverteres til PDF og åbnes i designeren med en påmindelse om at tjekke det konverterede layout, før du placerer felter. Små rettelser foretages direkte i PDF’en (”Rediger indhold”); ved en større omskrivning ændrer du Word-filen og uploader den igen.
  • Start fra et tomt dokument: skriv kontrakten i dokumenttilstand.

Indholdsredigeringer

Sektion kaldt “Indholdsredigeringer”

Designerens tilstand Rediger indhold ændrer, hvad underskriverne ser, uden at røre den uploadede fil. Dens standardværktøj, Rediger tekst, fremhæver sidens tekstblokke (linjer og afsnit grupperet ud fra PDF’ens tekstlag); klik på en, eller gå til den med Tab og tryk på Enter, for at redigere den på stedet med samme position, størrelse, farve, justering og skrifttype. Ctrl/Cmd+Enter gemmer, Esc annullerer, og hver redigering kan tilbageføres fra listen over redigeringer. Redigeringer kan fortrydes som alle andre ændringer. De øvrige værktøjer tilføjer overdækning, tekstfelter og billeder og indsætter, sletter, omarrangerer eller roterer sider.

En tekstredigering på stedet gemmes som to elementer, der deler en group: en overdækning over den oprindelige blok (i sidens baggrundsfarve) og et tekstelement, der sættes op i blokken med blokkens linjehøjde og første grundlinje:

edits.items (excerpt)
[
  { "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ælger skrifttypen: PDF’ens indlejrede skrifttype, når den kan tegne alle tegn i den nye tekst, ellers en medfølgende metrisk kompatibel skrifttype (sans Arimo til Helvetica/Arial, serif Tinos til Times, mono Cousine til Courier, carlito Carlito til Calibri) i den tilsvarende vægt og stil. Teksten ombrydes inden for blokken; når den kræver flere linjer end originalen, vokser redigeringen ned i ledig plads under den, og designeren nægter at gemme den, når der ikke er nogen (”teksten kan ikke være der – forkort den, eller tilføj plads”). Designeren og API’et deler layout- og skrifttypekoden, så den udgivne PDF svarer til forhåndsvisningen linje for linje.

Redigeringer kan kun ændre en kladde. Udgivelsen anvender dem på en ny basis-PDF, hvis SHA-256 er versionens documentHash (hashen af det, underskriverne ser); den uploadede original bevares som versionens sourceFile, og den næste kladde starter fra den med de samme redigeringer. Overdækning skjuler indhold visuelt; den oprindelige tekst ligger stadig i filen nedenunder, så det er ikke en sikker sløring.

Roller

Sektion kaldt “Roller”

Roller er kontraktens parter. En kuverts modtagere matches med roller via key.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }
Egenskab Betydning
key Identifikator med små bogstaver (^[a-z][a-z0-9_]*$), som bruges af felter og af kuvertens modtagere
kind signer (skal have et signatur- eller initialfelt), approver, form_filler eller cc (modtager, underskriver aldrig)
order Rækkefølge fra 1. Roller med samme rækkefølge underskriver parallelt; den næste starter, når de er færdige
verification Hvordan rollens modtager beviser, hvem vedkommende er: none (standard: kun det unikke underskriftslink) eller email_otp (linket plus en kode pr. e-mail). En modtager kan tilsidesætte det; se verificering af underskrivere

passkey, id_check og sms_otp findes i skemaet, men er endnu ikke tilgængelige til underskrift: en skabelon, der bruger passkey eller id_check, kan ikke udgives, og sms-koder leveres endnu ikke.

Felter

Sektion kaldt “Felter”
{
  "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 (udfyldes fra en variabel af afsenderen, ikke af en underskriver). Felter kan også have:

  • variable: en JSON Pointer ind i variablerne (/client/name) til at binde eller forudfylde feltet;
  • options til radio og dropdown;
  • validation: pattern, min, max, maxLength eller et format (email, phone, date, number, currency);
  • showIf: en betingelse over variabler og andre felter, f.eks. plan != "free";
  • formula: en beregnet, skrivebeskyttet værdi;
  • overflow: hvad der sker, når en værdi ikke kan være i feltet: shrink (standard), wrap eller reject.

Variabler

Sektion kaldt “Variabler”

En versions variables er et JSON Schema (draft 2020-12) for de data, du sender med hver kuvert; versionens sampleVariables er et eksempel. POST /v1/envelopes validerer dine variables mod 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'." }
  ]
}

Hvis du vil se resultatet, før du sender, kan du rendere en forhåndsvisning med vandmærke af en vilkårlig version med POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) eller oprette kuverten med ?dry_run=true.

Opbygning af en skabelon med API’et

Sektion kaldt “Opbygning af en skabelon med API’et”

De fleste teams designer skabeloner i dashboardets designer. Alt, hvad den kan, er også tilgængeligt via API’et:

  1. POST /v1/templates med { "name": "Mutual NDA" }.
  2. POST /v1/templates/{id}/files med PDF’en (eller .docx) som body (Content-Type: application/pdf) eller som multipart-feltet file. Op til 25 MB. Svaret indeholder filens id (tfl_…), antal sider og sidestørrelser.
  3. PUT /v1/templates/{id}/draft med roles, fields, variables (og file, eller source: "document" med content). Kladder gemmes, som de er; intet tjekkes endnu.
  4. POST /v1/templates/{id}/publish. Udgivelsen linter kladden: hvert felts rolle findes, hver underskriverrolle har et signaturfelt, felterne passer til deres sider, radio- og rullelistefelter har valgmuligheder, udtrykkene kan fortolkes. Problemer returneres som 422 med pointere som /fields/3/rect.
Terminal window
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

Versionsslutpunkterne accepterer et nummer, latest eller draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (basis-PDF’en). En skabelon, der aldrig er brugt af en kuvert eller et underskriftslink, kan slettes; ellers svarer DELETE med 409 in-use.