Điền mẫu Word API

Điền mẫu Word .docx có {thẻ}, lặp dòng bảng, điều kiện từ JSON; trộn nhiều bản ghi thành file zip. Định dạng tiền VND, số tiền bằng chữ, ngày tháng.

POSThttps://apibox.io.vn/v1/docx-template

Tải lên file Word có các thẻ và gửi dữ liệu JSON: {ho_ten} chèn giá trị (dùng được đường dẫn như {ben_a.ten}), {#items}…{/items} lặp nội dung cho từng phần tử của mảng, {#co_bao_hiem}…{/co_bao_hiem} chỉ hiện khi giá trị đúng và {^co_bao_hiem}…{/co_bao_hiem} khi sai hoặc rỗng. Vòng lặp đặt trong dòng của bảng sẽ lặp dòng đó (dòng hàng hóa, điều khoản), vòng lặp qua nhiều đoạn sẽ lặp các đoạn, vòng lặp trong một đoạn lặp phần chữ tại chỗ. {$index} để đánh số thứ tự.

Bộ lọc định dạng theo kiểu Việt Nam: {luong|money} ra 15.500.000, {luong|words} ra "Mười lăm triệu năm trăm nghìn đồng", {ngay|date} ra 11/11/2026, {ngay|date_vi} ra "ngày 11 tháng 11 năm 2026", cùng upper, lower, trim và default:…. Thẻ bị Word tách thành nhiều đoạn chữ khi gõ (do kiểm tra chính tả, đổi định dạng) được ghép lại trước, nên vẫn chạy đúng như khi gõ; định dạng của ký tự đầu thẻ được giữ. Đầu trang, chân trang, chú thích cũng được điền; dấu {{ten}} được tự nhận ra.

Gửi rows (mảng) thay cho data để trộn nhiều văn bản một lần: kết quả là file zip, tên file theo filename như HD_{so_hd}. action=tags liệt kê các thẻ trong mẫu. Kết quả là .docx (không chuyển sang PDF); file được xử lý trong bộ nhớ, không lưu lại.

Tham số

TênVị tríKiểuBắt buộcMặc định
templatebodyfilecóFile mẫu .docx (multipart template hoặc file, hoặc template_base64).
databodyobjectkhôngDữ liệu cho một văn bản (đối tượng JSON).
rowsbodyarraykhôngTrộn hàng loạt: mảng đối tượng, trả file zip (tối đa 500).
filenamebodystringkhôngdocumentTên file kết quả, dùng được thẻ: HD_{so_hd}.
outputbody|querystringkhôngdocxdocx (file) hoặc json (xem trước nội dung, thẻ, trường thiếu, base64).
actionbody|querystringkhôngtags: chỉ liệt kê các thẻ của mẫu.
delimitersbody|querystringkhôngsingle { } hoặc double {{ }} (tự nhận).

Ví dụ

curl -X POST "https://apibox.io.vn/v1/docx-template" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "0=@./my-file"

Kết quả trả về

{
  "filename": "document.docx",
  "delimiters": "{ }",
  "tags": [
    {
      "name": "so_hd",
      "kind": "variable"
    },
    {
      "name": "ho_ten",
      "kind": "variable",
      "filters": [
        "upper"
      ]
    },
    {
      "name": "luong",
      "kind": "variable",
      "filters": [
        "money"
      ]
    },
    {
      "name": "luong",
      "kind": "variable",
      "filters": [
        "words"
      ]
    },
    {
      "name": "items",
      "kind": "section"
    },
    {
      "name": "$index",
      "kind": "variable"
    },
    {
      "name": "ten",
      "kind": "variable"
    },
    {
      "name": "tien",
      "kind": "variable",
      "filters": [
        "money"
      ]
    }
  ],
  "missing_fields": [],
  "text": "HỢP ĐỒNG LAO ĐỘNG số 12/2026/HĐLĐ\nBên B: Ông/Bà NGUYỄN VĂN AN, lương 15.500.000 đồng (Mười lăm triệu năm trăm nghìn đồng)\nSTT\nNội dung\nSố tiền\n1\nLương cơ bản\n12.000.000",
  "docx_base64": "UEsDBBQAAAgIAAAAAACY9I3b6wAAAM4BAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtbH2R…",
  "bytes": 1190
}

Ứng dụng

  • Sinh hợp đồng lao động, hợp đồng mua bán từ dữ liệu HR / CRM
  • Trộn giấy chứng nhận, giấy mời, thông báo thành file zip
  • Lập báo giá, biên bản bàn giao có bảng hàng hóa
  • Điền các biểu mẫu hành chính lưu dạng mẫu Word

Hỏi đáp

Thẻ không được thay giá trị là vì sao?

Kiểm tra bằng action=tags: thẻ phải dùng ngoặc nhọn thường {…} và không xuống dòng ở giữa. Thẻ bị tách đoạn được xử lý tự động; giá trị thiếu được báo trong missing_fields (hoặc header x-missing-fields).

Làm sao lặp một dòng của bảng?

Đặt {#items} ở ô đầu và {/items} ở ô cuối của dòng (hoặc của một dòng phía dưới): các dòng đó được nhân lên theo từng phần tử, {$index} là số thứ tự.

Có xuất ra PDF được không?

Không, kết quả là file .docx. Hãy chuyển bằng Word / LibreOffice, hoặc dùng /v1/md-pdf cho văn bản soạn bằng Markdown.

API liên quan

Bắt đầu với 1.000 request miễn phí mỗi tháng. Nhận API key miễn phí →