API yêu cầu ký

API envelopes gửi tài liệu để ký từ hệ thống của riêng bạn. Một envelope (phong bì) chính là thứ mà ứng dụng gọi là yêu cầu ký: cùng một thứ, dưới tên gọi trong API. Mỗi yêu cầu chứa tối đa 10 tài liệu, những người ký hoặc nhận chúng, và các ô mà mỗi người ký điền.

AutomaDoc Sign ghi lại một chữ ký điện tử đơn giản có nhật ký kiểm tra: ai đã ký, khi nào, từ đâu, và dấu vân tay (SHA-256) của từng tệp. Đây không phải chữ ký số dựa trên chứng thư. Một số tài liệu (di chúc, việc gia đình, hồ sơ nộp tòa) và một số hệ thống của cơ quan nhà nước cần một hình thức chữ ký khác, vì vậy hãy kiểm tra tài liệu của bạn cần gì.

Xác thực

Mọi đường dẫn đều nhận một khóa API của công ty (bắt đầu bằng amk_), ở một trong hai header:

X-Webhook-API-Key: amk_…
Authorization: Bearer amk_…

Quản trị viên tạo khóa API của công ty trong Cổng thông tin công ty, tại Công ty → Khóa API (xem Bắt đầu nhanh với API). Khóa riêng của một mẫu chỉ mở được mẫu đó, không mở được các yêu cầu ký của công ty bạn: nó bị từ chối với API_KEY_INVALID. Một khóa thấy mọi yêu cầu ký của công ty mình, dù được tạo qua API hay trong cổng thông tin, và không thấy gì của công ty khác (ENVELOPE_NOT_FOUND).

Có hai giới hạn tốc độ:

• 60 request mỗi phút cho mỗi khóa, tính chung cho mọi đường dẫn envelope.
• 600 tài liệu mỗi phút cho mỗi công ty, dùng chung với API tài liệu và HTTP Trigger. Một lần tạo được tính một cho mỗi tài liệu trong đó.

Vượt quá một trong hai, kết quả trả về là 429 với RATE_LIMITED.

Một yêu cầu ký được gửi đi như thế nào

1. POST /api/v1/envelopes lưu các tài liệu của bạn và trả về 201 ngay lập tức, khi yêu cầu vẫn là draft và mỗi tài liệu có prepareState: "pending".
2. AutomaDoc chuẩn bị từng tài liệu: tệp Word, Excel và PowerPoint được chuyển thành PDF, và văn bản được quét để tìm điểm neo và thẻ [[…]] của bạn. Tài liệu nào vẫn ở trạng thái chờ sau 30 phút sẽ thất bại với timeout.
3. Khi tài liệu cuối cùng sẵn sàng, các ô từ điểm neo và thẻ được đặt và, với send: true, yêu cầu được gửi đi. Người nhận qua email đang đến lượt sẽ nhận lời mời.
4. Đọc GET /api/v1/envelopes/:id để theo dõi. Nếu không gửi được, yêu cầu vẫn là draft và sendError cho biết lý do.

API công khai không có lệnh gửi riêng: yêu cầu được tạo mà không có send: true sẽ vẫn là bản nháp. Bản nháp không gửi được cũng không thể thử lại qua API; hãy tạo một yêu cầu mới. Bản nháp không ai thay đổi trong 30 ngày sẽ bị xóa.

Tạo một yêu cầu ký

POST https://api.automadoc.cc/api/v1/envelopes

Gửi phần thân dưới dạng JSON (Content-Type: application/json, tối đa 14 MB), hoặc dưới dạng multipart/form-data với một phần envelope chứa cùng đoạn JSON đó cộng với một phần cho mỗi tệp (tối đa 26 MB cho toàn bộ request).

