Tài liệu API v1

Một bộ ký (envelope) = các văn bản + người ký + thứ tự. Vòng đời: sent → (mọi cá nhân xác minh xong, văn bản được chốt và băm SHA-256) signing → completed, hoặc voided.

Tạo bộ ký

POST /api/v1/envelopes
Authorization: Bearer <API key>

{
  "externalRef": "GD-260813-432",          // mã phía bạn — trả lại trong mọi webhook
  "title": "Hồ sơ GD-260813-432",
  "meta": { "display": { "subtitle": "M2.19.06 · Masteri Waterfront" } },
  "recipients": [
    { "role": "buyer",  "label": "Bên Mua", "kind": "person", "name": "Hồ Ngọc Mai", "order": 1,
      "verify": { "cccdQr": true, "allowManual": true, "matchName": true },
      "fields": [ { "key": "phone", "label": "Số điện thoại nhận OTP", "required": true, "type": "tel" },
                  { "key": "address", "label": "Địa chỉ liên hệ", "required": true },
                  { "key": "bankAcc", "label": "Số tài khoản", "required": true, "type": "number" },
                  { "key": "bankName", "label": "Ngân hàng", "required": true } ] },
    { "role": "seller", "label": "Bên Bán", "kind": "person", "name": "Chu Văn Kiên", "order": 1, "fields": [ ... ] },
    { "role": "onehub", "label": "OneHub",  "kind": "org",    "name": "OneHub", "order": 2 }
  ],
  "documents": [   // ký theo đúng thứ tự mảng; html có thể chứa trường trộn {{vai.trường}}
    { "key": "hddv", "name": "Hợp đồng dịch vụ", "signers": ["buyer","seller","onehub"],
      "html": "<div>… Số CCCD {{buyer.cccd}} cấp ngày {{buyer.issued}} bởi {{buyer.issuedBy}} …</div>" }
  ]
}
→ 201 { id, status: "sent", recipients: [{ id, role, status, signUrl }], documents: [...] }

Các lệnh khác

GET/api/v1/envelopes?externalRef=…

Liệt kê bộ ký theo mã phía bạn

GET/api/v1/envelopes/:id

Trạng thái, người ký (kèm signUrl), văn bản + mã băm

GET/api/v1/envelopes/:id/events

Nhật ký đầy đủ (mở link, xác minh, gửi OTP, ký) kèm IP

POST/api/v1/envelopes/:id/void

{ reason } — huỷ bộ chưa hoàn tất; sửa nội dung = huỷ + gửi bộ mới

POST/api/v1/envelopes/:id/recipients/:rid/sign

{ signerName } — tổ chức (kind "org") ký khi tới lượt

POST/api/v1/envelopes/:id/recipients/:rid/rotate-link

Thu hồi link ký cũ, cấp link mới

Trường trộn

{{vai.trường}} trong html được điền khi chốt văn bản. Trường có sẵn: name; từ QR CCCD: cccd, issued, issuedBy, dob, gender, nameOnCard, address; và mọi fields[].key người ký tự điền (ghi đè giá trị cùng tên, ví dụ address). Ô chưa có dữ liệu hiện "………".

Webhook

Sự kiện: envelope.sent · recipient.viewed · recipient.identified · recipient.verified · envelope.ready · recipient.signed · recipient.declined · envelope.completed · envelope.voided. Gửi lại tự động tối đa 6 lần, giữ đúng thứ tự trong một bộ ký. Trả về 2xx để xác nhận.

POST <webhook_url>
X-OneSign-Event: recipient.signed
X-OneSign-Timestamp: 1793337947789
X-OneSign-Signature: v1=hex(HMAC_SHA256(webhook_secret, timestamp + "." + body))

{ "id": "…", "type": "recipient.signed", "occurredAt": "…",
  "envelope": { id, externalRef, status, documents: [{ id, key, hash }], recipients: [...] },
  "recipient": { id, role, status, identity: { cccd, issued, issuedBy, dob, address, source }, values: { phone, bankAcc, … },
                 signature: { at, method, ip, docs: [{ id, hash }] } } }