跳至內容
bona fidedocs

快速入門

本教學會帶您從一個已發布的範本，一路走到簽署完成並已封存的 PDF。教學使用測試金鑰，因此不會產生任何費用，每份文件都會加上 TEST 浮水印。

  1. 建立 API 金鑰

    標題為「建立 API 金鑰」的章節

    API 金鑰在主控台的 設定 › API 金鑰 中建立。本教學請選擇測試：這類金鑰以 bf_test_ 開頭。完整金鑰只會顯示一次，請將它儲存為環境變數。

    Terminal window
    export BONA_FIDE_API_KEY=bf_test_…

    每個要求都會以 Authorization: Bearer …（或 x-api-key: …）的形式傳送金鑰。請參閱驗證身分。

  2. 找到您的範本

    標題為「找到您的範本」的章節

    範本在主控台中設計（上傳 PDF 或 Word 文件並放置欄位，或在文件模式下撰寫），然後發布。列出範本即可取得其 ID：

    Terminal window
    curl https://api.bonafidesign.com/v1/templates \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY"

    GET /v1/templates/{id}/versions/latest 會傳回該版本的 roles、fields，以及其 variables 的 JSON Schema。主控台的範本頁面還有一個在 API 中使用面板，提供針對該版本的現成要求。

  3. 建立信封

    標題為「建立信封」的章節

    POST /v1/envelopes 會以您的變數轉譯範本、鎖定版本並開始傳送流程。請為每個角色提供一位收件者（副本角色為選用）。請傳送 Idempotency-Key，確保重試不會重複傳送。

    Terminal window
    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），而且只能使用一次。

    Terminal window
    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_…）傳給您的頁面，並轉譯 Web 元件：

    <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 驗證方式下，簽署人必須先確認寄到其電子郵件信箱的 6 位數驗證碼，才能提交。在測試模式下，電子郵件只會寄給您組織的成員，因此測試時請使用您自己的電子郵件地址。

  5. 在完成時收到通知

    標題為「在完成時收到通知」的章節

    在 設定 › Webhook 中（或透過 POST /v1/webhook-endpoints）註冊 Webhook 端點，並妥善保存 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（附有完成證明書並加上時間戳記的文件）：

    Terminal window
    curl -o signed.pdf "https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/document?version=sealed" \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY"

    完整的事件清單、重試機制和手動驗證，請參閱 Webhook。

正式上線

標題為「正式上線」的章節

將測試金鑰換成 bf_live_ 金鑰。正式信封不會加上浮水印，電子郵件會寄給任何收件者，已完成的信封會計入您的方案用量（方案與限制）。金鑰建立的所有內容都沿用該金鑰的模式，清單只會顯示該模式下的內容，而且測試信封只會通知測試模式的 Webhook 端點，因此也請另外註冊一個正式端點。