跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

建立報告模板

⚠️

Beta 預覽版
Report Generation API 目前位於 /beta 路徑下,屬於預覽版功能。API 介面、欄位、處理行為及回應格式可能隨產品迭代調整(包含但不限於變更規格、移除功能),APMIC 不保證其向下相容性。

報告模板用於定義報告的版面結構、可填寫欄位與撰寫指引。模板建立完成後,可在後續報告生成流程中重複使用,以確保報告格式與內容結構一致。
系統會依序完成以下處理:

  • 模板轉換:解析上傳的 PDF 模板,並轉換為 HTML 結構。

  • 欄位擷取:識別模板中的版面結構與可填寫欄位,產生 jinja_html 與 slots。

  • 撰寫指引生成:根據確認後的模板結構,產生後續報告生成所需的 writing_guidelines。結構詳見下方「writing_guidelines 結構」。


API 一覽​

功能MethodEndpoint
建立報告模板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​

HeaderValue
AuthorizationBearer <your-api-key>
Content-Typeapplication/json
acceptapplication/json

Request Body​

{
"name": "Monthly Financial Report Template",
"source_file_id": "e49a877e-738d-4f7c-93f6-0bb4b58b9a53",
"webhook_url": "https://example.com/webhooks/report-template"
}

欄位說明​

欄位型別必填說明
namestring否報告模板名稱。未提供時由系統自動命名
source_file_idstring是透過 Files API 上傳 PDF 模板後取得的檔案 ID
webhook_urlstring (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 欄位​

欄位型別說明
idstring (uuid)報告模板 ID
objectstring資源類型,固定為 report_template
namestring報告模板名稱
statestring模板目前的處理狀態,請參考下方「模板狀態」
source_file_idstring來源檔案 ID
webhook_urlstring接收通知的 Webhook URL,未設定時不會出現在回應中
fail_detailarray失敗紀錄,無失敗時為空陣列
metadataobject模板附加資訊
created_atstring (date-time)資源建立時間
updated_atstring (date-time)資源最後更新時間
jinja_htmlstring模板的 Jinja HTML,僅在有值時出現,詳見「取得報告模板」的 expand 說明
slotsobject模板的可填寫欄位,僅在有值時出現
writing_guidelinesobject撰寫指引,僅在有值時出現

報告模板 API 的回應中,值為 null 的欄位不會出現在回應中,而非以 null 回傳。
後續查詢、確認或更新模板時,請使用回應中的 id 作為 template_id。


2. 取得報告模板​

取得指定模板的目前狀態與資料。

Endpoint​

GET /beta/report-generation/templates/{template_id}

Path Parameters​

參數型別必填說明
template_idstring (uuid)是報告模板 ID

Query Parameters​

expand​

expand 用於額外取得模板內容。未指定時,回應只包含模板的基本資料。

參數型別必填說明
expandarray 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_htmlstring否確認或調整後的 Jinja HTML 模板,未提供時沿用目前內容
slotsobject否確認或調整後的模板欄位,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"
}
}

欄位說明​

欄位型別必填說明
namestring否報告模板名稱
jinja_htmlstring否Jinja HTML 模板內容,會整份取代原有內容
slotsobject否模板欄位,會整份取代原有內容
writing_guidelinesobject否撰寫指引,會整份取代原有內容。結構為 global_guide 與 chapters,詳見下方「writing_guidelines 結構」
metadataobject否自訂附加資訊(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_guidestring整份報告共用的撰寫規範(Markdown),描述報告種類、報告對象、使用語言、整體口吻與重要元素
chaptersarray章節撰寫指引陣列,順序與模板中的章節順序一致
chapters[].guidestring單一章節的撰寫指引(Markdown),描述章節主旨、內容摘要、包含的元素與各 slot 的內容方向
chapters[].slot_maparray該章節負責填入的 slot 及其說明
chapters[].slot_map[].namestringslot 名稱,須與 slots 的 Key 及 jinja_html 中的變數名稱完全一致
chapters[].slot_map[].descriptionstring該 slot 應填入內容的性質與目的。系統產生的內容會包含「我不會做的事」(例如不捏造數值)與「需要你提供的資料」兩個區塊
chapters[].slot_map[].stylestring該 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_templatePDF 轉 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"
}
HTTPerror_code情境
401AUTH_001未提供 Authorization header
403AUTH_002 / AUTH_003API Key 無效/已過期
404REPORT_TEMPLATE_001模板不存在,或不屬於目前的 API Key
409REPORT_TEMPLATE_002狀態不符(確認 API 需為 pending_confirm、PATCH 需為 completed),附 state / expected_state
400REPORT_TEMPLATE_003expand 指定了不支援的欄位,附 fields
400REPORT_TEMPLATE_004確認時 slots 與 jinja_html 變數不一致,附 missing_slots / extra_slots
422—Request Body 或參數不符合 Schema

完整錯誤代碼請參考 錯誤代碼說明-建立報告模板。


串接注意事項​

項目說明
API 路徑Report Generation API 目前使用 /beta,屬預覽版功能,不保證向下相容
非同步處理建立與確認模板後,需依 state 判斷處理進度
Template IDPath 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 確認最新狀態
後續使用模板完成後,可依「報告生成」章節以模板內容建立報告