建立報告模板
Beta 預覽版
Report Generation API 目前位於 /beta 路徑下,屬於預覽版功能。API 介面、欄位、處理行為及回應格式可能隨產品迭代調整(包含但不限於變更規格、移除功能),APMIC 不保證其向下相容性。
報告模板用於定義報告的版面結構、可填寫欄位與撰寫指引。模板建立完成後,可在後續報告生成流程中重複使用,以確保報告格式與內容結構一致。
系統會依序完成以下處理:
-
模板轉換:解析上傳的 PDF 模板,並轉換為 HTML 結構。
-
欄位擷取:識別模板中的版面結構與可填寫欄位,產生
jinja_html與slots。 -
撰寫指引生成:根據確認後的模板結構,產生後續報告生成所需的
writing_guidelines。結構詳見下方「writing_guidelines結構」。
API 一覽
| 功能 | Method | Endpoint |
|---|---|---|
| 建立報告模板 | POST | /beta/report-generation/templates |
| 取得報告模板 | GET | /beta/report-generation/templates/{template_id} |
| 確認模板結構 | POST | /beta/report-generation/templates/{template_id}/confirm |
| 更新報告模板 | PATCH | /beta/report-generation/templates/{template_id} |
操作流程
透過 Files API 上傳 PDF 模板,取得檔案 ID
↓
建立報告模板(state: parsing_template)
↓
系統解析模板結構(完成後 state: pending_confirm,發送 Webhook)
↓
取得並確認或調整 jinja_html 與 slots
↓
確認模板結構(state: generating_guidelines)
↓
系統產生撰寫指引(完成後 state: completed,發送 Webhook)
↓
模板建立完成,可用於報告生成或透過 PATCH 更新
建立報告模板前,請先透過「上傳檔案」API 上傳 PDF 格式的來源模板,並取得檔案 ID。此 ID 將作為建立模板時的 source_file_id。
1. 建立報告模板
建立新的報告模板,並啟動非同步模板解析程序。
Endpoint
POST /beta/report-generation/templates
建立成功後回傳 201 Created,模板狀態會先進入:
parsing_template
模板解析完成後,狀態會轉為:
pending_confirm
解析失敗時,狀態會轉為 failed。若有設定 webhook_url,系統會在解析完成或失敗時傳送通知。
Request Headers
| Header | Value |
|---|---|
Authorization | Bearer <your-api-key> |
Content-Type | application/json |
accept | application/json |
Request Body
{
"name": "Monthly Financial Report Template",
"source_file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
"webhook_url": "https://example.com/webhooks/report-template"
}
欄位說明
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
name | string | 否 | 報告模板名稱。未提供時由系統自動命名 |
source_file_id | string | 是 | 透過 Files API 上傳 PDF 模板後取得的檔案 ID |
webhook_url | string (URL) | 否 | 接收非同步處理通知的 Webhook URL,需為合法的 HTTP / HTTPS URL |
Request Body 不接受上表以外的欄位,帶入未定義的欄位會回傳 422。
source_file_id 須為已上傳的 PDF 檔案。若檔案無法解析,模板會在背景處理後轉為 failed,並在 fail_detail 中記錄 failed_step 為 parse_template。
cURL 範例
curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/templates' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "Monthly Financial Report Template",
"source_file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
"webhook_url": "https://example.com/webhooks/report-template"
}'
Response 範例
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "report_template",
"name": "Monthly Financial Report Template",
"state": "parsing_template",
"source_file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
"webhook_url": "https://example.com/webhooks/report-template",
"fail_detail": [],
"metadata": {},
"created_at": "2026-10-08T07:20:00.123456Z",
"updated_at": "2026-10-08T07:20:00.123456Z"
}
Response 欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string (uuid) | 報告模板 ID |
object | string | 資源類型,固定為 report_template |
name | string | 報告模板名稱 |
state | string | 模板目前的處理狀態,請參考下方「模板狀態」 |
source_file_id | string | 來源檔案 ID |
webhook_url | string | 接收通知的 Webhook URL,未設定時不會出現在回應中 |
fail_detail | array | 失敗紀錄,無失敗時為空陣列 |
metadata | object | 模板附加資訊 |
created_at | string (date-time) | 資源建立時間 |
updated_at | string (date-time) | 資源最後更新時間 |
jinja_html | string | 模板的 Jinja HTML,僅在有值時出現,詳見「取得報告模板」的 expand 說明 |
slots | object | 模板的可填寫欄位,僅在有值時出現 |
writing_guidelines | object | 撰寫指引,僅在有值時出現 |
報告模板 API 的回應中,值為 null 的欄位不會出現在回應中,而非以 null 回傳。
後續查詢、確認或更新模板時,請使用回應中的 id 作為 template_id。
2. 取得報告模板
取得指定模板的目前狀態與資料。
Endpoint
GET /beta/report-generation/templates/{template_id}
Path Parameters
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
template_id | string (uuid) | 是 | 報告模板 ID |
Query Parameters
expand
expand 用於額外取得模板內容。未指定時,回應只包含模板的基本資料。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
expand | array of string | 否 | 指定要展開的欄位 |
支援的欄位與可取得的狀態如下。即使明確指定 expand,模板狀態不符合時該欄位仍不會出現在回應中:
| 欄位 | 說明 | 可取得的狀態 |
|---|---|---|
jinja_html | 模板的 Jinja HTML 內容 | pending_confirm、generating_guidelines、completed(parsing_template 與 failed 時一律不回傳) |
slots | 模板的可填寫欄位 | pending_confirm、generating_guidelines、completed(parsing_template 與 failed 時一律不回傳) |
writing_guidelines | 報告撰寫指引 | 僅 completed |
多個欄位可使用逗號分隔:
GET /beta/report-generation/templates/{template_id}?expand=jinja_html,slots,writing_guidelines
也可以重複傳入:
GET /beta/report-generation/templates/{template_id}?expand=jinja_html&expand=slots
指定上表以外的欄位時,API 會回傳 400(REPORT_TEMPLATE_003),並在 fields 中列出不支援的欄位。
cURL 範例
curl -X GET 'https://api.bcm.apmic.ai/beta/report-generation/templates/7c9e6679-7425-40de-944b-e07fc1f90ae7?expand=jinja_html,slots' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY"
Response 範例
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"object": "report_template",
"name": "Monthly Financial Report Template",
"state": "pending_confirm",
"source_file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
"webhook_url": "https://example.com/webhooks/report-template",
"fail_detail": [],
"metadata": {},
"created_at": "2026-10-08T07:20:00.123456Z",
"updated_at": "2026-10-08T07:25:00.654321Z",
"jinja_html": "<!DOCTYPE html><html lang=\"zh-TW\"><head>...</head><body><h1>{{ company_name }}</h1><p>報告期間:{{ report_period }}</p></body></html>",
"slots": {
"company_name": "Example Company",
"report_period": "2026 Q2"
}
}
系統產生的 jinja_html 會在 <head> 內嵌入 Tailwind CSS 樣式程式碼,以確保模板可直接於瀏覽器中呈現,因此實際內容會遠長於上例。
3. 確認模板結構
確認系統解析出的模板結構,並啟動撰寫指引生成程序。可在同一次呼叫中帶入修改後的 jinja_html 與 slots,一次完成編輯與確認。
Endpoint
POST /beta/report-generation/templates/{template_id}/confirm
此 API 僅可在模板狀態為以下值時呼叫,其他狀態會回傳 409(REPORT_TEMPLATE_002):
pending_confirm
確認前,建議先取得 jinja_html 與 slots:
GET /beta/report-generation/templates/{template_id}?expand=jinja_html,slots
Request Body
Request Body 為選填。不帶 Request Body 時,系統會直接以目前的 jinja_html 與 slots 進行確認。
{
"jinja_html": "<!DOCTYPE html><html lang=\"zh-TW\"><head>...</head><body><h1>{{ company_name }}</h1><p>報告期間:{{ report_period }}</p></body></html>",
"slots": {
"company_name": "Example Company",
"report_period": "2026 Q2"
}
}
欄位說明
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
jinja_html | string | 否 | 確認或調整後的 Jinja HTML 模板,未提供時沿用目前內容 |
slots | object | 否 | 確認或調整後的模板欄位,Key 為 slot 名稱、Value 為範例內容,未提供時沿用目前內容 |
Request Body 不接受上表以外的欄位,帶入未定義的欄位會回傳 422。
slots 與 jinja_html 的一致性檢查
確認時,系統會比對 slots 的 Key 與 jinja_html 中的模板變數,兩者必須完全一致。例如:
<h1>{{ company_name }}</h1><p>報告期間:{{ report_period }}</p>
應對應:
{
"company_name": "Example Company",
"report_period": "2026 Q2"
}
-
系統只會把
{{ 變數名稱 }}或{{ 變數名稱 | filter }}形式、且名稱為英數字與底線組成的運算式視為模板變數。 -
若
jinja_html中有變數未出現在slots,或slots中有 Key 未出現在jinja_html,API 會回傳400(REPORT_TEMPLATE_004),並在missing_slots與extra_slots中列出差異。
cURL 範例
curl -X POST 'https://api.bcm.apmic.ai/beta/report-generation/templates/7c9e6679-7425-40de-944b-e07fc1f90ae7/confirm' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"slots": {
"company_name": "Example Company",
"report_period": "2026 Q2"
}
}'
確認成功後回傳 202 Accepted,回應內容為更新後的模板(包含 jinja_html 與 slots),狀態為:
generating_guidelines
撰寫指引產生完成後,狀態會轉為 completed;產生失敗時則轉為 failed。兩種情況都會發送 Webhook 通知(若有設定 webhook_url)。
4. 更新報告模板
更新已完成的報告模板。
Endpoint
PATCH /beta/report-generation/templates/{template_id}
此 API 僅適用於狀態為以下值的模板,其他狀態會回傳 409(REPORT_TEMPLATE_002):
completed
Request Body
所有欄位皆為選填,只會更新有帶入的欄位。
{
"name": "Updated Financial Report Template",
"writing_guidelines": {
"global_guide": "## 報告種類\n- 月度財務報告\n## 整體口吻\n- 正式、客觀、資料導向",
"chapters": [
{
"guide": "## 主旨\n- 摘要本期財務表現與關鍵結論",
"slot_map": [
{
"name": "company_name",
"description": "填入報告對象的公司名稱。",
"style": "純文字,不含額外標籤。"
}
]
}
]
},
"metadata": {
"department": "finance"
}
}
欄位說明
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
name | string | 否 | 報告模板名稱 |
jinja_html | string | 否 | Jinja HTML 模板內容,會整份取代原有內容 |
slots | object | 否 | 模板欄位,會整份取代原有內容 |
writing_guidelines | object | 否 | 撰寫指引,會整份取代原有內容。結構為 global_guide 與 chapters,詳見下方「writing_guidelines 結構」 |
metadata | object | 否 | 自訂附加資訊(Key-Value),會整份取代原有內容 |
Swagger UI 中顯示的 additionalProp1 代表該物件可以使用自訂 Key-Value,不需要實際傳入名為 additionalProp1 的欄位。Request Body 不接受上表以外的欄位,帶入未定義的欄位會回傳 422。
修改 jinja_html 前,請先取得原內容再修改
系統解析模板時,會在 jinja_html 中自動嵌入 Tailwind CSS 樣式程式碼。PATCH 會直接以送出的內容取代原有 jinja_html,不會再自動嵌入樣式,也不會檢查 slots 與 jinja_html 是否一致,或重新產生 writing_guidelines。建議先以 GET ?expand=jinja_html,slots,writing_guidelines 取得完整內容,在其上修改後再送出,並自行確認 slots、writing_guidelines.chapters[].slot_map[].name 與 jinja_html 中的變數保持一致。
cURL 範例
curl -X PATCH 'https://api.bcm.apmic.ai/beta/report-generation/templates/7c9e6679-7425-40de-944b-e07fc1f90ae7' \
-H 'accept: application/json' \
-H "Authorization: Bearer $PRIVAI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "Updated Financial Report Template",
"metadata": {
"department": "finance"
}
}'
更新成功後回傳 200,回應內容為更新後的完整模板(包含 jinja_html、slots 與 writing_guidelines)。更新不會改變模板狀態。不帶任何欄位時,系統不做變更,直接回傳目前的模板內容。
模板狀態
| 狀態 | 說明 | 建議操作 |
|---|---|---|
parsing_template | 系統正在將 PDF 轉換為 HTML 並抽取模板欄位 | 等待 Webhook 通知或查詢最新狀態 |
pending_confirm | 模板結構已解析完成 | 取得並確認 jinja_html 與 slots,呼叫確認 API |
generating_guidelines | 系統正在產生撰寫指引 | 等待 Webhook 通知或查詢最新狀態 |
completed | 模板建立完成 | 可用於建立報告,或透過 PATCH 更新模板 |
failed | 模板處理失敗 | 檢查 fail_detail,修正來源檔案後重新建立模板 |
狀態流轉如下:
parsing_template ──(解析失敗)──→ failed
↓
pending_confirm
↓ 呼叫確認 API
generating_guidelines ──(指引生成失敗)──→ failed
↓
completed
failed 為終止狀態:確認 API 與 PATCH API 都不接受 failed 狀態的模板,需重新建立模板。
模板主要欄位
jinja_html
模板的 HTML 結構,其中以 Jinja 語法標示可填入內容的位置。
<h1>{{ company_name }}</h1><p>報告期間:{{ report_period }}</p>
slots
描述模板中可填入內容的欄位。Key 為 slot 名稱(對應 jinja_html 中的變數),Value 為從來源 PDF 擷取的範例內容。
{
"company_name": "Example Company",
"report_period": "2026 Q2"
}
writing_guidelines 結構
描述報告內容的撰寫原則與章節指引,作為報告生成時的依據。呼叫確認模板結構 API 後,系統會根據 jinja_html 與 slots 自動產生撰寫指引,完成後模板狀態直接轉為 completed,不需要再次確認。撰寫指引的文字內容以繁體中文產生,可透過以下 API 取得:
GET /beta/report-generation/templates/{template_id}?expand=writing_guidelines
欄位說明
| 欄位 | 型別 | 說明 |
|---|---|---|
global_guide | string | 整份報告共用的撰寫規範(Markdown),描述報告種類、報告對象、使用語言、整體口吻與重要元素 |
chapters | array | 章節撰寫指引陣列,順序與模板中的章節順序一致 |
chapters[].guide | string | 單一章節的撰寫指引(Markdown),描述章節主旨、內容摘要、包含的元素與各 slot 的內容方向 |
chapters[].slot_map | array | 該章節負責填入的 slot 及其說明 |
chapters[].slot_map[].name | string | slot 名稱,須與 slots 的 Key 及 jinja_html 中的變數名稱完全一致 |
chapters[].slot_map[].description | string | 該 slot 應填入內容的性質與目的。系統產生的內容會包含「我不會做的事」(例如不捏造數值)與「需要你提供的資料」兩個區塊 |
chapters[].slot_map[].style | string | 該 slot 內容的 HTML 結構與樣式規格,作為報告內容的輸出格式依據 |
範例
{
"global_guide": "## 報告種類\n- 季度財務報告\n## 報告對象\n- 企業內部主管與決策者\n## 使用語言\n- 繁體中文\n## 整體口吻\n- 正式、客觀且資料導向,避免未經資料支持的推測",
"chapters": [
{
"guide": "## 主旨\n- 作為整份報告的摘要\n## 內容摘要\n- 報告期間、核心發現與主要指標變化",
"slot_map": [
{
"name": "report_title",
"description": "填入報告標題,需包含報告期間與報告類型。\n我不會做的事:\n- 不會自行推定未提供的報告期間\n需要你提供的資料:\n- 報告期間與報告類型",
"style": "純文字,不含額外標籤。"
},
{
"name": "executive_summary",
"description": "填入本期報告的整體摘要,應包含主要結論與關鍵數據變化。\n我不會做的事:\n- 不會在沒有數據時填入統計數字\n需要你提供的資料:\n- 本期主要財務數據與結論",
"style": "以 <p class='mb-4 leading-relaxed'> 段落呈現。"
}
]
},
{
"guide": "## 主旨\n- 分析本期財務表現\n## 內容摘要\n- 收入、成本與毛利的變化,並與前一季比較",
"slot_map": [
{
"name": "financial_performance",
"description": "填入財務表現分析內容,包含主要財務指標與變化幅度。\n我不會做的事:\n- 不會推測資料以外的變化原因\n需要你提供的資料:\n- 本期與比較期間的財務報表",
"style": "以 <p class='mb-4'> 段落呈現。"
}
]
}
]
}
章節順序與 chapter_id
chapters 陣列中的位置(自 0 起算)即為報告生成時的 chapter_id,也是報告草稿中章節的順序。上例中,report_title 與 executive_summary 屬於 chapter_id 為 0 的章節,financial_performance 屬於 chapter_id 為 1 的章節。
slot 分配的校正
系統產生撰寫指引時,會確保模板中的每個 slot 都分配到一個章節,且只分配一次。因此取得的 writing_guidelines 可能出現以下結果:
| 情況 | 結果 |
|---|---|
slot_map 中出現 slots 沒有的名稱 | 該筆會被移除 |
| 同一個 slot 被分配到多個章節 | 只保留第一次出現的分配 |
| 章節中沒有任何有效的 slot | 該章節會被移除 |
| 有 slot 未被分配到任何章節 | chapters 最後會新增一個章節,收納所有遺漏的 slot,並附上通用的 guide、description 與 style |
若最後一個章節為系統補入的章節,建議檢視其內容,必要時將其中的 slot 調整到合適的章節。
調整撰寫指引
撰寫指引會直接影響報告生成的結果:各章節會依 global_guide、guide 與 slot_map 決定要檢索的資料與撰寫方向。若產生的指引不符合需求,可透過「更新報告模板」API 以 writing_guidelines 欄位整份取代原有內容。調整時請注意:
-
請先取得完整的
writing_guidelines,在其上修改後整份送出,未送出的章節不會保留。 -
slot_map[].name須與slots及jinja_html中的變數保持一致。 -
指引應避免要求產生無資料支持或超出模板用途的內容。
fail_detail
失敗紀錄陣列,每次失敗會累加一筆。
[
{
"error": "...",
"failed_step": "parse_template"
}
]
failed_step | 說明 |
|---|---|
parse_template | PDF 轉 HTML 或模板欄位抽取階段失敗 |
generate_guidelines | 撰寫指引生成階段失敗 |
redelivered_message | 解析任務被重新投遞後中止,需重新建立模板 |
Webhook
建立模板時,可透過 webhook_url 指定接收非同步處理通知的 URL。系統只會在以下三個時間點發送通知:
| 時間點 | 通知時的 state |
|---|---|
| 模板解析完成 | pending_confirm |
| 撰寫指引生成完成 | completed |
| 任一非同步階段失敗 | failed |
建立模板時進入 parsing_template,以及呼叫確認 API 後轉為 generating_guidelines,這兩次狀態變更不會發送 Webhook,因為這兩個狀態會直接由 API 回應帶出。
Webhook 以 POST 發送 application/json,內容包含 id、object、name、state、source_file_id、fail_detail、metadata、created_at、updated_at、jinja_html、slots 與 writing_guidelines,不受 expand 與狀態限制影響。Webhook 請求不附簽章 header。
Webhook 目前只會發送一次,接收端回應失敗或逾時時系統不會重送。收到通知後,建議再呼叫 GET API 確認最新模板狀態與內容;若未收到通知,請以 GET API 輪詢狀態。
錯誤處理
當 Request Body、Path Parameter 或 Query Parameter 不符合 API Schema 時,API 會回傳 422:
{
"detail": [
{
"loc": ["body", "source_file_id"],
"msg": "Field required",
"type": "missing"
}
]
}
| 欄位 | 說明 |
|---|---|
detail[].loc | 錯誤位置 |
detail[].msg | 錯誤說明 |
detail[].type | 錯誤類型 |
其餘錯誤會以下列格式回傳:
{
"error_code": "REPORT_TEMPLATE_002",
"error_message": "Report template is in completed state, expected pending_confirm. Please refer to the API documentation.",
"state": "completed",
"expected_state": "pending_confirm"
}
| HTTP | error_code | 情境 |
|---|---|---|
401 | AUTH_001 | 未提供 Authorization header |
403 | AUTH_002 / AUTH_003 | API Key 無效/已過期 |
404 | REPORT_TEMPLATE_001 | 模板不存在,或不屬於目前的 API Key |
409 | REPORT_TEMPLATE_002 | 狀態不符(確認 API 需為 pending_confirm、PATCH 需為 completed),附 state / expected_state |
400 | REPORT_TEMPLATE_003 | expand 指定了不支援的欄位,附 fields |
400 | REPORT_TEMPLATE_004 | 確認時 slots 與 jinja_html 變數不一致,附 missing_slots / extra_slots |
422 | — | Request Body 或參數不符合 Schema |
完整錯誤代碼請參考 錯誤代碼說明-建立報告模板。
串接注意事項
| 項目 | 說明 |
|---|---|
| API 路徑 | Report Generation API 目前使用 /beta,屬預覽版功能,不保證向下相容 |
| 非同步處理 | 建立與確認模板後,需依 state 判斷處理進度 |
| Template ID | Path Parameter 使用 template_id |
| Expand | 可使用逗號分隔或重複傳入,且受模板狀態限制 |
| Null 處理 | 值為 null 的欄位不會出現在回應中 |
| 確認限制 | 確認 API 僅適用於 pending_confirm 狀態,且 slots 須與 jinja_html 變數一致 |
| 更新限制 | PATCH API 僅適用於 completed 狀態,修改 jinja_html 前請先取得原內容 |
| 失敗處理 | failed 狀態無法重試,需重新建立模板 |
| 資料範圍 | 模板僅能由建立它的 API Key 查詢、確認與更新,詳見「Tenant Scope 與資料隔離」章節 |
| Webhook | 僅在 pending_confirm、completed、failed 時發送且不重送,收到通知後建議再呼叫 GET API 確認最新狀態 |
| 後續使用 | 模板完成後,可依「報告生成」章節以模板內容建立報告 |