API 使用手冊

Jason Tools 文件工具箱對外提供 RESTful API，所有工具皆有對應 endpoint，可整合到自動化流程、自家系統或排程工作。

基本原則：API 預設可不認證（與 web UI 同步開放）；需要鎖時管理員到 admin 「API Token」頁開啟 enforce 模式並核發 bearer token。

不啟用認證（預設）

新安裝預設不啟用認證，所有 /api/* 直接可用，無需 token。

啟用 API token

管理員到 admin → API Token：

1. 點「核發新 token」→ 輸入用途名稱（例 gitlab-ci）→ 拿到 64 字 hex token（只顯示一次，存好）
2. 勾選「Enforce — 沒帶 token 一律拒絕」並儲存

之後所有 /api/* 必須帶以下任一形式：

Authorization: Bearer 64char-hex-token-here

或 query string：

GET /api/jobs/abc123?token=64char-hex-token-here

未帶或 token 無效 → 401 Unauthorized JSON：

{"ok": false, "detail": "需要有效的 API token（Authorization: Bearer ...）"}

Token 透過 admin / jtdt CLI 管理，與 web 認證 (jtdt-admin / LDAP / AD) 完全獨立。

2. 通用約定

以下每個端點都附 curl 範例。回傳檔案的端點用 --output 檔名 存檔；回傳 JSON 的端點可接 | jq 美化。

文書轉 PDF

把 Word / Excel / PowerPoint / ODF 轉成 PDF（走 OxOffice / LibreOffice 引擎）。

POST /api/convert-to-pdf

curl -X POST http://localhost:8765/api/convert-to-pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@報告.docx" \
  --output 報告.pdf

回應：PDF 二進位（application/pdf）。失敗 4xx + JSON {"detail": "..."}。

圖片轉 PDF

把一張或多張圖片合併成單一 PDF。

POST /tools/image-to-pdf/api/image-to-pdf

curl -X POST http://localhost:8765/tools/image-to-pdf/api/image-to-pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@p1.jpg" -F "files=@p2.png" \
  -F "page_size=A4" -F "margin_mm=5" \
  --output album.pdf

回應：PDF 二進位。

PDF 轉圖片

把 PDF 每頁轉成 PNG（多頁自動打包 ZIP）。

POST /tools/pdf-to-image/convert

curl -X POST http://localhost:8765/tools/pdf-to-image/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" -F "dpi=200" \
  --output pages.zip

回應：單頁回 PNG，多頁回 ZIP。

PDF 轉 Office

把 PDF 反轉成 Word（.docx）或 OpenDocument（.odt）。走 job 模式回 job_id。

POST /tools/pdf-to-office/convert

# 預設引擎 pdf2docx-refine
curl -X POST http://localhost:8765/tools/pdf-to-office/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@form.pdf" -F "output_format=docx" \
  | jq
# → {"job_id": "...", "download_url": "/api/jobs/.../download"}

# 改用自家 jtdt-reform 引擎
curl -X POST http://localhost:8765/tools/pdf-to-office/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@form.pdf" -F "output_format=odt" -F "engine=jtdt-reform" \
  | jq

回應：{"job_id": "...", "download_url": "..."}；之後用第 10 章的 job API 輪詢 + 取結果。

取得轉換前後對照縮圖：job 完成後，GET /api/jobs/{job_id} 的 meta.preview 內含 page_indices（要預覽的 0-based 頁碼清單，≤ 6 頁全取 / > 6 頁取前 2 + 中 2 + 後 2）、 orig_pages、result_pages、orig_chars、result_chars。逐頁縮圖用：

GET /tools/pdf-to-office/preview/{job_id}/orig/{page}     # 轉換前（原 PDF）
GET /tools/pdf-to-office/preview/{job_id}/result/{page}   # 轉換後（docx/odt 渲染）

page 為 1-based 頁碼（對應 page_indices 元素 +1），回傳 image/png。

# 完成後讀 preview 頁碼清單
curl -s http://localhost:8765/api/jobs/$JOB \
  -H "Authorization: Bearer YOUR_TOKEN" | jq '.meta.preview'
# 取第 1 頁的前 / 後對照縮圖
curl -s http://localhost:8765/tools/pdf-to-office/preview/$JOB/orig/1 \
  -H "Authorization: Bearer YOUR_TOKEN" --output before_p1.png
curl -s http://localhost:8765/tools/pdf-to-office/preview/$JOB/result/1 \
  -H "Authorization: Bearer YOUR_TOKEN" --output after_p1.png

PDF 合併

把多份 PDF 依上傳順序合併為一份。

POST /tools/pdf-merge/api/pdf-merge

curl -X POST http://localhost:8765/tools/pdf-merge/api/pdf-merge \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@a.pdf" -F "files=@b.pdf" -F "files=@c.pdf" \
  --output merged.pdf

回應：合併後的 PDF。

PDF 分割

依頁數 / 範圍切分 PDF。

POST /tools/pdf-split/api/pdf-split

curl -X POST http://localhost:8765/tools/pdf-split/api/pdf-split \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@big.pdf" -F "mode=ranges" -F "ranges=1-3,8-10" \
  --output parts.zip

回應：切出的 PDF（多份打包 ZIP）。

PDF 頁面處理

刪除 / 抽取 / 重排頁面。

POST /tools/pdf-pages/api/pdf-pages

curl -X POST http://localhost:8765/tools/pdf-pages/api/pdf-pages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" -F "mode=keep" -F "spec=1,3,5-8" \
  --output picked.pdf

回應：處理後的 PDF。

PDF 旋轉

旋轉指定頁面。

POST /tools/pdf-rotate/api/pdf-rotate

curl -X POST http://localhost:8765/tools/pdf-rotate/api/pdf-rotate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@scan.pdf" -F "angle=90" -F "pages=1-4" \
  --output rotated.pdf

回應：旋轉後的 PDF。

PDF 加頁碼

在頁面指定位置加頁碼。

POST /tools/pdf-pageno/api/pdf-pageno

curl -X POST http://localhost:8765/tools/pdf-pageno/api/pdf-pageno \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@report.pdf" -F "position=bottom-center" \
  -F "fmt=第 {n} / {total} 頁" -F "start=1" \
  --output numbered.pdf

回應：加完頁碼的 PDF。

PDF 多頁合一（N-up）

把多頁縮排到單頁（2-up / 4-up 等）。

POST /tools/pdf-nup/api/pdf-nup

curl -X POST http://localhost:8765/tools/pdf-nup/api/pdf-nup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@slides.pdf" -F "cols=2" -F "rows=2" \
  -F "paper=A4" -F "orientation=landscape" \
  --output 4up.pdf

回應：N-up 後的 PDF。

PDF 壓縮

縮小 PDF 檔案大小。

POST /tools/pdf-compress/api/pdf-compress

curl -X POST http://localhost:8765/tools/pdf-compress/api/pdf-compress \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@large.pdf" -F "preset=ebook" \
  --output small.pdf

回應：壓縮後的 PDF。

掃描拼合

把多張掃描（如證件正、反面）中「有內容的區塊」自動偵測出來、保留原彩色，依其在原掃描中的相對位置合成到同一張 A4 白底 PDF。重疊時保留原位置不自動重排（需拖曳微調請改用網頁介面）。

POST /tools/scan-merge/api/scan-merge

curl -X POST http://localhost:8765/tools/scan-merge/api/scan-merge \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@id-front.jpg" -F "files=@id-back.jpg" \
  -F "whiten=true" \
  --output id-merged.pdf

回應：單張 A4 白底 PDF 二進位。

PDF 文字擷取

抽出 PDF 內所有文字（自動處理壞 CMap / OCR 雙層）。

POST /tools/pdf-extract-text/api/pdf-extract-text

curl -X POST http://localhost:8765/tools/pdf-extract-text/api/pdf-extract-text \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" | jq

回應 JSON：逐頁文字 + 全文。

PDF 圖片擷取

抽出 PDF 內嵌的所有圖片。

POST /tools/pdf-extract-images/api/pdf-extract-images

curl -X POST http://localhost:8765/tools/pdf-extract-images/api/pdf-extract-images \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  --output images.zip

回應：圖片打包 ZIP。

PDF 附件擷取

列出 / 抽出 PDF 內嵌附件（embedded files）。

POST /tools/pdf-attachments/api/pdf-attachments

curl -X POST http://localhost:8765/tools/pdf-attachments/api/pdf-attachments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@with_attachments.pdf" \
  --output attachments.zip

回應：附件清單 + 內容（ZIP）。

PDF 中繼資料

讀取 / 清除 PDF metadata、XMP、書籤、註解、表單。

POST /tools/pdf-metadata/api/pdf-metadata

curl -X POST http://localhost:8765/tools/pdf-metadata/api/pdf-metadata \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" -F "clear_info=true" -F "clear_xmp=true" \
  --output cleaned.pdf

回應：未帶 clear_* 旗標 → 回 metadata JSON；帶旗標 → 回清除後的 PDF。

PDF 字數統計

統計頁數、字數、詞數、閱讀時間與高頻詞。

POST /tools/pdf-wordcount/api/pdf-wordcount

curl -X POST http://localhost:8765/tools/pdf-wordcount/api/pdf-wordcount \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" | jq

回應 JSON（節錄）：

{
  "filename": "document.pdf",
  "page_count": 12,
  "char_count": 18342,
  "word_count": 3521,
  "estimated_reading_minutes": 12.5,
  "per_page_chars": [/* ... */],
  "top_words_zh2": [/* ... */], "top_words_en": [/* ... */]
}

