Đặt ô tự động

Đặt ô bằng tay thì ổn với một tài liệu. Với hợp đồng bạn gửi mỗi tuần, hay một tài liệu do AutomaDoc tạo, hãy viết thẻ vào tài liệu: [[sign:Client]] ở chỗ khách hàng ký, [[date:Client]] ở chỗ ghi ngày. Khi tài liệu được chuẩn bị, AutomaDoc tìm từng thẻ và đặt ô vào đó. Bên gọi API không sửa được tài liệu thì có thể dùng điểm neo: một ô được đặt tương đối so với đoạn văn bản đã có sẵn trong tài liệu.

Thẻ văn bản

Ví dụ trong Word

Gõ các thẻ như văn bản thường ở chỗ cần đặt ô:

Signed for the client:

[[sign:Client]]

Name: [[name:Client]]          Date: [[date:Client]]
Company: [[company:Client]]
Purchase order: [[text:Client:PO number;optional]]

[[check:Client:Terms]] I have read and accept the terms.

Signed for the supplier:

[[sign:Supplier;w=180;h=50]]
Initials on every page: [[initials:Supplier]]

Khi bạn thêm tài liệu này vào một yêu cầu, nó có hai vị trí, Client và Supplier. Giao mỗi vị trí cho một người nhận và mọi ô của vai trò đó sẽ thuộc về người ấy. Từ API, đặt autoTags: true và cho mỗi người nhận slot của họ.

Thẻ hoạt động giống nhau trong tệp PDF, Word, Excel hoặc PowerPoint, và trong mẫu AutomaDoc: quá trình tạo tài liệu không đụng đến dấu ngoặc vuông, nên tài liệu tạo từ một mẫu có thẻ sẽ đến yêu cầu với các ô sẵn sàng để đặt. Đó là lý do thẻ dùng [[ ]] chứ không dùng { } của biến giữ chỗ trong mẫu.

Cú pháp

[[ kind : role ]]
[[ kind : role : label ]]
[[ kind : role ; option ; option ]]
[[ kind : role : label ; option ]]

Kind (loại, viết hoa hay thường đều được) cho biết ô là gì:

Kind	Cách viết khác	Ô
`sign`	`signature`	Chữ ký
`initials`	`initial`	Chữ ký tắt
`name`		Họ tên
`date`		Ngày ký (điền tự động)
`text`		Văn bản
`check`	`checkbox`	Ô đánh dấu
`company`		Công ty
`email`		Email

Role (vai trò) là vị trí mà ô thuộc về: từ 1 đến 60 chữ cái, chữ số, dấu thanh hoặc dấu gạch dưới, trong bất kỳ bảng chữ cái nào (Client, Witness_1, 客户). Không có khoảng trắng. Có phân biệt hoa thường: Client và client là hai vị trí khác nhau. Dấu # theo sau là chữ số đặt sau vai trò được dành riêng cho AutomaDoc.

Label (nhãn), tùy chọn, gồm 1 đến 100 ký tự hiển thị cho người ký như tên của ô, ví dụ [[text:Client:PO number]]. Nhãn không được chứa [, ], ; hoặc :.

Option (tùy chọn), mỗi tùy chọn đứng sau một dấu ;, viết hoa hay thường đều được:

Tùy chọn	Ý nghĩa
`w=180`	Chiều rộng tính bằng point (1 point bằng 1/72 inch), từ 8 đến 1000, tối đa hai chữ số thập phân
`h=50`	Chiều cao tính bằng point, từ 8 đến 1000
`optional`	Người ký có thể để trống ô
`required`	Người ký phải điền (mặc định)

Khoảng trắng và ngắt dòng được phép quanh mọi phần, nên [[ sign : Client ]] vẫn hoạt động, và thẻ bị xuống dòng giữa hai phần của nó cũng vậy. Ngắt dòng ở giữa một từ (chẳng hạn giữa chữ Client) sẽ làm hỏng thẻ.

Một thẻ dài tối đa 200 ký tự tính từ [[ đến ]]. Dài hơn thế, hoặc thiếu ]] đóng, thì nó chỉ là văn bản thường và bị bỏ qua.

Ô được đặt ở đâu

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ẻ. Kích thước của ô là w và h của thẻ, nếu không thì là kích thước mặc định của loại ô (tính bằng point: chữ ký 160 × 48, chữ ký tắt 64 × 40, ô đánh dấu 14 × 14, email 180 × 20, ngày 110 × 20, các ô văn bản khác 160 × 20). Khi không có h, ô không bao giờ thấp hơn chữ của thẻ. Ô nào lẽ ra tràn ra ngoài trang sẽ được dời vào trong trang.

Vì vậy hãy chừa chỗ ở bên phải và bên dưới mỗi thẻ: ô chữ ký kéo dài 48 point (khoảng 1,7 cm) xuống dưới tính từ đỉnh của thẻ.

