📖 API Documentation

Hướng dẫn sử dụng API DocFlow — tạo template, mapping, và xuất PDF.

Tổng Quan

DocFlow API cho phép bạn tạo template từ file DOCX, thiết kế các trường dữ liệu (mapping), và render ra file DOCX/PDF hoàn chỉnh. Tất cả qua REST API.

Base URL:
Swagger UI: /docs

Xác Thực (Authentication)

API hỗ trợ 2 phương thức xác thực:

1. API Key (cho hệ thống bên ngoài)

Thêm header X-API-Key vào mọi request:

curl -H "X-API-Key: Test_apikey_doc_automation_2026" \
     https://docflow.devhub.ai.vn/api/v1/designer/

2. JWT Token (cho frontend / user)

Đăng nhập lấy token, rồi dùng Authorization: Bearer <token>:

# Đăng ký
curl -X POST /api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Đăng nhập
curl -X POST /api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Response → {"access_token": "eyJ..."}

# Dùng token
curl -H "Authorization: Bearer eyJ..." \
     /api/v1/designer/

Quick Start (5 Bước)

Quy trình: Upload DOCX → Xem cấu trúc → Tạo mappings → Publish → Render PDF 
# Bước 1: Upload file DOCX
curl -X POST /api/v1/designer/raw \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@contract.docx"
# → {"template_id": "abc-123..."}

# Bước 2: Xem cấu trúc
curl /api/v1/designer/abc-123/structure

# Bước 3: Tạo mapping (ví dụ: text "Nguyễn Văn A" → biến customer_name)
curl -X POST /api/v1/designer/abc-123/mappings \
  -H "Content-Type: application/json" \
  -d '{"mapping_type":"paragraph","paragraph_index":2,
       "original_text":"Nguyễn Văn A","label":"customer_name"}'

# Bước 4: Publish template
curl -X POST /api/v1/designer/abc-123/publish

# Bước 5: Render với data mới
curl -X POST /api/v1/designer/abc-123/render \
  -H "Content-Type: application/json" \
  -d '{"customer_name":"Trần Thị B","items":[
       {"stt":"1","description":"Dịch vụ","amount":"5.000.000"}]}'
# → {"document_id":"xyz","docx_path":"...","pdf_path":"...","status":"completed"}

📋 Templates Hiện Tại

Các template đã tạo trong hệ thống. Click vào ID để xem schema và code mẫu.

Đang tải templates...

Upload DOCX

POST/api/v1/designer/raw

Upload file DOCX gốc để bắt đầu thiết kế template.

Param Loại Mô tả
file File required File .docx cần upload 
curl -X POST /api/v1/designer/raw \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@hopdong.docx"

Danh Sách Templates

GET/api/v1/designer/

curl /api/v1/designer/ -H "X-API-Key: YOUR_API_KEY"

Xem Cấu Trúc Document

GET/api/v1/designer/{template_id}/structure

Trả về danh sách paragraphs và tables với nội dung text, dùng để xác định vị trí mapping.

curl /api/v1/designer/{template_id}/structure \
  -H "X-API-Key: YOUR_API_KEY"

Tạo Mapping

POST/api/v1/designer/{template_id}/mappings

3 loại mapping:

Paragraph Mapping

Thay thế text trong đoạn văn bản bằng biến.

Field Type Mô tả
mapping_type string "paragraph"
paragraph_index int req Thứ tự paragraph (0-based)
original_text string req Text gốc cần thay thế
label string req Tên biến (lowercase, underscores)
field_type string opt string | number | date | currency
required bool opt Bắt buộc khi render (default: true)

Table Cell Mapping

Thay thế nội dung 1 ô trong bảng.

{
  "mapping_type": "table_cell",
  "table_index": 0,
  "row_index": 1,
  "col_index": 2,
  "original_text": "5.000.000",
  "label": "amount",
  "field_type": "currency"
}

Table Loop (Array / Bảng động)

POST/api/v1/designer/{template_id}/mappings

Tạo bảng dữ liệu động — hệ thống tự nhân bản row theo số lượng phần tử trong mảng.

Hỗ trợ multi-group: Bạn có thể tạo nhiều loop group trên cùng 1 bảng. Ví dụ: cột 0-2 → items1, cột 3-5 → items2. 
{
  "mapping_type": "table_loop",
  "table_index": 0,
  "data_row_index": 1,
  "loop_variable": "items",
  "cell_labels": [
    {"col_index": 0, "label": "stt"},
    {"col_index": 1, "label": "description"},
    {"col_index": 2, "label": "amount"}
  ]
}

Publish Template

POST/api/v1/designer/{template_id}/publish

Khóa template và apply mappings. Sau khi publish, template sẵn sàng để render.

Lưu ý: Sau khi publish, không thể thêm/sửa mappings. Hãy chắc chắn đã thiết kế đầy đủ. 
curl -X POST /api/v1/designer/{template_id}/publish \
  -H "X-API-Key: YOUR_API_KEY"

Schema (Xem form dữ liệu)

GET/api/v1/designer/{template_id}/schema

Trả về danh sách các trường cần điền khi render. Dùng để tạo form tự động.

curl /api/v1/designer/{template_id}/schema \
  -H "X-API-Key: YOUR_API_KEY"

# Response example:
{
  "fields": [
    {"name": "customer_name", "type": "string", "required": true},
    {"name": "items", "type": "array", "sub_fields": [
      {"name": "stt"}, {"name": "description"}, {"name": "amount"}
    ]}
  ]
}

Render Document

POST/api/v1/designer/{template_id}/render

Gửi dữ liệu → nhận file DOCX + PDF.

Field Type Mô tả
{field_name} string Giá trị cho mỗi trường (theo schema)
{array_field} array Mảng object cho table loop 
curl -X POST /api/v1/designer/{template_id}/render \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Trần Thị B",
    "address": "456 Nguyễn Huệ, Q3",
    "items": [
      {"stt": "1", "description": "Tư vấn", "amount": "5.000.000"},
      {"stt": "2", "description": "Triển khai", "amount": "10.000.000"}
    ]
  }'

# Response:
{
  "document_id": "xyz-789",
  "docx_path": "storage/rendered/xyz-789.docx",
  "pdf_path": "storage/pdfs/xyz-789.pdf",
  "status": "completed"
}

Download File

GET/api/v1/files/download/{filename}

Download file DOCX hoặc PDF đã render.

# Download DOCX
curl -O /api/v1/files/download/xyz-789.docx \
  -H "X-API-Key: YOUR_API_KEY"

# Download PDF
curl -O /api/v1/files/download/xyz-789.pdf \
  -H "X-API-Key: YOUR_API_KEY"