Шаблоны, роли и поля

Шаблон — это договор для многократного использования. У него есть название, один черновик и любое число опубликованных версий. Конверты всегда создаются из опубликованной версии, а она неизменяема: чтобы отредактировать шаблон, нужно сохранить новый черновик и опубликовать его как следующую версию. Уже отправленные конверты сохраняют закреплённую за ними версию.

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

Идентификаторы — строки с префиксом (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); метки времени указываются в формате RFC 3339 в UTC.

Два способа создания

Режим Overlay (source: "pdf") начинается с загруженного документа. Поля — это прямоугольники, размещённые на его страницах в пунктах PDF (1/72 дюйма), начало координат — в левом верхнем углу страницы, нумерация страниц — с 0. Загруженный файл .docx один раз конвертируется в PDF (через LibreOffice с сохранением вёрстки Word; шрифты, не встроенные в файл, могут быть заменены), и дальше это обычный PDF: файл сообщает convertedFrom: "docx". Версии в режиме Overlay также могут содержать правки содержимого (текст, отредактированный на месте, закрашивание, текстовые блоки, изображения, операции со страницами), которые применяются при публикации версии.

Режим Document (source: "document") хранит сам договор в виде форматированного текста (ProseMirror JSON) с метками переменных, например {{client.name}}, встроенными блоками полей, условными разделами (остаются, только если выражение showIf истинно) и повторяющимися разделами и строками таблиц (по одному на каждый элемент переменной-массива). Каждый конверт формирует собственный PDF, а позиции полей считываются из этого результата. В панели управления режим Document называется «Начать с пустого документа». Через API файл Word также можно импортировать в режим Document с помощью POST /v1/templates/{id}/import: {{tags}} становятся переменными или полями, а строки для подписи («Signature: ____», «By: ____», «Date: ____») — блоками полей.

В панели управления

Новый шаблон предлагает два варианта начала:

Загрузить документ: одна область для перетаскивания файлов .pdf и .docx размером до 25 МБ. Файлы Word конвертируются в PDF и открываются в редакторе с напоминанием проверить сконвертированную вёрстку, прежде чем расставлять поля. Небольшие исправления вносятся прямо в PDF («Редактировать содержимое»); для серьёзной переработки измените файл Word и загрузите его заново.
Начать с пустого документа: напишите договор в режиме Document.

Правки содержимого

Режим Редактировать содержимое в редакторе меняет то, что видят подписанты, не затрагивая загруженный файл. Его инструмент по умолчанию, Редактировать текст, подсвечивает текстовые блоки страницы (строки и абзацы, сгруппированные по текстовому слою PDF); щёлкните блок или перейдите к нему клавишей Tab и нажмите Enter, чтобы отредактировать его на месте с тем же положением, размером, цветом, выравниванием и шрифтом. Ctrl/Cmd+Enter сохраняет, Esc отменяет, а любую правку можно откатить из списка правок. Правки отменяются так же, как любые другие изменения. Остальные инструменты добавляют закрашивание, текстовые блоки и изображения, а также вставляют, удаляют, переупорядочивают или поворачивают страницы.

Правка текста на месте хранится как два элемента с общим group: закрашивание поверх исходного блока (цветом фона страницы) и текстовый элемент, размещённый в блоке, с межстрочным интервалом и первой базовой линией блока:

[
  { "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 выбирает шрифт: встроенный шрифт PDF, если он может отобразить каждый символ нового текста, иначе входящий в комплект шрифт с совместимыми метриками (sans Arimo для Helvetica/Arial, serif Tinos для Times, mono Cousine для Courier, carlito Carlito для Calibri) соответствующей насыщенности и начертания. Текст переносится в пределах блока; если ему нужно больше строк, чем в оригинале, правка расширяется на свободное место под ним, а если места нет, редактор отказывается её сохранить («текст не помещается — сократите его или освободите место»). Редактор и API используют общий код вёрстки и шрифтов, поэтому опубликованный PDF совпадает с предпросмотром строка в строку.

Правки можно вносить только в черновик. При публикации они применяются к новому базовому PDF, SHA-256 которого становится documentHash версии (хешем того, что видят подписанты); загруженный оригинал сохраняется как sourceFile версии, а следующий черновик начинается с него с теми же правками. Закрашивание скрывает содержимое только визуально; исходный текст остаётся в файле под ним, поэтому это не надёжное удаление конфиденциальных данных.

Роли

Роли — это стороны договора. Получатели конверта сопоставляются с ролями по key.

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

Свойство	Значение
`key`	Идентификатор в нижнем регистре (`^[a-z][a-z0-9_]*$`), который используют поля и получатели конверта
`kind`	`signer` (должно быть поле подписи или инициалов), `approver`, `form_filler` или `cc` (получает копию, никогда не подписывает)
`order`	Порядок маршрутизации начиная с 1. Роли с одинаковым порядком подписывают параллельно; следующий номер начинает, когда они закончат
`verification`	Как получатель роли подтверждает свою личность: `none` (по умолчанию: только уникальная ссылка для подписания) или `email_otp` (ссылка плюс код, отправленный по почте). Получатель может переопределить это; см. проверку подписанта

passkey, id_check и sms_otp есть в схеме, но для подписания пока недоступны: шаблон, который использует passkey или id_check, нельзя опубликовать, а SMS-коды пока не доставляются.

Поля

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

Типы полей: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp и variable_text (заполняется из переменной отправителем, а не подписантом). У полей также могут быть:

variable: JSON Pointer на переменную (/client/name), чтобы привязать или предзаполнить поле;
options для radio и dropdown;
validation: pattern, min, max, maxLength или format (email, phone, date, number, currency);
showIf: условие по переменным и другим полям, например plan != "free";
formula: вычисляемое значение только для чтения;
overflow: что делать, если значение не помещается в поле: shrink (по умолчанию), wrap или reject.

Переменные

variables версии — это JSON Schema (draft 2020-12) для данных, которые вы отправляете с каждым конвертом; sampleVariables версии — пример. POST /v1/envelopes проверяет ваши variables по этой схеме и сообщает о каждой проблеме с указателем 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'." }
  ]
}

Чтобы увидеть результат до отправки, сформируйте предпросмотр любой версии с водяным знаком через POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) или создайте конверт с ?dry_run=true.

Создание шаблона через API

Большинство команд создают шаблоны в редакторе панели управления. Всё, что он делает, доступно через API:

POST /v1/templates с { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files с PDF (или .docx) в теле запроса (Content-Type: application/pdf) либо в поле multipart file. До 25 МБ. Ответ содержит идентификатор файла (tfl_…), число страниц и их размеры.
PUT /v1/templates/{id}/draft с roles, fields, variables (и file либо source: "document" с content). Черновики сохраняются как есть; на этом этапе ничего не проверяется.
POST /v1/templates/{id}/publish. При публикации черновик проверяется: роль каждого поля существует, у каждой роли подписанта есть поле подписи, поля помещаются на страницах, у переключателей и раскрывающихся списков есть варианты, выражения разбираются. Проблемы возвращаются как 422 с указателями вида /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

Конечные точки версий принимают номер, latest или draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (базовый PDF). Шаблон, который ни разу не использовался конвертом или ссылкой для подписания, можно удалить; в противном случае DELETE отвечает 409 in-use.