Khi có gì đó sai

Một [[…]] không đúng cú pháp sẽ không bao giờ bị đoán ý: nó vẫn nằm trên trang dưới dạng văn bản, không ô nào được tạo, và người gửi được cảnh báo kèm thẻ như đã viết (tối đa 50 thẻ đầu tiên mỗi tài liệu). Nguyên nhân thường gặp là thiếu vai trò, có khoảng trắng trong vai trò, loại hoặc tùy chọn không xác định, hoặc kích thước nằm ngoài khoảng 8 đến 1000.

Các giới hạn khác:

chỉ đọc tối đa 500 thẻ mỗi trang và 500 thẻ mỗi tài liệu; vượt quá thì phần còn lại bị bỏ qua kèm cảnh báo;
chỉ tìm trong văn bản mà PDF thực sự chứa: trang được quét là một hình ảnh, và thẻ trong đó không được tìm thấy;
thẻ có vai trò không được giao cho người nhận nào thì không tạo ra ô. Một người ký không còn ô nào thì yêu cầu không thể gửi đi.

Áp dụng thẻ lần nữa sẽ thay thế các ô đã tạo từ thẻ. Các ô bạn đặt bằng tay vẫn giữ nguyên.

Điểm neo từ API

Điểm neo đặt một ô tương đối so với đoạn văn bản đã có trong tài liệu, như “Client signature:”. Cách này dành cho tài liệu bạn không sửa được. Điểm neo là một phần của POST /api/v1/envelopes (xem API yêu cầu ký). Ở đây yêu cầu được gửi dưới dạng multipart/form-data: đoạn JSON này nằm trong phần tên envelope, tệp PDF trong phần tên contract.

{
  "title": "Service agreement",
  "documents": [{ "file": "contract" }],
  "recipients": [
    { "key": "client", "role": "signer", "name": "Ana Lim", "email": "ana@example.com" }
  ],
  "anchors": [
    { "anchor": "Client signature:", "recipient": "client", "type": "signature", "offsetY": 14 },
    { "anchor": "Date:", "occurrence": 2, "recipient": "client", "type": "date_signed", "offsetX": 30, "offsetY": -2 }
  ],
  "send": true
}

Thuộc tính
`anchor`	Đoạn văn bản cần tìm, từ 1 đến 200 ký tự. Bắt buộc.
`recipient`	`key` của một người nhận trong cùng yêu cầu. Bắt buộc.
`type`	`signature`, `initials`, `name`, `date_signed`, `text`, `checkbox`, `company` hoặc `email`. Bắt buộc.
`occurrence`	`"all"` (mặc định) hoặc một số: lần khớp thứ 1, thứ 2… trên toàn bộ yêu cầu.
`offsetX`, `offsetY`	Số point tính từ góc trên bên trái của đoạn văn bản khớp, từ -2000 đến 2000. Số dương đi sang phải và xuống dưới. Mặc định 0.
`w`, `h`	Kích thước tính bằng point, từ 8 đến 1000. Mặc định: kích thước của loại ô.
`required`	Mặc định `true`.
`label`	Hiển thị cho người ký như tên của ô.

Một yêu cầu có thể chứa tối đa 50 điểm neo.

Cách so khớp văn bản

Chính xác và phân biệt hoa thường: Signature: không khớp với signature: hay Signature.
Mọi chuỗi khoảng trắng, tab hoặc ngắt dòng trong điểm neo đều khớp với mọi chuỗi như vậy trong tài liệu, vì văn bản PDF không giữ khoảng cách một cách đáng tin cậy. Khoảng trắng ở đầu hoặc cuối điểm neo bị bỏ qua.
Các lần khớp không bao giờ chồng lên nhau.
Số lần xuất hiện được đếm trên toàn bộ yêu cầu theo thứ tự đọc: các tài liệu theo thứ tự của chúng, rồi từng trang, từ trên xuống dưới, từ trái sang phải. "occurrence": 2 là lần khớp thứ hai ở bất kỳ đâu trong yêu cầu, không phải lần thứ hai trên mỗi trang.
Tối đa 200 lần khớp mỗi điểm neo. Nhiều hơn được coi là nhầm lẫn: hãy viết điểm neo dài hơn.

Điểm neo không khớp gì thì không tạo ra ô, và tài liệu ghi lại cảnh báo anchor_not_found. Giống như với thẻ, ô của điểm neo lẽ ra tràn ra ngoài trang sẽ được dời vào trong trang, và một người ký không còn ô nào sẽ khiến yêu cầu không thể gửi đi: khi đó GET /api/v1/envelopes/:id cho biết lý do trong sendError.

Bạn có thể kết hợp ô theo tọa độ, thẻ (autoTags) và điểm neo trong cùng một yêu cầu, tổng cộng tối đa 500 ô.