Trường	Bắt buộc	Tác dụng
title	có	Hiển thị cho người ký và trong email. Tối đa 200 ký tự.
message	không	Lời nhắn cho người nhận, tối đa 1.000 ký tự.
documents	có	Từ 1 đến 10 tài liệu, theo thứ tự (xem bên dưới).
recipients	có	Từ 1 đến 20 người nhận (xem bên dưới).
fields	không	Các ô đặt theo tọa độ (xem bên dưới). Tối đa 500.
anchors	không	Các ô đặt tương đối so với văn bản trong tài liệu (xem bên dưới). Tối đa 50.
autoTags	không	true đặt ô từ các thẻ [[…]] viết trong tài liệu (xem bên dưới).
send	không	true gửi yêu cầu ngay khi các tài liệu đã được chuẩn bị và các ô đã được đặt. Nếu không, nó vẫn là bản nháp.
locale	không	Ngôn ngữ của email và trang ký: en, zh, id, es, vi, th hoặc ja. Giá trị khác bị bỏ qua.
timezone	không	Múi giờ IANA (Asia/Jakarta) cho ngày tháng ghi trên tài liệu và giấy chứng nhận. Mặc định UTC.
expiryDays	không	Số ngày từ lúc gửi đến khi yêu cầu hết hạn: từ 1 đến 120, mặc định 30.
reminders	không	{ "everyDays": 3, "max": 3 } (mặc định; everyDays từ 1 đến 30, max từ 0 đến 10), hoặc false để không nhắc.
appendCertificate	không	Mặc định true: mỗi PDF đã ký kết thúc bằng giấy chứng nhận hoàn tất. Giấy chứng nhận luôn có thể tải riêng.

Tài liệu

Mỗi tài liệu là đúng một trong các loại sau:

Trường	Là gì
base64	Nội dung tệp dạng base64 (chấp nhận tiền tố data:). Tổng các tài liệu base64 của một request sau khi giải mã tối đa 10 MB; hãy gửi tệp lớn hơn dưới dạng multipart.
file	Tên của một phần trong request multipart chứa tệp.
generationId	Một tài liệu đã hoàn tất do AutomaDoc tạo cho công ty bạn (generationId của API tài liệu, hoặc bất kỳ tài liệu đã tạo nào khác còn được lưu). Tệp của nó được sao chép vào yêu cầu ký.

name là tùy chọn: mặc định là tên tệp của phần đó, tên tệp đã tạo, hoặc “Document 1”, “Document 2”. Đuôi .pdf, .docx, .xlsx hoặc .pptx ở cuối bị bỏ đi. Tệp có thể là PDF, Word, Excel hoặc PowerPoint, được nhận diện theo nội dung, không bao giờ theo tên. Mỗi tệp tối đa 25 MB, và các tệp của một yêu cầu tổng cộng tối đa 50 MB.

Người nhận

Trường	Bắt buộc	Tác dụng
key	có	Tên riêng bạn đặt cho người nhận này (client), dùng trong fields và anchors và được trả về trong mọi phản hồi. Từ 1 đến 60 chữ cái, chữ số, _, - hoặc ., không trùng lặp trong request.
role	có	signer (điền ô và ký) hoặc cc (nhận kết quả đã ký).
name	có	Tối đa 120 ký tự.
email	khi reach: "email"	Nơi gửi lời mời. Tùy chọn với người nhận qua liên kết.
reach	không	"email" (mặc định): AutomaDoc gửi email mời khi đến lượt người nhận này. "link": không gửi thư nào, và phản hồi của lần tạo trả về một signingUrl để bạn tự chuyển.
routingOrder	không	Từ 1 đến 100, mặc định 1. Người nhận có cùng số ký song song; số lớn hơn chờ cho đến khi mọi số nhỏ hơn đã xong.
accessCode	không	Từ 6 đến 128 ký tự mà người nhận phải nhập trước khi xem tài liệu. Năm lần nhập sai sẽ khóa liên kết. Hãy tự đưa mã cho người nhận, không nằm chung tin nhắn với liên kết.
slot	không	Với autoTags: tên vai trò dùng trong thẻ (Client) mà người nhận này điền.

Ô theo tọa độ