PDF OCR

對掃描 PDF 做文字辨識，加上可選取的文字層。

POST /tools/pdf-ocr/api/pdf-ocr

curl -X POST http://localhost:8765/tools/pdf-ocr/api/pdf-ocr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@scan.pdf" -F "lang=chi_tra+eng" -F "dpi=300" \
  --output ocr.pdf

回應：加上文字層的 PDF。

外部 GPU OCR Server

管理員可在 admin/ocr-langs → 外部 GPU 識別伺服器 部署 jt-ocr-server 到 GPU 主機，jtdt 透過 HTTP 呼叫遠端 EasyOCR，速度比 CPU 快 10× 以上。設定相關 admin endpoints：

GET  /admin/ocr-langs/deploy/install.sh        # 下載安裝腳本
GET  /admin/ocr-langs/deploy/uninstall.sh      # 下載解除安裝腳本
GET  /admin/api/ocr-langs/external/status      # 讀取目前設定
POST /admin/api/ocr-langs/external/save        # 儲存 URL / Token / Timeout / 啟用
POST /admin/api/ocr-langs/external/test        # 測試連接

啟用後 /tools/pdf-ocr/* 與內部呼叫 EasyOCR 的工具會自動走遠端 GPU，連線失敗自動退回本機。jt-ocr-server 自身對外端點：

GET  /healthz        # 不需 token,回 GPU/VRAM 資訊
GET  /version        # 需 Bearer token
POST /ocr            # 需 Bearer token,multipart image + langs form

PDF 註解整理

列出 PDF 所有註解（頁碼、類型、作者、內容、座標、時間）。

POST /tools/pdf-annotations/api/pdf-annotations

curl -X POST http://localhost:8765/tools/pdf-annotations/api/pdf-annotations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@reviewed.pdf" | jq

回應 JSON：每筆註解的詳細資訊。

PDF 註解清除

移除 PDF 註解（可依類型 / 作者篩選）。

POST /tools/pdf-annotations-strip/api/pdf-annotations-strip

curl -X POST http://localhost:8765/tools/pdf-annotations-strip/api/pdf-annotations-strip \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@reviewed.pdf" -F "types=Highlight,Text" \
  --output clean.pdf

回應：清除後的 PDF。

PDF 註解平面化

把註解燒進頁面內容流（收件方無法移除；表單欄位仍可填）。

POST /tools/pdf-annotations-flatten/api/pdf-annotations-flatten

curl -X POST http://localhost:8765/tools/pdf-annotations-flatten/api/pdf-annotations-flatten \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@annotated.pdf" \
  --output flattened.pdf

回應：平面化後的 PDF。

PDF 隱藏內容掃描

掃描 PDF 內可能洩漏的隱藏內容（中繼資料、被遮蓋文字、圖層、附件等）。

POST /tools/pdf-hidden-scan/api/pdf-hidden-scan

curl -X POST http://localhost:8765/tools/pdf-hidden-scan/api/pdf-hidden-scan \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" | jq

回應 JSON：各類隱藏內容的偵測結果。

PDF 表單填寫

自動辨識表單欄位並填入公司主檔資料。

POST /tools/pdf-fill/api/pdf-fill

curl -X POST http://localhost:8765/tools/pdf-fill/api/pdf-fill \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@vendor_form.pdf" -F "company_id=acme" \
  --output filled.pdf

回應：填好的 PDF。

PDF 用印 / 簽名

在 PDF 上疊加印章 / 簽名圖。

POST /tools/pdf-stamp/api/pdf-stamp

curl -X POST http://localhost:8765/tools/pdf-stamp/api/pdf-stamp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@contract.pdf" -F "stamp_image=@chop.png" \
  -F "x_mm=150" -F "y_mm=30" -F "width_mm=30" -F "height_mm=30" \
  -F "pages_json=[0,2]" \
  --output stamped.pdf

回應：蓋章後的 PDF。

PDF 浮水印

加文字浮水印。

POST /tools/pdf-watermark/api/pdf-watermark

curl -X POST http://localhost:8765/tools/pdf-watermark/api/pdf-watermark \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" -F "text=機密" \
  -F "opacity=0.12" -F "mode=tile" \
  --output watermarked.pdf

回應：加浮水印後的 PDF。

PDF 編輯器

依 overlay JSON 模型把文字 / 圖片 / 形狀 / 遮罩燒進 PDF（含真刪 redaction）。

POST /tools/pdf-editor/api/pdf-editor

curl -X POST http://localhost:8765/tools/pdf-editor/api/pdf-editor \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'model={"version":1,"pages":[{"page":0,"objects":[{"id":"o1","type":"text","x":100,"y":200,"w":120,"h":20,"text":"已蓋章","font":"Noto Sans TC","size":14,"color":"#cc0000"}]}]}' \
  --output edited.pdf

回應：套用 overlay 後的 PDF。模型格式詳見 web UI 的 pdf-editor。

PDF 加密

加使用者 / 擁有者密碼並設定權限。

POST /tools/pdf-encrypt/api/pdf-encrypt

curl -X POST http://localhost:8765/tools/pdf-encrypt/api/pdf-encrypt \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" -F "user_pw=open123" \
  -F "owner_pw=admin456" -F "algorithm=AES-256" -F "allow_print=true" \
  --output encrypted.pdf

回應：加密後的 PDF。

PDF 解密

用密碼移除 PDF 加密。

POST /tools/pdf-decrypt/api/pdf-decrypt

curl -X POST http://localhost:8765/tools/pdf-decrypt/api/pdf-decrypt \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@encrypted.pdf" -F "password=open123" \
  --output decrypted.pdf

回應：解密後的 PDF。

文件去識別化

對 Word / PDF 文件偵測並遮蔽個資（regex / 可選 LLM）。

POST /tools/doc-deident/api/doc-deident

curl -X POST http://localhost:8765/tools/doc-deident/api/doc-deident \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@contract.pdf" -F "mode=mask" \
  --output deidentified.pdf

回應：去識別化後的檔案。

文字去識別化

對純文字偵測並遮蔽個資。

POST /tools/text-deident/api/text-deident

Body（JSON）：

curl -X POST http://localhost:8765/tools/text-deident/api/text-deident \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"我的電話是 0912345678，身分證 A123456789","mode":"mask"}'

回應 JSON：遮蔽後文字 + 命中的 PII 清單。

文字差異比對

比對兩段文字差異。

POST /tools/text-diff/api/text-diff

Body（JSON）：

curl -X POST http://localhost:8765/tools/text-diff/api/text-diff \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text_a":"原始內容\n第二行","text_b":"修改內容\n第二行"}'

回應 JSON：每段差異的類型（equal / insert / delete / replace）與內容。

文件差異比對

比對兩份文件（PDF / Word）內容差異。

POST /tools/doc-diff/api/doc-diff

curl -X POST http://localhost:8765/tools/doc-diff/api/doc-diff \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file_a=@v1.pdf" -F "file_b=@v2.pdf" | jq

回應 JSON：逐段差異結構。

清單處理

對文字清單做去重、排序、計數、集合運算等管線處理。

POST /tools/text-list/api/text-list

Body（JSON）：

curl -X POST http://localhost:8765/tools/text-list/api/text-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"banana\napple\napple\ncherry","ops":[{"op":"dedup"},{"op":"sort"}]}'

回應 JSON：{"lines": [...], "count": N, "original_count": M, ...}。

逐句翻譯

走本地端 LLM 逐句翻譯。

POST /tools/translate-doc/api/translate-doc

Body（JSON）：

curl -X POST http://localhost:8765/tools/translate-doc/api/translate-doc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world. This is a test.","source_lang":"auto","target_lang":"zh-TW"}'

回應 JSON：

{
  "source_lang": "en",
  "target_lang": "zh-TW",
  "results": [
    {"src": "Hello world.", "translated": "你好，世界。", "error": ""},
    {"src": "This is a test.", "translated": "這是一個測試。", "error": ""}
  ]
}

需 admin 啟用 LLM 服務（/admin/llm-settings）。未啟用回 503。

統編查詢（單筆）

依 8 位統一編號反查公司 / 機關名稱、地址、行業類別。

POST /tools/vat-lookup/api/vat-lookup

Body（JSON）：{"vat": "12345678"}

curl -X POST http://localhost:8765/tools/vat-lookup/api/vat-lookup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vat":"12345678"}' | jq

回應 JSON：公司名稱 / 地址 / 行業等。找不到回 404。

統編查詢（path style）

同上，但用 GET + path 參數。

GET /api/vat-lookup/{vat}

curl http://localhost:8765/api/vat-lookup/12345678 \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

回應 JSON：同單筆查詢。

統編查詢（批次）

一次查多筆統編。

POST /tools/vat-lookup/api/vat-lookup/batch

Body（JSON）：{"vats": ["12345678", "23456789"]}

curl -X POST http://localhost:8765/tools/vat-lookup/api/vat-lookup/batch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vats":["12345678","23456789"]}' | jq

回應 JSON：每筆查詢結果陣列。

電子發票掃描

解析電子發票 QR Code 內容。

POST /tools/einvoice-scan/api/einvoice-scan

curl -X POST http://localhost:8765/tools/einvoice-scan/api/einvoice-scan \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@invoice.jpg" | jq

回應 JSON：發票號碼、日期、金額、賣方統編等。

電子發票後端狀態

查 QR Code 解碼後端（zbar）是否可用。

GET /tools/einvoice-scan/api/backend-status

curl http://localhost:8765/tools/einvoice-scan/api/backend-status \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

回應 JSON：{"available": true/false, ...}。

送件前檢核 — 自家公司主檔

管理送件前檢核用的自家公司實體（CRUD）。

GET    /tools/submission-check/api/self-entities
POST   /tools/submission-check/api/self-entities
PUT    /tools/submission-check/api/self-entities/{entity_id}
DELETE /tools/submission-check/api/self-entities/{entity_id}

POST / PUT 參數：name、tax_id、address、aliases、type、note。

# 列出
curl http://localhost:8765/tools/submission-check/api/self-entities \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

# 新增
curl -X POST http://localhost:8765/tools/submission-check/api/self-entities \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Acme 股份有限公司" -F "tax_id=12345678" \
  -F "address=台北市..." -F "type=company"

# 更新
curl -X PUT http://localhost:8765/tools/submission-check/api/self-entities/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Acme 國際" -F "tax_id=12345678"

# 刪除
curl -X DELETE http://localhost:8765/tools/submission-check/api/self-entities/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

回應 JSON：實體清單 / 操作結果。

長時間或批次操作走 job queue。流程：

1. 呼叫對應工具的提交 endpoint → 拿到 {"job_id": "..."}
2. 輪詢 GET /api/jobs/{job_id} 直到 status == "completed"
3. 下載 GET /api/jobs/{job_id}/download 取結果（單檔 PDF / 多檔 ZIP）

LLM 校驗（pdf-fill）

POST /api/llm-review

curl -X POST http://localhost:8765/api/llm-review \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@filled.pdf" -F "template_id=vendor_form_v3" \
  | jq
# → {"job_id": "..."}

回應：{"job_id": "..."}。

查 job 狀態

GET /api/jobs/{job_id}

curl http://localhost:8765/api/jobs/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

回應：

{
  "job_id": "abc123...",
  "status": "running",
  "progress": 0.65,
  "message": "校驗第 5 / 12 欄位",
  "error": null,
  "tool": "pdf-fill-llm"
}

status：pending / running / completed / failed。

下載 job 結果

GET /api/jobs/{job_id}/download

curl http://localhost:8765/api/jobs/abc123/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output result.pdf

回應：結果檔（PDF / ZIP）。未完成（status != completed）回 409。

下載 job 結果為 PNG

GET /api/jobs/{job_id}/download-png

curl http://localhost:8765/api/jobs/abc123/download-png \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output result.zip

回應：把 job 的 PDF 結果 render 成 PNG（多頁 / 多檔自動打 ZIP）。

需 admin 登入或 admin role token。

列出資產

列出所有印章 / 簽名 / Logo / 浮水印資產。

GET /admin/api/assets

curl http://localhost:8765/admin/api/assets \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

讀取 / 更新 LLM 設定

GET  /admin/api/llm/settings
POST /admin/api/llm/settings

# 讀取
curl http://localhost:8765/admin/api/llm/settings \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

# 更新
curl -X POST http://localhost:8765/admin/api/llm/settings \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"base_url":"http://localhost:11434","model":"gemma4:26b"}'

測試 LLM 連線

POST /admin/api/llm/test-connection

curl -X POST http://localhost:8765/admin/api/llm/test-connection \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

抓 LLM 模型清單

GET /admin/api/llm/models

curl http://localhost:8765/admin/api/llm/models \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

系統相依套件狀態

GET /admin/api/sys-deps

curl http://localhost:8765/admin/api/sys-deps \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

企業 logo 狀態

GET /admin/api/branding

curl http://localhost:8765/admin/api/branding \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

設定匯出清單

GET /admin/api/settings-export/summary

curl http://localhost:8765/admin/api/settings-export/summary \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq

Token 管理

POST /admin/api/tokens/create    # 核發新 token
POST /admin/api/tokens/revoke    # 撤銷 token
POST /admin/api/tokens/enforce   # 開關 enforce 模式

# 核發
curl -X POST http://localhost:8765/admin/api/tokens/create \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"gitlab-ci"}' | jq

# 開啟 enforce
curl -X POST http://localhost:8765/admin/api/tokens/enforce \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enforce":true}'

GitLab CI / GitHub Actions：把 Word 文件自動轉 PDF

# .gitlab-ci.yml
convert-docs:
  script:
    - |
      for f in docs/*.docx; do
        curl -fsSL -X POST "http://jtdt.internal:8765/api/convert-to-pdf" \
          -H "Authorization: Bearer $JTDT_TOKEN" \
          -F "file=@$f" \
          --output "build/$(basename "$f" .docx).pdf"
      done
  artifacts:
    paths: [build/]

Python 客戶端：批次清掉 PDF 註解

import requests
from pathlib import Path

API = "http://localhost:8765"
TOKEN = "YOUR_64_HEX_TOKEN"
H = {"Authorization": f"Bearer {TOKEN}"}

for pdf in Path("incoming/").glob("*.pdf"):
    with pdf.open("rb") as f:
        r = requests.post(
            f"{API}/tools/pdf-annotations-strip/api/pdf-annotations-strip",
            headers=H,
            files={"file": (pdf.name, f, "application/pdf")},
        )
    r.raise_for_status()
    (Path("clean/") / pdf.name).write_bytes(r.content)
    print(f"OK {pdf.name}")

Shell：監看 job 完成後下載

#!/bin/bash
TOKEN="YOUR_TOKEN"
API="http://localhost:8765"

JOB=$(curl -fsSL -X POST "$API/api/llm-review" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@filled.pdf" -F "template_id=vendor_form_v3" \
  | jq -r .job_id)

echo "Job: $JOB"

while :; do
  S=$(curl -fsSL "$API/api/jobs/$JOB" -H "Authorization: Bearer $TOKEN")
  STATE=$(echo "$S" | jq -r .status)
  PROG=$(echo "$S" | jq -r .progress)
  echo "  $STATE  $PROG"
  [ "$STATE" = "completed" ] && break
  [ "$STATE" = "failed" ] && { echo "Failed"; exit 1; }
  sleep 2
done

curl -fsSL "$API/api/jobs/$JOB/download" \
  -H "Authorization: Bearer $TOKEN" \
  --output reviewed.pdf
echo "Saved: reviewed.pdf"

Node.js：逐句翻譯

const r = await fetch(
  'http://localhost:8765/tools/translate-doc/api/translate-doc',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN',
    },
    body: JSON.stringify({
      text: 'Hello world. This is a test.',
      source_lang: 'auto',
      target_lang: 'zh-TW',
    }),
  }
);
const j = await r.json();
console.log(j.results);
// [{src: 'Hello world.', translated: '你好，世界。', error: ''}, ...]

13. CLI 管理 token

# 列出
sudo jtdt auth show

# 直接讀檔可看（unhash 不可逆）：
sudo cat /var/lib/jt-doc-tools/data/api_tokens.json

# 撤銷（CLI 沒提供撤銷，必要時直接清掉檔案後重啟服務）：
sudo systemctl stop jt-doc-tools
sudo rm /var/lib/jt-doc-tools/data/api_tokens.json
sudo systemctl start jt-doc-tools
# 重啟後 admin UI 重新核發

14. 速率限制 / 大檔上限

目前沒有內建 rate limit。建議部署時用反向代理（nginx / Caddy）加：

• client_max_body_size 100M（必設，否則 PDF 大檔會被拒）
• proxy_read_timeout 900s + proxy_send_timeout 900s（必設 — LLM 工具單筆推理常 5-15 分鐘，預設 60s 必定 504）
• proxy_buffering off（LLM streaming 友善）
• 多層 nginx 情境（自架 LLM proxy + jt-doc-tools 兩台 nginx）每一層都要設，一層用預設整鏈就斷
• 如有公開暴露需求，建議加上 limit_req_zone 防濫用

詳見 OPS.md 的「反向代理」段與「504 Gateway Timeout 排錯流程」。

14b. 使用者工作區（session 認證，非 Bearer API）

「我的工作區」是綁定登入 session 的網頁功能（cookie 認證），不屬於對外 Bearer API，因為每個檔案以登入者帳號隔離。需 admin 在「工作區設定」啟用；停用時下列端點一律回 404。

容量額度、單檔上限、保留時數、啟用 / 停用由 admin 在 /admin/workspace 設定（全站統一，無個人特例）。

15. 變更歷史

API 介面遵循 SemVer：minor 版本（如 1.4.x → 1.5.x）保證後相容；major 版本（1.x → 2.x）才會 breaking。新加 endpoint 不算 breaking。

完整變更紀錄見 CHANGELOG.md。