Bắt đầu nhanh với API

Trang này đưa bạn từ một tài khoản trống đến một tài liệu hoàn chỉnh do chính mã của bạn tạo ra: một tài khoản, một mẫu, một khóa và một yêu cầu HTTP. Mọi trường, câu trả lời và lỗi đều được mô tả trong tài liệu tham khảo API tài liệu.

Gói dịch vụ

API tài liệu dùng được với mọi gói, kể cả gói Miễn phí. Mỗi tài liệu nó tạo ra là một tài liệu tự động: với gói Pro thì không giới hạn; nếu không, tài liệu được trừ vào số tài liệu tự động của các suất Business (20.000 mỗi năm cho mỗi suất), sau đó vào 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. Tài liệu được tính khi hoàn tất, nên tài liệu thất bại không tốn gì. Với gói Miễn phí, tài liệu mang dòng chân trang “Generated with AutomaDoc” trừ khi công ty bạn có một gói tài liệu đã mua. Xem Gói dịch vụ, suất và gói tài liệu.

1. Một tài khoản

Mọi tài khoản AutomaDoc đều gọi được API: một tổ chức Microsoft 365, một tên miền Google Workspace, một không gian làm việc Lark hoặc một tài khoản email. Nếu bạn chỉ cần API, hãy đăng ký bằng một địa chỉ email: xem Tài khoản chỉ dùng API.

Bước 2 và 3 diễn ra trong Cổng thông tin công ty tại company.automadoc.cc và cần một quản trị viên của tài khoản (trong không gian làm việc Lark, là quản trị viên ứng dụng Lark).

2. Một mẫu và ID của mẫu

Mẫu là một tệp Word, Excel hoặc PowerPoint có các biến giữ chỗ ở những chỗ dữ liệu của bạn được điền vào. Với trang này, hãy lấy một hóa đơn Word có:

• {Invoice_No} và {Customer} trong văn bản,
• một hàng bảng có ô đầu tiên bắt đầu bằng {#Items}{Product}, tiếp theo là {Qty}, và ô cuối cùng kết thúc bằng {Price}{/Items}: hàng này lặp lại một lần cho mỗi mục,
• {Total | currency:"USD"} bên dưới bảng.

Cú pháp đầy đủ có trong Cú pháp mẫu.

Để thêm mẫu trong Cổng thông tin công ty:

1. Mở Mẫu và nhấp Mẫu API mới.
2. Nhập tên và nhấp Tạo mẫu API.
3. Mở menu ở cuối hàng của mẫu và chọn Tải tệp lên. Tệp được kiểm tra khi tải lên; nếu có vấn đề, trang sẽ báo và bạn tải lên một tệp đã sửa.
4. Trong cùng menu đó, chọn Sao chép ID mẫu.

API điền được mọi mẫu của công ty bạn, không chỉ mẫu API: mẫu tạo trong phần bổ trợ Excel, từ một Google Sheet hoặc trong tiện ích mở rộng Lark Base đều hoạt động như nhau, và hàng của nó trên trang Mẫu cũng có Sao chép ID mẫu. Khi bạn đăng nhập vào cổng thông tin bằng Lark, hãy tạo mẫu trong tiện ích mở rộng Base; thẻ API tài liệu của tiện ích, trên tab Mẫu, cũng hiển thị endpoint có sẵn ID trong đó.

3. Một khóa API của công ty

1. Trong Cổng thông tin công ty, mở Công ty → Khóa API và nhấp Khóa API mới.
2. Điền Tên khóa bằng tên hệ thống sẽ dùng khóa, ví dụ ERP, rồi nhấp Tạo khóa.
3. Sao chép khóa. Khóa bắt đầu bằng amk_ và chỉ hiển thị một lần.

Khóa công ty mở được mọi mẫu của công ty bạn. Hãy cất giữ nó như mật khẩu. Thu hồi trên cùng trang sẽ vô hiệu hóa khóa ngay lập tức.

Một mẫu Lark Base cũng có khóa riêng, trên thẻ API tài liệu của nó, chỉ mở được mẫu đó.

4. Gửi yêu cầu đầu tiên

Gửi dữ liệu của mẫu dưới dạng JSON tới POST /api/v1/templates/{templateId}/documents, với khóa trong header X-Webhook-API-Key:

curl -X POST 'https://api.automadoc.cc/api/v1/templates/TEMPLATE_ID/documents?wait=20' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Invoice_No": "INV-2026-001",
      "Customer": "Acme Corp",
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Total": 1540
    },
    "format": "pdf"
  }'

• data là bản ghi. Mỗi khóa điền vào biến giữ chỗ cùng tên. Khoảng trắng, dấu chấm và các ký hiệu khác trong khóa trở thành _, nên "Invoice No." điền vào {Invoice_No_}; có phân biệt chữ hoa chữ thường.
• format là tùy chọn: "pdf", "png" (trang đầu tiên dưới dạng ảnh) hoặc "native" (loại tệp gốc của mẫu). Nếu bỏ trống, cài đặt của mẫu sẽ quyết định.
• ?wait=20 giữ câu trả lời tối đa 20 giây (nhiều nhất 25) trong khi tài liệu được tạo, nên thường chỉ cần một yêu cầu.

filename, recordId và mode cũng là tùy chọn; xem Tạo tài liệu.

5. Đọc câu trả lời và lấy tệp