Trường	Bắt buộc	Tác dụng
document	có	Chỉ số của tài liệu trong documents, bắt đầu từ 0.
recipient	có	Một key người nhận. Chỉ người ký mới có ô.
type	có	signature, initials, name, date_signed, text, checkbox, company hoặc email.
page	có	Trang, bắt đầu từ 1.
x, y, w, h	có	Vị trí và kích thước tính bằng point (1/72 inch), đo từ góc trên bên trái của trang như khi hiển thị (sau khi xoay, nếu có). Ô phải rộng và cao ít nhất 8 point và nằm trong trang.
required	không	Mặc định true.
label	không	Gợi ý hiển thị cho người ký, tối đa 100 ký tự.
options	không	Cho ô văn bản: maxLength (1 đến 1.000), validate ("number" hoặc "email"), fontSize (6 đến 72, tự thu nhỏ cho vừa).

name và email được điền sẵn tên và địa chỉ của người nhận, người ký có thể sửa; date_signed được điền ngày ký, ghi theo múi giờ của yêu cầu. Trang và vị trí được kiểm tra với các tài liệu đã chuẩn bị khi yêu cầu được gửi (field_bad_page, field_off_page), vì tệp Word chưa có trang nào cho đến khi được chuyển đổi.

Ô theo văn bản neo

Điểm neo đặt một ô tương đối so với đoạn văn bản đã có trong tài liệu, nên bạn không cần tọa độ:

Trường	Bắt buộc	Tác dụng
anchor	có	Đoạn văn bản cần tìm, tối đa 200 ký tự. So khớp chính xác và phân biệt hoa thường; mọi chuỗi khoảng trắng hoặc ngắt dòng đều khớp với mọi chuỗi khác.
recipient	có	Một key người nhận.
type	có	Một loại ô, như ở trên.
occurrence	không	"all" (mặc định: một ô ở mọi lần khớp, tối đa 200), hoặc n cho riêng lần khớp thứ n, đếm trên mọi tài liệu của yêu cầu theo thứ tự đọc.
offsetX, offsetY	không	Số point từ góc trên bên trái của đoạn văn bản khớp đến góc trên bên trái của ô (-2.000 đến 2.000, mặc định 0). offsetY âm dời lên trên.
w, h	không	Kích thước của ô tính bằng point (8 đến 1.000). Mặc định: chữ ký 160×48, chữ ký tắt 64×40, ô đánh dấu 14×14, ngày 110×20, email 180×20, văn bản khác 160×20.
required, label	không	Như với ô theo tọa độ.

Ô nào lẽ ra tràn ra ngoài trang sẽ được dời lại vào trong trang. Điểm neo không khớp gì thì không tạo ra ô, điều này thường hiện ra dưới dạng signer_without_fields trong sendError.

Ô từ thẻ

Với autoTags: true, các thẻ viết trong tài liệu trở thành ô cho người nhận có slot khớp với vai trò của thẻ (khớp chính xác, giữ nguyên hoa thường):

[[sign:Client]]   [[initials:Client]]   [[name:Client]]   [[date:Client]]
[[text:Client:PO number]]   [[check:Client]]   [[company:Client]]   [[email:Client]]
[[sign:Client;w=180;h=50]]   [[text:Client:Notes;optional]]

Góc trên bên trái của ô trùng với góc trên bên trái của thẻ, nên ô phủ lên thẻ. Thẻ có vai trò không người nhận nào điền thì không tạo ra ô.

Phản hồi

201 Created kèm yêu cầu ký. Ngay sau khi tạo, nó là một bản nháp với các tài liệu vẫn đang được chuẩn bị:

{
  "id": "env_01JAB3K9Q7M2X8R4T6V0W1Y2Z3",
  "status": "draft",
  "finishing": false,
  "finalizeFailed": false,
  "title": "Service agreement ACME-2026-114",
  "createdAt": 1792290600000,
  "sentAt": null,
  "expiresAt": null,
  "completedAt": null,
  "documents": [
    {
      "id": "doc_01JAB3K9RA5C7E9G1H3J5K7M9N",
      "name": "Service agreement",
      "prepareState": "pending",
      "prepareError": null,
      "pageCount": null,
      "originalSha256": "3b7e0c…",
      "preparedSha256": null,
      "finalSha256": null,
      "deliveredSha256": null
    }
  ],
  "recipients": [
    {
      "id": "rcp_01JAB3K9R2B4D6F8H0J2K4M6P8",
      "key": "client",
      "role": "signer",
      "name": "Dana Lee",
      "email": "dana@example.com",
      "status": "created",
      "routingOrder": 1,
      "viewedAt": null,
      "completedAt": null,
      "declineReason": null
    }
  ],
  "auditHead": "a41f9d…",
  "sendError": null
}

