Sjablonen, rollen & velden

Een sjabloon is een herbruikbaar contract. Het heeft een naam, één concept en een willekeurig aantal gepubliceerde versies. Enveloppen worden altijd aangemaakt uit een gepubliceerde versie, die onveranderlijk is: een sjabloon bewerken betekent een nieuw concept opslaan en dat publiceren als de volgende versie. Enveloppen die al zijn verstuurd, houden de versie die ze hebben vastgelegd.

{
  "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’s zijn strings met een prefix (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); tijdstempels zijn RFC 3339 in UTC.

Twee manieren om te maken

Overlaymodus (source: "pdf") begint bij een geüpload document. Velden zijn rechthoeken die op de pagina’s worden geplaatst in pdf-punten (1/72 inch), met de oorsprong linksboven op de pagina en paginanummering vanaf 0. Een geüpload .docx-bestand wordt één keer naar pdf geconverteerd (met LibreOffice, met behoud van de Word-opmaak; lettertypen die het bestand niet insluit, kunnen worden vervangen), en is daarna een pdf als elke andere: het bestand meldt convertedFrom: "docx". Versies in Overlaymodus kunnen ook inhoudsbewerkingen bevatten (tekst ter plekke bewerkt, white-out, tekstvakken, afbeeldingen, paginabewerkingen) die worden toegepast wanneer de versie wordt gepubliceerd.

Documentmodus (source: "document") slaat het contract zelf op als opgemaakte tekst (ProseMirror JSON) met variabelechips zoals {{client.name}}, inline veldblokken, voorwaardelijke secties (alleen behouden als een showIf-expressie waar is) en herhalende secties en tabelrijen (één per item van een arrayvariabele). Elke envelop rendert een eigen pdf, en de posities van velden worden uit die render gelezen. In het dashboard heet Documentmodus “Beginnen met een leeg document”. Via de API kan een Word-bestand ook in Documentmodus worden geïmporteerd met POST /v1/templates/{id}/import: {{tags}} worden variabelen of velden, en handtekeningregels (“Signature: ____”, “By: ____”, “Date: ____”) worden veldblokken.

In het dashboard

Nieuw sjabloon biedt twee beginpunten:

Document uploaden: één dropzone voor .pdf- en .docx-bestanden tot 25 MB. Word-bestanden worden naar pdf geconverteerd en openen in de designer met een herinnering om de geconverteerde opmaak te controleren voordat u velden plaatst. Kleine correcties maakt u direct in de pdf (“Inhoud bewerken”); voor een grotere herschrijving past u het Word-bestand aan en uploadt u het opnieuw.
Beginnen met een leeg document: schrijf het contract in Documentmodus.

Inhoudsbewerkingen

De modus Inhoud bewerken van de designer wijzigt wat ondertekenaars zien zonder het geüploade bestand aan te raken. Het standaardgereedschap, Tekst bewerken, markeert de tekstblokken van de pagina (regels en alinea’s, gegroepeerd op basis van de tekstlaag van de pdf); klik op een blok, of ga er met Tab naartoe en druk op Enter, om het ter plekke te bewerken in dezelfde positie, grootte, kleur, uitlijning en hetzelfde lettertype. Ctrl/Cmd+Enter slaat op, Esc annuleert en elke bewerking kan worden teruggedraaid vanuit de lijst met bewerkingen. Bewerkingen kunnen ongedaan worden gemaakt zoals elke andere wijziging. Met de andere gereedschappen voegt u white-out, tekstvakken en afbeeldingen toe, en voegt u pagina’s in, verwijdert, herschikt of draait u ze.

Een tekstbewerking ter plekke wordt opgeslagen als twee items met dezelfde group: een white-out over het oorspronkelijke blok (in de achtergrondkleur van de pagina) en een tekstitem dat in het blok wordt opgemaakt, met de regelhoogte en eerste basislijn van het blok:

[
  { "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 kiest het lettertype: het ingesloten lettertype van de pdf als dat elk teken van de nieuwe tekst kan weergeven, anders een meegeleverd lettertype met compatibele metrics (sans Arimo voor Helvetica/Arial, serif Tinos voor Times, mono Cousine voor Courier, carlito Carlito voor Calibri) in het overeenkomende gewicht en de overeenkomende stijl. De tekst loopt door binnen het blok; als er meer regels nodig zijn dan in het origineel, groeit de bewerking in de vrije ruimte eronder, en de designer weigert op te slaan als die er niet is (“tekst past niet — maak hem korter of voeg ruimte toe”). De designer en de API delen de code voor opmaak en lettertypen, dus de gepubliceerde pdf komt regel voor regel overeen met de preview.

Bewerkingen kunnen alleen een concept wijzigen. Bij publicatie worden ze toegepast op een nieuwe basis-pdf waarvan de SHA-256 de documentHash van de versie is (de hash van wat ondertekenaars zien); het geüploade origineel wordt bewaard als de sourceFile van de versie, en het volgende concept begint daarbij met dezelfde bewerkingen. White-out bedekt inhoud alleen visueel; de oorspronkelijke tekst blijft eronder in het bestand staan, dus het is geen veilige redactie.

Rollen

Rollen zijn de partijen bij het contract. Ontvangers van een envelop worden op key aan rollen gekoppeld.

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

Eigenschap	Betekenis
`key`	Identifier in kleine letters (`^[a-z][a-z0-9_]*$`) die velden en ontvangers van de envelop gebruiken
`kind`	`signer` (moet een handtekening- of parafeerveld hebben), `approver`, `form_filler` of `cc` (ontvangt, ondertekent nooit)
`order`	Routeringsvolgorde vanaf 1. Rollen met dezelfde volgorde ondertekenen parallel; de volgende volgorde begint wanneer zij klaar zijn
`verification`	Hoe de ontvanger van de rol aantoont wie die is: `none` (standaard: alleen de unieke ondertekeningslink) of `email_otp` (de link plus een code per e-mail). Een ontvanger kan dit overschrijven; zie verificatie van de ondertekenaar

passkey, id_check en sms_otp staan in het schema maar zijn nog niet beschikbaar voor ondertekening: een sjabloon dat passkey of id_check gebruikt, kan niet worden gepubliceerd, en sms-codes worden nog niet bezorgd.

Velden

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

Veldtypen: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp en variable_text (door de afzender ingevuld vanuit een variabele, niet door een ondertekenaar). Velden kunnen ook het volgende hebben:

variable: een JSON Pointer in de variabelen (/client/name) om het veld te koppelen of vooraf in te vullen;
options voor radio en dropdown;
validation: pattern, min, max, maxLength of een format (email, phone, date, number, currency);
showIf: een voorwaarde over variabelen en andere velden, zoals plan != "free";
formula: een berekende, alleen-lezen waarde;
overflow: wat er gebeurt als een waarde niet in het vak past: shrink (standaard), wrap of reject.

Variabelen

De variables van een versie zijn een JSON Schema (draft 2020-12) voor de data die u met elke envelop meestuurt; de sampleVariables van de versie zijn een voorbeeld. POST /v1/envelopes valideert uw variables daartegen en meldt elk probleem met een 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'." }
  ]
}

Wilt u het resultaat zien voordat u verstuurt, render dan een preview met watermerk van een willekeurige versie met POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → pdf), of maak de envelop aan met ?dry_run=true.

Een sjabloon bouwen met de API

De meeste teams ontwerpen sjablonen in de designer van het dashboard. Alles wat die doet, is ook via de API beschikbaar:

POST /v1/templates met { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files met de pdf (of .docx) als body (Content-Type: application/pdf) of als multipartveld file. Maximaal 25 MB. Het antwoord bevat het bestands-id (tfl_…), het aantal pagina’s en de paginaformaten.
PUT /v1/templates/{id}/draft met roles, fields, variables (en file, of source: "document" met content). Concepten worden opgeslagen zoals ze zijn; er wordt nog niets gecontroleerd.
POST /v1/templates/{id}/publish. Bij publicatie wordt het concept gecontroleerd: de rol van elk veld bestaat, elke ondertekenaarsrol heeft een handtekeningveld, velden passen op hun pagina’s, radio- en dropdownvelden hebben opties, expressies zijn te parsen. Problemen komen terug als een 422 met pointers zoals /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

Versie-endpoints accepteren een getal, latest of draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (de basis-pdf). Een sjabloon dat nooit door een envelop of een ondertekeningslink is gebruikt, kan worden verwijderd; anders antwoordt DELETE met 409 in-use.