Bỏ qua để đến nội dung
bona fidedocs

Bắt đầu nhanh

Hướng dẫn này đưa một mẫu đã xuất bản đến một tệp PDF đã ký và niêm phong. Hướng dẫn dùng khóa thử nghiệm, nên không có gì bị tính phí và mọi tài liệu đều có hình mờ TEST.

  1. Tạo khóa API

    Phần tiêu đề “Tạo khóa API”

    Khóa API được tạo trong bảng điều khiển, tại Settings › API keys. Chọn Test cho hướng dẫn này: khóa bắt đầu bằng bf_test_. Khóa đầy đủ chỉ hiển thị một lần; hãy lưu nó dưới dạng biến môi trường.

    Terminal window
    export BONA_FIDE_API_KEY=bf_test_…

    Mọi yêu cầu đều gửi khóa dưới dạng Authorization: Bearer … (hoặc x-api-key: …). Xem Xác thực.

  2. Tìm mẫu của bạn

    Phần tiêu đề “Tìm mẫu của bạn”

    Mẫu được thiết kế trong bảng điều khiển (tải lên tài liệu PDF hoặc Word rồi đặt các trường, hoặc soạn ở chế độ Document) và sau đó được xuất bản. Liệt kê các mẫu để lấy id:

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

    GET /v1/templates/{id}/versions/latest trả về roles, fields của phiên bản và JSON Schema của variables. Trang của mẫu trong bảng điều khiển cũng có bảng Use in API với một yêu cầu dựng sẵn cho đúng phiên bản đó.

  3. Tạo phong bì

    Phần tiêu đề “Tạo phong bì”

    POST /v1/envelopes kết xuất mẫu với các biến của bạn, cố định phiên bản và bắt đầu chuyển tiếp. Cung cấp một người nhận cho mỗi vai trò (vai trò CC là tùy chọn). Gửi kèm Idempotency-Key để một lần thử lại không thể gửi hai lần.

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

    Phản hồi là 201 Created kèm phong bì:

    {
      "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 quyết định cách liên hệ với người nhận: email (mặc định) gửi email liên kết ký cho từng người nhận khi đến lượt họ; embedded và none không gửi email nào, và bạn tự mở các phiên ký (bước tiếp theo).

  4. Để người nhận ký

    Phần tiêu đề “Để người nhận ký”

    Tạo một phiên ký cho người nhận từ backend của bạn. Phiên có thời hạn ngắn (ttlSeconds, từ 60 đến 3600, mặc định 600) và chỉ dùng được một lần.

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

    Chuyển token được trả về (bfs_…) cho trang của bạn và kết xuất web component:

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

    Bản bao cho React và Vue, sự kiện và mô hình bảo mật: Ký nhúng.

    Với phương thức xác minh mặc định email_otp, người ký xác nhận một mã gồm sáu chữ số được gửi đến email của họ trước khi gửi. Ở chế độ thử nghiệm, email chỉ được gửi đến thành viên trong tổ chức của bạn, vì vậy hãy dùng địa chỉ của chính bạn khi thử nghiệm.

  5. Nhận thông báo khi hoàn tất

    Phần tiêu đề “Nhận thông báo khi hoàn tất”

    Đăng ký một endpoint webhook tại Settings › Webhooks (hoặc bằng POST /v1/webhook-endpoints) và giữ lại secret whsec_…. Khi người nhận cuối cùng ký, bạn nhận được envelope.completed, với mọi biến và giá trị đã nhập trong data.values. Tệp PDF đã niêm phong đến sau cùng 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);
    });

    Tải xuống tệp PDF đã niêm phong (tài liệu kèm chứng nhận hoàn tất, có dấu thời gian):

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

    Danh sách sự kiện đầy đủ, cơ chế thử lại và xác minh thủ công: Webhook.

Chuyển sang chạy thật

Phần tiêu đề “Chuyển sang chạy thật”

Thay khóa thử nghiệm bằng khóa bf_live_. Phong bì ở chế độ trực tiếp không có hình mờ, email được gửi đến mọi người nhận, và các phong bì đã hoàn tất được tính vào gói của bạn (Gói và giới hạn). Mọi thứ một khóa tạo ra đều mang chế độ của khóa đó, danh sách của khóa chỉ hiển thị chế độ đó, và phong bì thử nghiệm chỉ thông báo đến các endpoint webhook ở chế độ thử nghiệm, vì vậy hãy đăng ký thêm một endpoint ở chế độ trực tiếp.