Người nhận có reach: "link" còn có thêm signingUrl (https://sign.automadoc.cc/#/…) chỉ trong phản hồi này: không lần đọc nào sau đó trả về nó, nên hãy lưu lại ngay. Liên kết bắt đầu hoạt động khi yêu cầu được gửi. Mỗi email mời và lời nhắc mang một liên kết mới, vì vậy người nhận qua liên kết không bao giờ được nhắc qua email.

Đọc một yêu cầu ký

GET https://api.automadoc.cc/api/v1/envelopes/{envelopeId}

Trả về cùng cấu trúc như khi tạo, theo trạng thái hiện tại. Hãy hỏi lại vài giây một lần trong lúc tài liệu được chuẩn bị; khi yêu cầu đã được gửi đi, vài phút hỏi một lần là đủ.

status	Ý nghĩa
draft	Chưa gửi: tài liệu đang chuẩn bị, không yêu cầu send, hoặc sendError cho biết vì sao không gửi được.
sent	Đang chờ ký.
completed	Mọi người đã ký và các tệp đã ký đã sẵn sàng.
declined	Một người ký đã từ chối; declineReason của họ nằm trên mục người nhận của họ.
voided	Bạn đã hủy yêu cầu.
expired	expiresAt đã qua trước khi mọi người ký.

finishing: true (với status: "sent") nghĩa là mọi người đã ký và các PDF đã ký đang được tạo. finalizeFailed: true nghĩa là không tạo được chúng sau mọi lần thử lại: các chữ ký vẫn được giữ và đội ngũ của chúng tôi đã được báo.

Người nhận đi qua các trạng thái created (chưa đến lượt), sent, viewed, rồi completed hoặc declined. Người nhận cc ở trạng thái sent ngay từ đầu.

Mỗi tài liệu mang SHA-256 của từng giai đoạn: originalSha256 (tệp của bạn), preparedSha256 (PDF mà mọi người đã xem và ký), finalSha256 (đã đóng chữ ký) và deliveredSha256 (tệp bạn tải về: đã đóng chữ ký, cộng giấy chứng nhận khi được gắn kèm). auditHead là mã băm của sự kiện cuối cùng trong nhật ký kiểm tra của yêu cầu. Bất kỳ ai cũng có thể kiểm tra một tệp đã giao bằng POST https://api.automadoc.cc/api/verify với { "sha256": "…" } (chuỗi hex chữ thường của toàn bộ tệp), kết quả cho biết tệp có khớp với một yêu cầu đã hoàn tất hay không.

Liệt kê các yêu cầu ký

GET https://api.automadoc.cc/api/v1/envelopes?status=completed&since=1792290600000&limit=50

Tham số truy vấn	Tác dụng
status	draft, sent, completed, declined, voided hoặc expired.
since	Chỉ các yêu cầu được cập nhật từ thời điểm này trở đi (Unix ms).
limit	Từ 1 đến 100, mặc định 25.
cursor	nextCursor của trang trước.

Kết quả là { "envelopes": [ … ], "nextCursor": "…" }, mới nhất trước; nextCursor là null ở trang cuối. key là null với người nhận của các yêu cầu tạo trong cổng thông tin.

Tải các tệp đã ký

GET https://api.automadoc.cc/api/v1/envelopes/{envelopeId}/documents/{documentId}/signed
GET https://api.automadoc.cc/api/v1/envelopes/{envelopeId}/certificate
GET https://api.automadoc.cc/api/v1/envelopes/{envelopeId}/combined

signed là một tài liệu đã ký; certificate là riêng giấy chứng nhận hoàn tất; combined là mọi tài liệu đã ký trong một PDF (có giấy chứng nhận ở cuối khi được gắn kèm), chỉ được tạo cho yêu cầu có từ hai tài liệu trở lên. Các đường dẫn này hoạt động khi yêu cầu đã completed: trước đó, chúng trả về 409 với DOCUMENT_NOT_FOUND.

Kết quả là một liên kết ngắn hạn, không phải bản thân tệp:

{
  "url": "https://api.automadoc.cc/api/esign-files/env_01JAB3K9Q7M2X8R4T6V0W1Y2Z3/final/doc_01JAB3K9RA5C7E9G1H3J5K7M9N.pdf?e=…&d=a&n=…&s=…",
  "filename": "Service agreement.pdf",
  "expiresAt": 1792306800000,
  "sha256": "e5a01c…"
}

Hãy tải url trong vòng 15 phút; không cần khóa. Hỏi lại để có liên kết mới. sha256 là dấu vân tay của tệp (với signed, đó là deliveredSha256 của tài liệu). Mỗi lần tải xuống đều được ghi vào nhật ký kiểm tra. Các tệp đã ký của một yêu cầu đã hoàn tất được giữ cho đến khi có người xóa.

Hủy một yêu cầu ký

POST https://api.automadoc.cc/api/v1/envelopes/{envelopeId}/void
{ "reason": "Replaced by version 2" }

Dừng một yêu cầu đã gửi: các liên kết ngừng hoạt động, và những người nhận đã được gửi yêu cầu sẽ được báo qua email. reason là bắt buộc (tối đa 500 ký tự). Trả về yêu cầu ký, giờ ở trạng thái voided. Chỉ có thể hủy yêu cầu đã gửi và vẫn đang mở.

Nhắc một người nhận

POST https://api.automadoc.cc/api/v1/envelopes/{envelopeId}/recipients/{recipientId}/remind

recipientId là id của người nhận (rcp_…), không phải key của bạn. Gửi ngay cho người nhận một email có liên kết mới; liên kết trong các email trước ngừng hoạt động. Chỉ áp dụng cho người nhận qua email đang đến lượt, tối đa mỗi 10 phút một lần. Trả về { "remindedAt": 1792300000000, "channel": "email" }. Lời nhắc tự động theo cài đặt reminders của yêu cầu mà không cần gọi gì.

Ví dụ: curl

Tạo một yêu cầu ký với một người ký, đặt chữ ký cạnh đoạn văn bản “Client signature:” và ngày cạnh “Date:”, rồi gửi đi. Đoạn JSON nằm trong phần envelope và tệp PDF trong phần tên contract:

cat > envelope.json <<'EOF'
{
  "title": "Service agreement ACME-2026-114",
  "message": "Please review and sign by Friday.",
  "timezone": "Asia/Jakarta",
  "documents": [{ "name": "Service agreement", "file": "contract" }],
  "recipients": [
    { "key": "client", "role": "signer", "name": "Dana Lee", "email": "dana@example.com" }
  ],
  "anchors": [
    { "anchor": "Client signature:", "recipient": "client", "type": "signature", "offsetX": 110, "offsetY": -10 },
    { "anchor": "Date:", "recipient": "client", "type": "date_signed", "offsetX": 40, "occurrence": 1 }
  ],
  "send": true
}
EOF

curl -X POST 'https://api.automadoc.cc/api/v1/envelopes' \
  -H "X-Webhook-API-Key: $AUTOMADOC_KEY" \
  -F 'envelope=<envelope.json' \
  -F 'contract=@contract.pdf;type=application/pdf'

Theo dõi cho đến khi status là sent (hoặc sendError được đặt), rồi cho đến khi nó là completed:

curl -s 'https://api.automadoc.cc/api/v1/envelopes/ENVELOPE_ID' \
  -H "X-Webhook-API-Key: $AUTOMADOC_KEY"

Khi đã hoàn tất, lấy liên kết của tài liệu đã ký và tải về:

url=$(curl -s 'https://api.automadoc.cc/api/v1/envelopes/ENVELOPE_ID/documents/DOCUMENT_ID/signed' \
  -H "X-Webhook-API-Key: $AUTOMADOC_KEY" | jq -r .url)
curl -s -o signed.pdf "$url"

Cũng lần tạo đó ở dạng JSON thì đặt tệp vào base64: "documents": [{ "name": "Service agreement", "base64": "JVBERi0xLjcK…" }].

Ví dụ: Node.js

Node.js 18 trở lên. Chạy bằng AUTOMADOC_KEY=amk_… node sign.mjs:

import { readFile, writeFile } from 'node:fs/promises'
import { createHash } from 'node:crypto'

const API = 'https://api.automadoc.cc'
const KEY = process.env.AUTOMADOC_KEY

async function call(method, path, body) {
  const res = await fetch(API + path, {
    method,
    headers: body ? { 'X-Webhook-API-Key': KEY, 'Content-Type': 'application/json' } : { 'X-Webhook-API-Key': KEY },
    body: body ? JSON.stringify(body) : undefined,
  })
  const json = await res.json()
  if (!res.ok) throw new Error(`${res.status} ${json.code}: ${json.error}`)
  return json
}

const pdf = await readFile('contract.pdf')
let envelope = await call('POST', '/api/v1/envelopes', {
  title: 'Service agreement ACME-2026-114',
  documents: [{ name: 'Service agreement', base64: pdf.toString('base64') }],
  recipients: [{ key: 'client', role: 'signer', name: 'Dana Lee', email: 'dana@example.com' }],
  anchors: [{ anchor: 'Client signature:', recipient: 'client', type: 'signature', offsetX: 110, offsetY: -10 }],
  send: true,
})

// The documents are prepared and the fields placed, then the envelope is sent.
while (envelope.status === 'draft' && !envelope.sendError) {
  await new Promise((resolve) => setTimeout(resolve, 2000))
  envelope = await call('GET', `/api/v1/envelopes/${envelope.id}`)
}
if (envelope.sendError) throw new Error(`Not sent: ${JSON.stringify(envelope.sendError)}`)
console.log(`${envelope.id} is ${envelope.status}`)

// Later (a scheduled job, say): download every signed document of a completed envelope.
export async function downloadSigned(envelopeId) {
  const current = await call('GET', `/api/v1/envelopes/${envelopeId}`)
  if (current.status !== 'completed') return false
  for (const doc of current.documents) {
    const link = await call('GET', `/api/v1/envelopes/${envelopeId}/documents/${doc.id}/signed`)
    const bytes = Buffer.from(await (await fetch(link.url)).arrayBuffer())
    if (createHash('sha256').update(bytes).digest('hex') !== link.sha256) throw new Error('Download damaged')
    await writeFile(`${doc.id}.pdf`, bytes)
  }
  return true
}

Lỗi

Lỗi được trả về dạng JSON: { "code": "…", "error": "English text" }, kèm path chỉ ra phần bị lỗi của request (recipients[1].email) khi có.

HTTP	code	Khi nào
400	INVALID_REQUEST	Request không hợp lệ; xem path và error.
401	API_KEY_MISSING	Không có khóa trong X-Webhook-API-Key hoặc Authorization.
403	API_KEY_INVALID	Khóa không tồn tại hoặc đã bị thu hồi, hoặc là khóa riêng của một mẫu.
403	ESIGN_SEND_BLOCKED	Nhắc: việc gửi của công ty bạn đang bị tạm dừng trong lúc một báo cáo về email của công ty được xem xét. Hãy liên hệ bộ phận hỗ trợ.
404	ENVELOPE_NOT_FOUND	Không có yêu cầu ký này trong công ty bạn.
404	RECIPIENT_NOT_FOUND	Nhắc: không có người nhận này trong yêu cầu.
404	DOCUMENT_NOT_FOUND	Tải xuống: không có tài liệu này, hoặc không có tệp này (tệp combined của một yêu cầu chỉ có một tài liệu).
404	GENERATION_NOT_FOUND	generationId không phải là tài liệu đã tạo của công ty bạn.
409	GENERATION_NOT_COMPLETED	Tài liệu đã tạo chưa hoàn tất, hoặc không còn được lưu.
409	DOCUMENT_NOT_FOUND	Tải xuống trước khi yêu cầu hoàn tất.
409	ENVELOPE_NOT_DRAFT	Hủy hoặc nhắc một yêu cầu chưa từng được gửi.
409	ENVELOPE_CLOSED	Hủy hoặc nhắc một yêu cầu đã hoàn tất, bị từ chối, bị hủy hoặc hết hạn.
409	ENVELOPE_FINISHING	Hủy hoặc nhắc sau khi mọi người đã ký, trong lúc các tệp đã ký đang được tạo.
409	NOT_ALLOWED	Nhắc một người nhận chưa đến lượt, hoặc một người nhận qua liên kết.
410	ENVELOPE_CLOSED	Tải xuống sau khi các tệp của yêu cầu đã bị xóa.
413	FILE_TOO_LARGE	Một tệp trên 25 MB, hoặc một request multipart trên 26 MB.
413	ENVELOPE_TOO_LARGE	Tổng các tài liệu base64 trên 10 MB, hoặc tổng các tệp trên 50 MB.
413	INVALID_REQUEST	Phần thân JSON trên 14 MB.
415	UNSUPPORTED_FILE	Tệp không phải PDF, Word, Excel hoặc PowerPoint.
429	RATE_LIMITED	Quá 60 request mỗi phút cho khóa, hoặc 600 tài liệu mỗi phút cho công ty.
429	ESIGN_SEND_RATE_LIMITED	Nhắc: người nhận này đã được nhắc chưa đầy 10 phút trước.
502	ESIGN_WORKER_UNAVAILABLE	Nhắc: không gửi được lời nhắc.
503	ESIGN_WORKER_UNSUPPORTED	Hiện không thể chuẩn bị tài liệu để ký. Hãy thử lại sau; không có gì được tạo.

Một lần tạo bị từ chối trong lúc đang lưu tài liệu sẽ xóa bản nháp và các tệp của nó, nên không để lại thứ gì dang dở.

Vì sao yêu cầu ký không được gửi

Với send: true, việc gửi diễn ra sau khi lần tạo đã trả kết quả, nên các lần từ chối xuất hiện trong sendError của yêu cầu (vẫn là draft), không phải dưới dạng mã trạng thái HTTP:

sendError.code	Ý nghĩa
SEND_PROBLEMS	Yêu cầu chưa đầy đủ; problems liệt kê lý do (xem bên dưới).
QUOTA_EXCEEDED	Hạn mức hằng tháng và mọi gói tài liệu đã dùng hết (xem chi phí).
ESIGN_SEND_RATE_LIMITED	Gói Miễn phí: công ty bạn đã gửi 3 yêu cầu trong một giờ qua. Ở mọi gói: hơn 10 lần gửi trong một phút.
ESIGN_RECIPIENT_CAP	Lần gửi này sẽ vượt số người nhận mỗi ngày mà công ty bạn được phép gửi tới (xem bên dưới).
ESIGN_SEND_BLOCKED	Việc gửi của công ty bạn đang bị tạm dừng trong lúc một báo cáo về email của công ty được xem xét. Hãy liên hệ bộ phận hỗ trợ.
ESIGN_EMAIL_UNAVAILABLE	Không thể gửi email cho yêu cầu này. Không có gì được gửi hay bị tính phí; người nhận có reach: "link" vẫn dùng được.
ESIGN_EMAIL_UNVERIFIED	Người tạo khóa chưa có địa chỉ email đã xác minh.
ESIGN_ALREADY_PENDING	Tài liệu đã tạo này đang chờ ký trong một yêu cầu khác.
INVALID_REQUEST	Thẻ và điểm neo cộng lại tạo ra hơn 500 ô, hoặc đã xảy ra lỗi ngoài dự kiến.

Mỗi vấn đề có dạng { "code": "…" }, kèm documentId, recipientId hoặc fieldId khi nó liên quan đến một trong số đó (là id, không phải key của bạn):

Vấn đề	Ý nghĩa
document_failed	Một tài liệu không chuẩn bị được; prepareError của nó cho biết lý do (xem bên dưới).
too_many_pages	Các tài liệu có tổng cộng hơn 300 trang.
envelope_too_large	Các tệp tổng cộng hơn 50 MB, hoặc các PDF đã chuẩn bị hơn 100 MB.
no_signer	Không người nhận nào có vai trò signer.
signer_without_fields	Một người ký không có ô nào: một điểm neo không khớp gì, hoặc vai trò của một thẻ không có slot.
recipient_missing_email	Một người nhận qua email không có địa chỉ.
recipient_role_unavailable	Một vai trò khác signer hoặc cc.
too_many_fields	Hơn 500 ô.
field_for_non_signer	Một ô được giao cho người nhận cc.
field_bad_page	Trang của một ô vượt quá cuối tài liệu.
field_off_page	Một ô tràn ra ngoài trang, hoặc nhỏ hơn 8 point.
field_type_unavailable	Một loại ô khác với tám loại liệt kê ở trên.

prepareError của một tài liệu là một trong các giá trị pdf_encrypted (PDF được bảo vệ bằng mật khẩu), file_too_large (PDF đã chuẩn bị sẽ vượt 50 MB), too_many_pages, unsupported_file, invalid_file (tệp bị hỏng), conversion_failed, source_unavailable, timeout hoặc internal.

Giới hạn

Giới hạn	Giá trị
Số tài liệu mỗi yêu cầu	10
Một tệp	25 MB
Tổng các tệp của một yêu cầu	50 MB
Một tài liệu đã chuẩn bị (PDF mà mọi người ký)	50 MB
Tổng các tài liệu đã chuẩn bị của một yêu cầu	100 MB
Số trang trên mọi tài liệu của một yêu cầu	300
Số người nhận mỗi yêu cầu	20
Số ô mỗi yêu cầu	500
Số điểm neo mỗi request	50, mỗi điểm neo khớp tối đa 200 lần
Phần thân request JSON	14 MB, với tối đa 10 MB tài liệu base64
Request multipart	26 MB
Hạn	Từ 1 đến 120 ngày sau khi gửi, mặc định 30
Lời nhắc	Cứ 1 đến 30 ngày một lần, tối đa 10 lần; mặc định cứ 3 ngày, 3 lần
Số lần nhập sai mã truy cập trước khi liên kết bị khóa	5
Liên kết tải xuống	15 phút
Bản nháp	Bị xóa sau 30 ngày không thay đổi
Tệp của yêu cầu bị từ chối, bị hủy và hết hạn	Bị xóa 90 ngày sau khi đóng

Để gửi hơn 26 MB tệp, hãy thêm chúng bằng generationId, vì cách này không truyền tệp trong request.

Giới hạn gửi. Không có Pro và không có suất Business, một công ty gửi tối đa 3 yêu cầu mỗi giờ và gửi tới tối đa 20 người nhận mỗi ngày (5 mỗi ngày trong 24 giờ đầu của tài khoản). Với Pro hoặc suất Business, công ty gửi tới tối đa 1.000 người nhận mỗi ngày. Mọi người nhận đều được tính, kể cả cc và người nhận qua liên kết, trong khoảng 24 giờ tính trượt. Mọi công ty gửi tối đa 10 yêu cầu mỗi phút.

Chi phí

• Một yêu cầu đã gửi dùng một tài liệu trong hạn mức của bạn, bất kể chứa bao nhiêu tài liệu và người nhận. Yêu cầu được tính phí khi gửi và không được hoàn lại nếu sau đó bị hủy, bị từ chối hoặc hết hạn. Bản nháp không tốn gì.
• Tài liệu do AutomaDoc tạo được gửi miễn phí lần đầu: yêu cầu mà mọi tài liệu đều đến từ generationId thì không tốn gì, trừ khi một trong số đó đã được gửi trong một yêu cầu khác; khi đó nó tốn một tài liệu. Yêu cầu kết hợp tệp đã tạo và tệp tải lên tốn một tài liệu.
• Ai chi trả. Yêu cầu gửi bằng khóa của công ty là tự động, giống API tài liệu: miễn phí với Pro (hoặc bản dùng thử); nếu không thì trừ vào hạn mức tự động hóa của suất Business trước, rồi đến hạn mức miễn phí hằng tháng, rồi đến các gói tài liệu của bạn. Khi tất cả đã hết, sendError là QUOTA_EXCEEDED. Suất Starter thuộc về một người và không áp dụng cho việc gửi qua API.

Các giới hạn gửi ở trên áp dụng cho mọi gói.