Khi tài liệu hoàn tất trong thời gian chờ, câu trả lời là 200 OK:

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "templateId": "9b1c…",
  "status": "completed",
  "statusUrl": "https://api.automadoc.cc/api/v1/documents/5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "createdAt": 1791878400000,
  "filename": "Invoice-INV-2026-001.pdf",
  "downloadUrl": "https://api.automadoc.cc/api/generations/…/download?expires=…&signature=…",
  "downloadUrlExpiresAt": 1792137600000
}

Khi tài liệu vẫn đang được tạo, câu trả lời là 202 Accepted với "status": "processing" và chưa có liên kết. Hãy đọc statusUrl bằng cùng khóa vài giây một lần (tối đa 60 lần đọc mỗi phút cho mỗi tài liệu) cho đến khi status là completed hoặc failed:

curl 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

• completed: downloadUrl mở tệp mà không cần khóa. Liên kết dùng được trong thời gian công ty bạn lưu giữ tài liệu đã tạo, và mỗi lần đọc trạng thái sẽ cho một liên kết mới.
• failed: error cho biết lý do, ví dụ một vòng lặp không bao giờ được đóng.
• warnings, nếu có, liệt kê những gì đã bị bỏ qua, như một hình ảnh có URL không tải được, hoặc các biến giữ chỗ mà dữ liệu của bạn không có giá trị.

Để lấy chính tệp bằng khóa thay vì liên kết:

curl -o invoice.pdf 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID/file' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

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

Mỗi lần từ chối đều có code và error bằng tiếng Anh. Những lỗi bạn hay gặp đầu tiên:

Trạng thái	code	Cách xử lý
401	API_KEY_MISSING	Thêm header X-Webhook-API-Key
403	API_KEY_INVALID	Kiểm tra khóa và ID mẫu: ID sai cũng nhận câu trả lời này
409	TEMPLATE_FILE_MISSING	Tải lên tệp của mẫu
400	TEMPLATE_VALIDATION_ERRORS	Sửa tệp mẫu; validationErrors liệt kê các vấn đề
403	QUOTA_EXCEEDED	Đã hết tài liệu trong tháng này; hãy mua gói tài liệu hoặc suất
429	RATE_LIMITED	Vượt 60 yêu cầu mỗi phút cho một mẫu, hoặc 600 tài liệu mỗi phút cho công ty bạn; hãy chờ rồi thử lại

Danh sách đầy đủ có trong Lỗi.

Ví dụ tương tự bằng Node.js

Node.js 18 trở lên có sẵn fetch. Lưu đoạn này thành quickstart.mjs và chạy bằng AUTOMADOC_KEY=amk_… node quickstart.mjs:

import { writeFile } from 'node:fs/promises'

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

async function makeDocument(templateId, data) {
  const res = await fetch(`${API}/api/v1/templates/${templateId}/documents?wait=20`, {
    method: 'POST',
    headers: { 'X-Webhook-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ data, format: 'pdf' }),
  })
  let doc = await res.json()
  if (!res.ok) throw new Error(`${doc.code}: ${doc.error}`)

  // Not finished within the wait: read the status until it is.
  while (doc.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 3000))
    const poll = await fetch(doc.statusUrl, { headers: { 'X-Webhook-API-Key': KEY } })
    doc = await poll.json()
    if (!poll.ok) throw new Error(`${doc.code}: ${doc.error}`)
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc
}

const doc = await makeDocument(TEMPLATE_ID, {
  Invoice_No: 'INV-2026-001',
  Customer: 'Acme Corp',
  Items: [
    { Product: 'Consulting', Qty: 10, Price: 120 },
    { Product: 'Travel', Qty: 1, Price: 340 },
  ],
  Total: 1540,
})

const file = await fetch(doc.downloadUrl)
await writeFile(doc.filename, Buffer.from(await file.arrayBuffer()))
console.log(`Saved ${doc.filename}`, doc.warnings ?? '')

Bước tiếp theo

• Vòng lặp. Một danh sách đối tượng điền vào vòng lặp {#Items}…{/Items}, mỗi đối tượng một hàng hoặc một khối; vòng lặp có thể lọc, sắp xếp và giới hạn số hàng. Xem Vòng lặp.
• Hình ảnh. Đặt Alt Text {Logo} cho một hình ảnh trong mẫu và gửi "Logo": "https://…". URL phải là địa chỉ http(s) công khai; ở bất kỳ chỗ nào khác trong mẫu, URL chỉ là văn bản. Xem Hình ảnh động và Dữ liệu của bạn điền vào mẫu như thế nào.
• PDF, ảnh hoặc tệp Office. "format" chọn đầu ra cho từng yêu cầu; cài đặt riêng của mẫu được áp dụng khi bạn bỏ trống.
• Nhiều tài liệu trong một yêu cầu. Gửi data dưới dạng danh sách tối đa 50 đối tượng để nhận mỗi phần tử một tài liệu. Xem Nhiều tài liệu cùng lúc.
• Một tài liệu từ nhiều bản ghi. Mẫu được thiết lập để tạo một danh sách, mỗi bản ghi một trang hoặc nhãn sẽ biến một danh sách tối đa 500 phần tử thành một tài liệu, tính là một. Xem Một tài liệu từ nhiều bản ghi và Một tài liệu từ tất cả phần tử.
• Chữ ký điện tử. Với mẫu Lark Base có trường chữ ký, khối sign gửi tài liệu đi ký ngay khi tài liệu được tạo. Xem Gửi tài liệu để ký.
• Hoàn toàn không cần viết mã. Trong Microsoft 365, trình kết nối Power Automate gửi cùng yêu cầu này từ một luồng.