Đ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.
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ên | Vị trí | Kiểu | Bắt buộc | Mặc định | |
|---|---|---|---|---|---|
template | body | file | có | File mẫu .docx (multipart template hoặc file, hoặc template_base64). | |
data | body | object | không | Dữ liệu cho một văn bản (đối tượng JSON). | |
rows | body | array | không | Trộn hàng loạt: mảng đối tượng, trả file zip (tối đa 500). | |
filename | body | string | không | document | Tên file kết quả, dùng được thẻ: HD_{so_hd}. |
output | body|query | string | không | docx | docx (file) hoặc json (xem trước nội dung, thẻ, trường thiếu, base64). |
action | body|query | string | không | tags: chỉ liệt kê các thẻ của mẫu. | |
delimiters | body|query | string | không | single { } 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"const form = new FormData();
form.append('0', fileInput.files[0]);
const res = await fetch('https://apibox.io.vn/v1/docx-template', {
method: 'POST',
headers: { Authorization: 'Bearer YOUR_API_KEY' },
body: form,
});
console.log(await res.json());import requests
res = requests.post(
"https://apibox.io.vn/v1/docx-template",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"0": open("my-file", "rb")},
timeout=30,
)
print(res.json())<?php
$ch = curl_init('https://apibox.io.vn/v1/docx-template');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
CURLOPT_POSTFIELDS => ['0' => new CURLFile('my-file')],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));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
Metadata ảnh & EXIF
Đọc kích thước, định dạng, thông tin EXIF máy ảnh, thông số chụp và vị trí GPS của ảnh JPEG, PNG, WebP, HEIC, AVIF, GIF… – upload file hoặc qua URL.
PDFMetadata PDF
Đọc metadata file PDF: số trang, tiêu đề, tác giả, phần mềm tạo, ngày tạo, phiên bản PDF, mã hoá, số trường form và khổ giấy từng trang (A4, Letter…).
PDF₫Tạo PDF báo giá, phiếu thu
Tạo PDF báo giá, phiếu thu, đơn đặt hàng, hoá đơn bán hàng gọn đẹp từ JSON: tiếng Việt chuẩn, thuế GTGT, số tiền bằng chữ và mã VietQR để thanh toán.