Szablony, role i pola

Szablon to umowa wielokrotnego użytku. Ma nazwę, jedną wersję roboczą i dowolną liczbę opublikowanych wersji. Koperty są zawsze tworzone z opublikowanej wersji, która jest niezmienna: edycja szablonu oznacza zapisanie nowej wersji roboczej i opublikowanie jej jako kolejnej wersji. Wysłane już koperty zachowują przypiętą wersję.

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

Identyfikatory to ciągi znaków z prefiksem (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); znaczniki czasu są w formacie RFC 3339 w strefie UTC.

Dwa sposoby tworzenia

Tryb Overlay (source: "pdf") zaczyna od przesłanego dokumentu. Pola to prostokąty umieszczone na jego stronach w punktach PDF (1/72 cala), z początkiem układu w lewym górnym rogu strony i indeksem strony liczonym od 0. Przesłany plik .docx jest jednorazowo konwertowany do PDF (przez LibreOffice, z zachowaniem układu z Worda; czcionki, których plik nie osadza, mogą zostać zastąpione), a od tej chwili jest zwykłym plikiem PDF: plik zgłasza convertedFrom: "docx". Wersje w trybie Overlay mogą też zawierać edycje treści (tekst edytowany w miejscu, zamalowania, pola tekstowe, obrazy, operacje na stronach), które są stosowane przy publikacji wersji.

Tryb Document (source: "document") przechowuje samą umowę jako tekst sformatowany (ProseMirror JSON) z elementami zmiennych, takimi jak {{client.name}}, blokami pól w tekście, sekcjami warunkowymi (zachowywanymi tylko wtedy, gdy wyrażenie showIf jest prawdziwe) oraz powtarzalnymi sekcjami i wierszami tabel (po jednym na każdy element zmiennej tablicowej). Każda koperta renderuje własny PDF, a pozycje pól są odczytywane z tego renderu. W panelu tryb Document to „Zacznij od pustego dokumentu”. Przez API można też zaimportować plik Word do trybu Document za pomocą POST /v1/templates/{id}/import: {{tags}} stają się zmiennymi lub polami, a linie podpisu („Signature: ____”, „By: ____”, „Date: ____”) stają się blokami pól.

W panelu

Nowy szablon oferuje dwa punkty startowe:

• Prześlij dokument: jedno pole upuszczania dla plików .pdf i .docx do 25 MB. Pliki Word są konwertowane do PDF i otwierane w edytorze z przypomnieniem, aby przed rozmieszczeniem pól sprawdzić skonwertowany układ. Drobne poprawki wprowadza się bezpośrednio w pliku PDF („Edytuj treść”); przy większych zmianach popraw plik Word i prześlij go ponownie.
• Zacznij od pustego dokumentu: napisz umowę w trybie Document.

Edycje treści

Tryb Edytuj treść w edytorze zmienia to, co widzą osoby podpisujące, bez modyfikowania przesłanego pliku. Jego domyślne narzędzie, Edytuj tekst, wyróżnia bloki tekstu na stronie (wiersze i akapity pogrupowane na podstawie warstwy tekstowej PDF); kliknij blok lub przejdź do niego klawiszem Tab i naciśnij Enter, aby edytować go w miejscu, z zachowaniem pozycji, rozmiaru, koloru, wyrównania i czcionki. Ctrl/Cmd+Enter zapisuje, Esc anuluje, a każdą edycję można cofnąć z listy edycji. Edycje można cofać jak każdą inną zmianę. Pozostałe narzędzia dodają zamalowania, pola tekstowe i obrazy oraz wstawiają, usuwają, zmieniają kolejność lub obracają strony.

Edycja tekstu w miejscu jest przechowywana jako dwa elementy o wspólnej wartości group: zamalowanie na oryginalnym bloku (w kolorze tła strony) i element tekstowy rozmieszczony w bloku, z wysokością wiersza i pierwszą linią bazową bloku:

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 wybiera czcionkę: osadzoną czcionkę z PDF, jeśli potrafi narysować każdy znak nowego tekstu, a w przeciwnym razie dołączoną czcionkę o zgodnej metryce (sans Arimo dla Helvetica/Arial, serif Tinos dla Times, mono Cousine dla Courier, carlito Carlito dla Calibri) w odpowiedniej grubości i stylu. Tekst zawija się w obrębie bloku; gdy potrzebuje więcej wierszy niż oryginał, edycja rozszerza się na wolne miejsce pod nim, a edytor odmawia zapisu, gdy go brakuje („tekst się nie mieści – skróć go lub dodaj miejsce”). Edytor i API współdzielą kod układu i czcionek, więc opublikowany PDF zgadza się z podglądem wiersz po wierszu.

