Tự động hóa

Tự động hóa việc tạo tài liệu bằng Lark Base Automation: tài liệu được tạo tự động khi bản ghi được tạo mới, cập nhật, hoặc khi thỏa mãn điều kiện nhất định.

1. Bật HTTP Trigger

Vào tab Mẫu.
Mở mục Tự động hóa và mở rộng HTTP Trigger.
Sao chép URL webhook được cung cấp.

2. Thiết lập tự động hóa trong Lark Base

Mở Base của bạn → Automations.
Tạo một automation mới.
Thêm điều kiện kích hoạt (ví dụ “When record is created”).
Thêm hành động: Send HTTP Request.
Cấu hình: Method = POST, URL = URL webhook vừa sao chép + ?recordId={{record_id}}.
Thêm header: X-Webhook-API-Key: <khóa API của bạn>.

Định dạng URL webhook:

https://api.automadoc.cc/api/webhook/templates/{templateId}/generate?recordId={recordId}

Khóa có thể là khóa riêng của mẫu hoặc khóa API của công ty, do quản trị viên ứng dụng tạo trong Cổng thông tin công ty tại Công ty → Khóa API, và dùng được cho mọi mẫu. Phản hồi liệt kê generationIds của các tài liệu đã được khởi tạo; GET /api/v1/documents/{generationId} cho biết trạng thái của từng tài liệu.

Gửi tài liệu để ký

Để gửi từng tài liệu được tạo đi ký, hãy thêm nội dung JSON cho bước Send HTTP Request (Content-Type: application/json):

{ "sign": {} }

Người ký được lấy từ bản ghi, theo thiết lập trong mục Ký tự động ở tab Mẫu; liên kết và mật khẩu tự tạo cho người bên ngoài được ghi lại vào bản ghi để quy trình tự động của bạn gửi email. Nếu muốn chỉ định người ký ngay trong yêu cầu, hãy truyền signers theo vai trò, giống như API tài liệu. Xem Chữ ký điện tử.

Công thức cho từng loại điều kiện kích hoạt

Mọi công thức đều kết thúc bằng cùng một bước: Send HTTP Request với method POST, URL webhook theo sau là ?recordId= và record ID của bản ghi mà điều kiện kích hoạt tìm thấy, cùng header X-Webhook-API-Key. Chỉ có điều kiện kích hoạt thay đổi. Tên các điều kiện kích hoạt có thể hơi khác nhau giữa các phiên bản Lark.

Khi một bản ghi được thêm: một tài liệu cho mỗi bản ghi mới, ví dụ một báo giá ngay khi yêu cầu được nhập. Chọn điều kiện kích hoạt cho bản ghi mới, và chọn bảng.

Khi một bản ghi được chỉnh sửa: một tài liệu mới khi bản ghi thay đổi. Chọn điều kiện kích hoạt cho bản ghi được sửa đổi và các trường cần theo dõi (ví dụ chỉ Amount và Customer), để một chỉnh sửa không liên quan không tạo ra tài liệu mới.

Khi một bản ghi thỏa mãn điều kiện: một tài liệu ngay khi bản ghi đạt tới một trạng thái, ví dụ Status chuyển thành Approved. Đây là công thức phổ biến nhất: nó chạy một lần, vào lúc điều kiện bắt đầu được thỏa mãn.

Khi đến một ngày: một tài liệu vào một ngày ghi trong bản ghi, ví dụ thư nhắc nhở vào Due date, hoặc bảy ngày trước đó. Chọn trường ngày và khoảng chênh lệch.

Theo lịch: tài liệu vào một thời điểm định sẵn, ví dụ mỗi thứ Hai lúc 9:00. Lịch không có bản ghi riêng, vì vậy hãy thêm bước Find records (ví dụ “Status is Open”), rồi gửi yêu cầu HTTP cho các bản ghi tìm được, dùng record ID của chúng. Hãy kiểm tra trong một lần chạy thử rằng yêu cầu được gửi một lần cho mỗi bản ghi.

Từ AnyCross hoặc bất kỳ HTTP client nào

AnyCross và các công cụ tích hợp khác có thể gọi AutomaDoc bằng một node HTTP request thông thường. Để tạo tài liệu từ một bản ghi Base, hãy dùng HTTP Trigger ở trên. Để tạo tài liệu từ dữ liệu không nằm trong Base (một biểu mẫu, một hệ thống ERP), hãy dùng API tài liệu, API này nhận dữ liệu dạng JSON:

