Перейти к содержимому
bona fidedocs

Быстрый старт

В этом руководстве вы пройдёте путь от опубликованного шаблона до подписанного и запечатанного PDF. Используется тестовый ключ, поэтому ничего не тарифицируется, а на каждом документе стоит водяной знак TEST.

  1. Создайте ключ API

    Заголовок раздела «Создайте ключ API»

    Ключи API создаются в панели управления, в разделе Настройки › Ключи API. Для этого руководства выберите Test: ключ начинается с bf_test_. Полный ключ показывается только один раз; сохраните его в переменной окружения.

    Окно терминала
    export BONA_FIDE_API_KEY=bf_test_…

    Каждый запрос передаёт его как Authorization: Bearer … (или x-api-key: …). См. Аутентификация.

  2. Найдите свой шаблон

    Заголовок раздела «Найдите свой шаблон»

    Шаблоны создаются в панели управления (загрузите документ PDF или Word и расставьте поля либо напишите его в режиме Document), а затем публикуются. Получите их список, чтобы узнать идентификатор:

    Окно терминала
    curl https://api.bonafidesign.com/v1/templates \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY"

    GET /v1/templates/{id}/versions/latest возвращает roles и fields версии, а также JSON Schema её variables. На странице шаблона в панели управления также есть блок Использовать в API с готовым запросом именно для этой версии.

  3. Создайте конверт

    Заголовок раздела «Создайте конверт»

    POST /v1/envelopes формирует документ из шаблона с вашими переменными, закрепляет версию и запускает маршрутизацию. Укажите по одному получателю на каждую роль (роли CC необязательны). Передайте Idempotency-Key, чтобы повторный запрос не отправил конверт дважды.

    Окно терминала
    curl https://api.bonafidesign.com/v1/envelopes \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: onboarding-8841" \
      -d '{
        "template": "tpl_…",
        "version": "latest",
        "variables": {
          "client": { "name": "Acme Robotics, Inc." },
          "effective_date": "2026-10-13"
        },
        "recipients": [
          { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev" }
        ],
        "delivery": "embedded",
        "externalId": "user_8841",
        "dedupeOn": "external_id"
      }'

    Ответ — 201 Created с конвертом:

    {
      "id": "env_8Gm2kQ4rT1",
      "organization": "org_…",
      "template": "tpl_…",
      "templateVersion": 3,
      "status": "sent",
      "seal": "not_started",
      "testMode": true,
      "recipients": [
        {
          "id": "rcp_5Jw0pLs9Xe",
          "role": "client",
          "name": "Jane Doe",
          "email": "jane@acme.dev",
          "order": 1,
          "status": "sent",
          "verification": "email_otp",
          "completedAt": null
        }
      ],
      "documentHash": "9f2c…",
      "sealedDocumentHash": null,
      "externalId": "user_8841",
      "metadata": {},
      "createdAt": "2026-10-13T13:58:04.512Z",
      "completedAt": null
    }

    delivery определяет, как вы связываетесь с получателями: email (по умолчанию) отправляет каждому получателю ссылку для подписания, когда наступает его очередь; embedded и none не отправляют писем, а сессии подписания вы открываете сами (следующий шаг).

  4. Дайте получателю подписать

    Заголовок раздела «Дайте получателю подписать»

    Создайте для получателя сессию подписания на своём бэкенде. Сессии короткоживущие (ttlSeconds, от 60 до 3600, по умолчанию 600) и одноразовые.

    Окно терминала
    curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "recipient": "rcp_5Jw0pLs9Xe",
        "mode": "embedded",
        "allowedOrigins": ["https://app.example.com"]
      }'

    Передайте возвращённый token (bfs_…) на свою страницу и отобразите веб-компонент:

    <script type="module" src="https://js.bonafidesign.com/v1"></script>
    

    <bf-signing session="bfs_…"></bf-signing>
    <script>
      document.querySelector('bf-signing')
        .addEventListener('completed', (e) => console.log('signed', e.detail.envelope));
    </script>

    Обёртки для React и Vue, события и модель безопасности: Встроенное подписание.

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

  5. Получите уведомление о завершении

    Заголовок раздела «Получите уведомление о завершении»

    Зарегистрируйте конечную точку вебхука в разделе Настройки › Вебхуки (или с помощью POST /v1/webhook-endpoints) и сохраните секрет whsec_…. Когда подписывает последний получатель, вы получаете envelope.completed со всеми переменными и введёнными значениями в data.values. Запечатанный PDF приходит следом вместе с envelope.sealed.

    import express from 'express';
    import { Webhook } from 'standardwebhooks';
    

    const wh = new Webhook(process.env.BONA_FIDE_WEBHOOK_SECRET!);
    const app = express();
    

    app.post('/hooks/bona-fide', express.raw({ type: 'application/json' }), async (req, res) => {
      const event = wh.verify(req.body, req.headers as Record<string, string>) as { type: string; data: any };
      if (event.type === 'envelope.completed') await saveValues(event.data.envelope.id, event.data.values);
      if (event.type === 'envelope.sealed') await fetchSealedPdf(event.data.envelope.id);
      res.sendStatus(204);
    });

    Скачайте запечатанный PDF (документ с сертификатом о завершении и меткой времени):

    Окно терминала
    curl -o signed.pdf "https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/document?version=sealed" \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY"

    Полный список событий, повторы и ручная проверка: Вебхуки.

Переход в рабочий режим

Заголовок раздела «Переход в рабочий режим»

Замените тестовый ключ на ключ bf_live_. Рабочие конверты не содержат водяного знака, письма уходят любому получателю, а завершённые конверты учитываются в вашем тарифе (Тарифы и лимиты). Всё, что создаёт ключ, получает его режим, его списки показывают только этот режим, а тестовые конверты уведомляют только конечные точки вебхуков в тестовом режиме, поэтому зарегистрируйте и рабочую конечную точку.