Edycje mogą zmieniać tylko wersję roboczą. Publikacja stosuje je do nowego bazowego pliku PDF, którego SHA-256 jest wartością documentHash wersji (skrótem tego, co widzą osoby podpisujące); przesłany oryginał jest zachowywany jako sourceFile wersji, a kolejna wersja robocza zaczyna od niego z tymi samymi edycjami. Zamalowanie zakrywa treść wizualnie; oryginalny tekst pozostaje w pliku pod spodem, więc nie jest to bezpieczna redakcja (usunięcie danych).

Role

Role to strony umowy. Odbiorcy koperty są dopasowywani do ról według key.

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

Właściwość	Znaczenie
key	Identyfikator małymi literami (^[a-z][a-z0-9_]*$) używany przez pola i przez odbiorców koperty
kind	signer (musi mieć pole podpisu lub parafy), approver, form_filler lub cc (otrzymuje, nigdy nie podpisuje)
order	Kolejność kierowania od 1. Role o tej samej kolejności podpisują równolegle; następna pozycja zaczyna, gdy skończą
verification	Jak odbiorca w danej roli potwierdza tożsamość: none (domyślnie: sam unikalny link do podpisu) lub email_otp (link plus kod wysłany e-mailem). Odbiorca może to nadpisać; zobacz weryfikację osoby podpisującej

passkey, id_check i sms_otp występują w schemacie, ale nie są jeszcze dostępne przy podpisywaniu: szablonu, który używa passkey lub id_check, nie można opublikować, a kody SMS nie są jeszcze dostarczane.

Pola

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

Typy pól: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp oraz variable_text (wypełniane ze zmiennej przez nadawcę, a nie przez osobę podpisującą). Pola mogą też mieć:

• variable: JSON Pointer wskazujący zmienną (/client/name), aby powiązać lub wstępnie wypełnić pole;
• options dla radio i dropdown;
• validation: pattern, min, max, maxLength lub format (email, phone, date, number, currency);
• showIf: warunek oparty na zmiennych i innych polach, np. plan != "free";
• formula: obliczana wartość tylko do odczytu;
• overflow: co zrobić, gdy wartość nie mieści się w polu: shrink (domyślnie), wrap lub reject.

Zmienne

variables wersji to JSON Schema (draft 2020-12) opisujący dane wysyłane z każdą kopertą; sampleVariables wersji to przykład. POST /v1/envelopes waliduje Twoje variables względem schematu i zgłasza każdy problem ze wskaźnikiem 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'." }
  ]
}

Aby zobaczyć wynik przed wysłaniem, wyrenderuj podgląd dowolnej wersji ze znakiem wodnym za pomocą POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) lub utwórz kopertę z ?dry_run=true.

Budowanie szablonu przez API

Większość zespołów projektuje szablony w edytorze w panelu. Wszystko, co on robi, jest dostępne przez API:

1. POST /v1/templates z { "name": "Mutual NDA" }.
2. POST /v1/templates/{id}/files z plikiem PDF (lub .docx) jako treścią żądania (Content-Type: application/pdf) albo jako pole multipart file. Do 25 MB. Odpowiedź zawiera identyfikator pliku (tfl_…), liczbę stron i rozmiary stron.
3. PUT /v1/templates/{id}/draft z roles, fields, variables (oraz file lub source: "document" z content). Wersje robocze są zapisywane w takiej postaci, w jakiej je przesłano; na tym etapie nic nie jest sprawdzane.
4. POST /v1/templates/{id}/publish. Publikacja sprawdza wersję roboczą: rola każdego pola istnieje, każda rola osoby podpisującej ma pole podpisu, pola mieszczą się na stronach, pola jednokrotnego wyboru i listy rozwijane mają opcje, wyrażenia dają się sparsować. Problemy wracają jako 422 ze wskaźnikami takimi jak /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

Punkty końcowe wersji akceptują numer, latest lub draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (bazowy PDF). Szablon, który nigdy nie został użyty przez kopertę ani przez link do podpisu, można usunąć; w przeciwnym razie DELETE odpowiada 409 in-use.