Cài đặt	Giá trị
Method	`POST`
URL	`https://api.automadoc.cc/api/v1/templates/{templateId}/documents?wait=20`
Header	`X-Webhook-API-Key`: khóa API của mẫu hoặc của công ty
Header	`Content-Type`: `application/json`
Body	`{"data": { … the fields of your document … }}`

Với ?wait=20, phản hồi được trả về khi tài liệu đã sẵn sàng, và downloadUrl trong đó có thể được chuyển sang node tiếp theo, để đính kèm tệp vào tin nhắn hoặc lưu vào Drive.

Khi yêu cầu bị từ chối

Khi lý do từ chối liên quan đến gói của bạn, HTTP Trigger trả về 403 kèm code trong phần thân JSON:

`code`	Lý do	Cách xử lý
`AUTOMATION_NOT_INCLUDED`	Công ty bạn không có gói Pro, không có bản dùng thử đang hoạt động và không có suất Business.	Mua suất Business hoặc Pro tại trang Thanh toán trong Cổng thông tin công ty.
`QUOTA_EXCEEDED`	Số tài liệu tự động đi kèm suất Business và hạn mức miễn phí hằng tháng đã hết, và các gói tài liệu cũng không còn tài liệu nào.	Mua gói tài liệu tại trang Thanh toán, hoặc chờ kỳ tiếp theo.
`TEMPLATE_DISABLED`	Mẫu bị khóa: công ty bạn có nhiều mẫu hơn mức gói cho phép.	Tăng giới hạn mẫu tại trang Thanh toán (gói, suất hoặc Mẫu bổ sung), hoặc xóa bớt một mẫu. Mẫu bị khóa sẽ trở lại trong vòng 24 giờ.

Thiếu X-Webhook-API-Key sẽ bị từ chối với 401 (API_KEY_MISSING), còn khóa sai hoặc không mở được mẫu này với 403 (API_KEY_INVALID).

HTTP Trigger nhận tối đa 300 yêu cầu mỗi phút cho mỗi mẫu, một giới hạn riêng: tự động hóa của Lark gửi mỗi bản ghi một lần và không thử lại, nên không áp dụng mức 60 của API tài liệu. Tài liệu của nó được tính vào giới hạn 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. Khi vượt một trong hai giới hạn, phản hồi là 429 (RATE_LIMITED) và không tạo tài liệu nào cho yêu cầu đó, vì vậy hãy chia một lần nhập rất lớn ra trong vài phút. Mọi lần từ chối khác cũng có code, ví dụ RECORD_ID_REQUIRED (400, thiếu recordId) và WORKER_UNAVAILABLE (502, thử lại sau ít phút).

Thông báo gửi đi

Nhận thông báo khi tài liệu được tạo xong. Rất hữu ích để kích hoạt các bước tự động hóa tiếp theo.

Ở tab Mẫu, mở mục Tự động hóa và bật Callback Webhook.
Nhập URL webhook của bạn.
Tùy chọn: thêm Bearer token để xác thực.

AutomaDoc gửi một yêu cầu POST với nội dung JSON như sau:

{
  "url": "https://api.automadoc.cc/...?expires=...&signature=...",
  "filename": "Invoice-INV-2024-001.pdf",
  "fields": { "Customer_Name": "Acme Corp", "Total_Amount": "1,500.00" }
}

url: liên kết tải xuống có chữ ký, hiệu lực 2 giờ.
filename: tên tệp cuối cùng sau khi áp dụng mẫu tên tệp.
fields: các giá trị đơn giản của bản ghi được dùng để tạo tài liệu: văn bản, số, ngày và tương tự, đúng như tài liệu in ra. Bản ghi liên kết, danh sách và tệp đính kèm không được gửi.
warnings: chỉ có khi quá trình tạo có cảnh báo, ví dụ một hình ảnh không tải được (ghi theo tên trường và máy chủ của URL).

Nếu bạn đặt Bearer token, token sẽ được gửi qua header Authorization.

Trường hợp sử dụng

Kích hoạt các automation Lark tiếp theo
Gửi thông báo Lark Messenger qua bot
Tích hợp với quy trình Lark Approval: để tạo tài liệu khi một yêu cầu được phê duyệt, xem Tài liệu phê duyệt, cách này không cần automation
Lưu trữ tài liệu vào Lark Docs hoặc Drive