# 建立報告模板

:::warning[⚠️]

**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}` |

---

### 操作流程

```text
透過 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

```text
POST /beta/report-generation/templates
```

建立成功後回傳 `201 Created`，模板狀態會先進入：

```text
parsing_template
```

模板解析完成後，狀態會轉為：

```text
pending_confirm
```

解析失敗時，狀態會轉為 `failed`。若有設定 `webhook_url`，系統會在解析完成或失敗時傳送通知。

---

### Request Headers

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer <your-api-key>` |
| `Content-Type` | `application/json` |
| `accept` | `application/json` |

---

### Request Body

```json
{
  "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 範例

```bash
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 範例

```json
{
  "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

```text
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` |

多個欄位可使用逗號分隔：

```text
GET /beta/report-generation/templates/{template_id}?expand=jinja_html,slots,writing_guidelines
```

也可以重複傳入：

```text
GET /beta/report-generation/templates/{template_id}?expand=jinja_html&expand=slots
```

指定上表以外的欄位時，API 會回傳 `400`（`REPORT_TEMPLATE_003`），並在 `fields` 中列出不支援的欄位。

---

### cURL 範例

```bash
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 範例

```json
{
  "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

```text
POST /beta/report-generation/templates/{template_id}/confirm
```

此 API 僅可在模板狀態為以下值時呼叫，其他狀態會回傳 `409`（`REPORT_TEMPLATE_002`）：

```text
pending_confirm
```

確認前，建議先取得 `jinja_html` 與 `slots`：

```text
GET /beta/report-generation/templates/{template_id}?expand=jinja_html,slots
```

---

### Request Body

Request Body 為選填。不帶 Request Body 時，系統會直接以目前的 `jinja_html` 與 `slots` 進行確認。

```json
{
  "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` 中的模板變數，兩者必須完全一致。例如：

```text
<h1>{{ company_name }}</h1><p>報告期間：{{ report_period }}</p>
```

應對應：

```json
{
  "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 範例

```bash
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`），狀態為：

```text
generating_guidelines
```

撰寫指引產生完成後，狀態會轉為 `completed`；產生失敗時則轉為 `failed`。兩種情況都會發送 Webhook 通知（若有設定 `webhook_url`）。

---

## 4. 更新報告模板

更新已完成的報告模板。

### Endpoint

```text
PATCH /beta/report-generation/templates/{template_id}
```

此 API 僅適用於狀態為以下值的模板，其他狀態會回傳 `409`（`REPORT_TEMPLATE_002`）：

```text
completed
```

---

### Request Body

所有欄位皆為選填，只會更新有帶入的欄位。

```json
{
  "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`。

:::danger[⚠️]

**修改** `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 範例

```bash
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`，修正來源檔案後重新建立模板 |

狀態流轉如下：

```text
parsing_template ──(解析失敗)──→ failed
       ↓
pending_confirm
       ↓ 呼叫確認 API
generating_guidelines ──(指引生成失敗)──→ failed
       ↓
completed
```

`failed` 為終止狀態：確認 API 與 PATCH API 都不接受 `failed` 狀態的模板，需重新建立模板。

---

## 模板主要欄位

### `jinja_html`

模板的 HTML 結構，其中以 Jinja 語法標示可填入內容的位置。

```text
<h1>{{ company_name }}</h1><p>報告期間：{{ report_period }}</p>
```

### `slots`

描述模板中可填入內容的欄位。Key 為 slot 名稱（對應 `jinja_html` 中的變數），Value 為從來源 PDF 擷取的範例內容。

```json
{
  "company_name": "Example Company",
  "report_period": "2026 Q2"
}
```

### `writing_guidelines` 結構

描述報告內容的撰寫原則與章節指引，作為報告生成時的依據。呼叫確認模板結構 API 後，系統會根據 `jinja_html` 與 `slots` 自動產生撰寫指引，完成後模板狀態直接轉為 `completed`，不需要再次確認。撰寫指引的文字內容以繁體中文產生，可透過以下 API 取得：

```text
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 結構與樣式規格，作為報告內容的輸出格式依據 |

#### 範例

```json
{
  "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`

失敗紀錄陣列，每次失敗會累加一筆。

```json
[
  {
    "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`：

```json
{
  "detail": [
    {
      "loc": ["body", "source_file_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

| 欄位 | 說明 |
| --- | --- |
| `detail[].loc` | 錯誤位置 |
| `detail[].msg` | 錯誤說明 |
| `detail[].type` | 錯誤類型 |

其餘錯誤會以下列格式回傳：

```json
{
  "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 |

完整錯誤代碼請參考 [錯誤代碼說明-建立報告模板](https://privstation-docs.apmic.ai/latest/privai-400/錯誤代碼說明-建立報告模板.md)。

---

## 串接注意事項

| 項目 | 說明 |
| --- | --- |
| 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 確認最新狀態 |
| 後續使用 | 模板完成後，可依「報告生成」章節以模板內容建立報告 |
