Сессии и ссылки для подписания

Получатели подписывают на странице подписания Bona Fide: либо на размещённой у нас странице https://sign.bonafidesign.com/s/…, либо на той же странице, встроенной в ваш продукт с помощью <bf-signing>. Учётная запись получателям не нужна. Доступ им даёт сессия подписания.

Сессии подписания

При доставке по почте сессии создаются автоматически (ссылка в письме). Для встроенного подписания или подписания со ссылками, которые вы доставляете сами, создайте сессию на своём бэкенде:

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

Поле	Примечания
`recipient`	Получатель конверта, который ещё может подписать (не CC, ещё не завершил)
`mode`	`embedded` (по умолчанию) или `hosted`. `url` для страницы на нашей стороне имеют вид `…/s/<token>` — на них можно перенаправить или отправить их самостоятельно
`allowedOrigins`	До 10 источников (origin), которым разрешено встраивать страницу во фрейм
`returnUrl`	Куда размещённая у нас страница отправляет подписанта после завершения
`ttlSeconds`	От 60 до 3600, по умолчанию 600

Сессии одноразовые: как только получатель отправляет подпись, сессия считается израсходованной, а использованная или просроченная сессия отвечает 410 Gone. Создавайте новую сессию при каждом отображении страницы. Сессии можно создавать, только пока конверт находится в статусе sent, а аннулирование конверта завершает их все.

Что проходит подписант

Страница подписания (и любой собственный интерфейс на том же API) выполняет следующие шаги:

Обмен: POST /v1/signing/exchange { "token": "bfs_…" } возвращает короткоживущий токен доступа (bfa_…), который хранится в памяти. Cookie не используются, поэтому блокировка сторонних cookie в iframe не мешает.
Загрузка: GET /v1/signing/session возвращает представление для подписанта (название конверта, отправитель, роль и поля получателя, предзаполненные значения, уведомление для потребителя) и при первом обращении записывает recipient.viewed. GET /v1/signing/document — PDF для отображения.
Проверка (только с email_otp): POST /v1/signing/otp отправляет по почте шестизначный код (действует 10 минут), а POST /v1/signing/otp/verify проверяет его. Неверный код возвращает verified: false с числом оставшихся попыток. verification.verified в представлении сразу равно true, если способу проверки получателя код не нужен.
Отправка: POST /v1/signing/submit со values полей (подписи нарисованные, напечатанные или загруженные), согласием с уведомлением и viewedDocumentHash — SHA-256 именно того PDF, который был показан. Если документ с тех пор изменился, отправка отклоняется (409).
Или отказ: POST /v1/signing/decline { "reason": "…" } завершает конверт (envelope.declined).

Очередь получателя наступает, только когда все предыдущие группы маршрутизации завершили работу; до этого в представлении canSign: false, а отправка возвращает 409 not-your-turn.

Проверка подписанта

У каждого получателя есть способ проверки verification: способ его роли (задаётся на панели ролей в редакторе шаблонов), если конверт не переопределяет его для конкретного получателя (на экране отправки или через recipients[].verification).

Способ	Что делает подписант	Когда использовать
`none` (по умолчанию)	Открывает уникальную ссылку для подписания и подписывает	Ссылка приходит ему по почте: она есть только у того, у кого есть доступ к этому почтовому ящику
`email_otp`	Открывает ссылку, затем вводит шестизначный код, отправленный на тот же адрес	Нужно второе, свежее подтверждение в момент подписания (договоры с крупными суммами, общие почтовые ящики)
`integrator_asserted`	Подписывает в вашем продукте, который удостоверяет его личность (`externalUserId`)	Встроенное подписание за вашей собственной системой входа

none используется по умолчанию, потому что ссылка, которую отправляет Bona Fide, уникальна для получателя и не поддаётся угадыванию: её открытие подтверждает контроль над адресом электронной почты, а именно на такую атрибуцию опираются законы об электронной подписи (ESIGN / UETA в США, простые электронные подписи по eIDAS). Аналогичные продукты тоже используют этот вариант по умолчанию. Шаблоны, опубликованные с email_otp, сохраняют его, а явно указанный email_otp продолжает работать везде.

Два сценария никогда не полагаются только на ссылку:

Постоянные ссылки для подписания (/l/…): посетитель сам вводит свой адрес, поэтому он всегда подтверждает код из письма, прежде чем будет создан конверт, независимо от настроек шаблона.
Сессии, которые создаёте вы (POST /v1/envelopes/{id}/sessions), вообще не содержат подтверждения адреса электронной почты: это задача вашей системы входа, поэтому используйте для них integrator_asserted (с externalUserId) или email_otp.

Сертификат о завершении фиксирует для каждого подписанта, что фактически использовалось:

Записывается как	Когда
Ссылка по почте (уникальная ссылка, отправленная на адрес)	`none`, подписано по ссылке из письма
Ссылка по почте + одноразовый код (отправлен на адрес)	`email_otp`, подписано по ссылке из письма
Ссылка для подписания + одноразовый код (отправлен на адрес)	Посетитель постоянной ссылки
Одноразовый код (отправлен на адрес)	`email_otp` в сессии, созданной вами
Сессия подписания, выданная отправителем	`none` в сессии, созданной вами
Подтверждение интегратора	`integrator_asserted`

Публичная сводка проверки показывает те же метки без адреса.

Языки

Страница подписания, её письма (запрос, напоминания, коды, завершение, аннулирование), страница постоянной ссылки и страница статуса для наблюдателя доступны на 50 языках. Подписант видит их в следующем порядке приоритета:

язык, выбранный в языковом меню страницы (запоминается на этом устройстве);
<bf-signing locale="…"> (встроенное подписание) или ?locale= в ссылке на нашу страницу;
locale получателя, заданный при создании конверта (recipients[].locale или locale у конверта для всех, у кого нет своего);
язык его браузера.

Письмам язык нужен ещё до того, как кто-либо откроет страницу, поэтому они используют locale получателя, а без него отправляются на английском. Постоянные ссылки отправляют письмо с кодом на том языке, на котором отображается страница посетителя.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

Близкие теги принимаются и сохраняются как язык, которому они соответствуют (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); всё остальное — ошибка валидации. В переведённых уведомлениях о согласии указано, что действует английский текст, и подписант может переключиться на него; язык, на котором было прочитано уведомление, записывается вместе с подписью (consentLocale в событии аудита recipient.signed).

Код	Язык	Самоназвание
`ar`	Арабский	العربية	справа налево
`hy`	Армянский	Հայերեն
`bn`	Бенгальский	বাংলা
`bg`	Болгарский	Български
`zh-Hans`	Китайский (упрощённый)	简体中文
`zh-Hant`	Китайский (традиционный)	繁體中文
`hr`	Хорватский	Hrvatski
`cs`	Чешский	Čeština
`da`	Датский	Dansk
`nl`	Нидерландский	Nederlands
`en-GB`	Английский (Великобритания)	English (UK)
`en-US`	Английский (США)	English (US)
`et`	Эстонский	Eesti
`fil`	Филиппинский	Filipino
`fi`	Финский	Suomi
`fr`	Французский	Français
`fr-CA`	Французский (Канада)	Français (Canada)
`de`	Немецкий	Deutsch
`el`	Греческий	Ελληνικά
`he`	Иврит	עברית	справа налево
`hi`	Хинди	हिन्दी
`hu`	Венгерский	Magyar
`id`	Индонезийский	Bahasa Indonesia
`it`	Итальянский	Italiano
`ja`	Японский	日本語
`ko`	Корейский	한국어
`lv`	Латышский	Latviešu
`lt`	Литовский	Lietuvių
`ms`	Малайский	Bahasa Melayu
`mr`	Маратхи	मराठी
`nb`	Норвежский	Norsk bokmål
`fa`	Персидский (фарси)	فارسی	справа налево
`pl`	Польский	Polski
`pt-BR`	Португальский (Бразилия)	Português (Brasil)
`pt-PT`	Португальский (Португалия)	Português (Portugal)
`ro`	Румынский	Română
`ru`	Русский	Русский
`sr-Latn`	Сербский (латиница)	Srpski
`sk`	Словацкий	Slovenčina
`sl`	Словенский	Slovenščina
`es-419`	Испанский (Латинская Америка)	Español (Latinoamérica)
`es-ES`	Испанский (Испания)	Español (España)
`sw`	Суахили	Kiswahili
`sv`	Шведский	Svenska
`te`	Телугу	తెలుగు
`th`	Тайский	ไทย
`tr`	Турецкий	Türkçe
`uk`	Украинский	Українська
`ur`	Урду	اردو	справа налево
`vi`	Вьетнамский	Tiếng Việt

Постоянные ссылки для подписания

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

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

visitorRole — роль подписанта, которую получает посетитель. Ссылки поддерживают одного посетителя и не более одного контрподписанта: mode: "auto" ставит контрподпись автоматически печатью платформы Bona Fide, а mode: "person" направляет конверт на указанный email. У любой другой роли, кроме CC, не было бы получателя, поэтому такие шаблоны отклоняются.
Посетитель вводит имя, адрес электронной почты и переменные шаблона, а затем подтверждает код из письма, прежде чем что-либо будет создано (POST /v1/links/{id}/start, затем POST /v1/links/{id}/verify).
limits ограничивает использование на адрес электронной почты в день (по умолчанию 3), на IP-адрес в час (по умолчанию 20), в целом за день и по почтовому домену. При dedupe (включено по умолчанию) адрес, который уже подписал, получает 409 already-signed.
PATCH /v1/signing-links/{id} приостанавливает ссылку (active: false), возобновляет её или переводит на более новую версию; удаление ссылки сохраняет созданные ею конверты. Каждое использование генерирует signing_link.used.