---
reviewed_by:
  rd: Ronny
  pm:
---
# 法人詳細資料 — `tw.gov.judicial~ref~foundation-doc`

> **給 AI 閱讀的使用指引。**
> 人類可在 https://data.openfun.tw/datasets/tw.gov.judicial~ref~foundation-doc 看到同份內容的網頁版。
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

## ⚠️ 開始之前（AI agent 必讀，摘要也請保留這段）

資料集 slug：tw.gov.judicial~ref~foundation-doc
API 端點：https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records
認證方式（必填）：HTTP Header  Authorization: Bearer {token}

最簡查詢範例：curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records?per_page=5"

**Token 是必要條件，沒有 Token 就無法查資料。**
如果使用者沒有 Token，請停止並告訴使用者：「請先前往 https://data.openfun.tw/user 免費申請帳號與 API Token，取得後告訴我，我再幫您查詢。」

禁止抓取 HTML 頁面（本平台有 bot 保護，WebFetch 讀 HTML 頁面會失敗）。

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／司法院」

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 司法院（[法人登記公告](https://www.judicial.gov.tw/tw/lp-144-1.html)） |
| 授權 | 政府資料開放授權條款 1.0 |
| 更新頻率 | 每日 |
| 涵蓋範圍 | 全台各地方法院登記之財團法人、社團法人、政黨的所有歷次公告 |
| 總筆數 | 約 165,273 筆 |

---

## 這份資料集能回答什麼問題

以下問題，這份資料集**可以回答**：

- 「某財團法人的主事務所地址、設立目的、捐助方法？」
- 「某法人的財產總額是多少？」
- 「某法人目前的董事長/理事長/董監事名單？」
- 「某法人何時解散、原因是什麼？」
- 「台中市有哪些社團法人？」（透過篩選法院編號＋類別）
- 「某人在哪些法人擔任董監事？」（搜尋 `董監事.姓名`）

以下問題，這份資料集**無法回答**：

- 「法人的財務報表」（本資料集僅有設立時申報的財產總額，不含年度財報）
- 「法人所有歷史紀錄的彙整」→ 每筆是單次公文，需透過 `tw.gov.judicial~ref~foundation` 的歷程公告文號串接

> **重要**：每筆記錄代表**一次登記事件**，不是法人的「現況快照」。若要查法人目前狀態，應先從 `tw.gov.judicial~ref~foundation` 取得最新公告文號，再查本資料集的對應記錄。

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `公文編號` | keyword（_id） | 每次設立或變更都會有一筆新的公文編號 |
| `公文編號.登記案號` | keyword |  |
| `公文編號.法院編號` | keyword（ref: tw.gov.judicial~ref~court） |  |
| `法人名稱` | text（_name） |  |
| `類別` | keyword（篩選器） | 1-財團,2-社團,3-政黨 |
| `案由` | keyword（篩選器） |  |
| `主任` | text | 地方法院登記處法人登記主任 |
| `登記號數` | keyword |  |
| `收件日期` | date |  |
| `登記日期` | date |  |
| `公告日期` | date |  |
| `登記簿` | text |  |
| `任期判定` | keyword |  |
| `屆期判定` | keyword |  |
| `法人代表` | text |  |
| `設立登記日期` | date |  |
| `主事務所` | text |  |
| `目的` | text |  |
| `捐助方法` | text |  |
| `許可機關日期` | text |  |
| `存立時期` | text |  |
| `財產總額` | number |  |
| `結案原因` | keyword |  |
| `結案日期` | date |  |
| `歸檔日期` | date |  |
| `發證日期` | date |  |
| `清算人` | text |  |
| `變更原因` | text |  |
| `註銷日期` | date |  |
| `撤銷日期` | date |  |
| `撤(註)銷機關文號` | text |  |
| `撤(註)銷原因` | text |  |
| `董監事` | object（多值） |  |

### 關鍵欄位補充說明

| 欄位 | 型別 | 重要說明 |
|------|------|---------|
| `公文編號` | keyword（_id） | 主鍵，格式 `{法院編號}:{民國年}法登{類型}{流水號}`，如 `TCD:105法登他000170` |
| `公文編號.法院編號` | keyword（篩選器） | 3 碼法院代碼，如 `TCD`；可篩選特定法院管轄的法人；對照 `tw.gov.judicial~ref~court` |
| `法人名稱` | text（_name） | 全文搜尋：`?q=慈善基金會` |
| `類別` | keyword（篩選器） | `1`=財團法人、`2`=社團法人、`3`=政黨 |
| `案由` | keyword（篩選器） | `1`=設立、`2`=變更、`3`=解散、`5`=清算終結、`A`=撤銷/廢止 |
| `財產總額` | number | 設立或本次變更申報值，**不等於現時實際財產** |
| `董監事` | object[]（multi） | 陣列，每筆含 `職稱`（篩選器）、`姓名`（篩選器）；查詢：`?董監事.姓名=王小明` |
| `設立登記日期` | date | 法人最初設立日期（非本次公告日期） |

---

## 重要注意事項（查詢前必讀）

### ⚠️ 每筆是登記事件，不是法人現況快照

同一法人的設立、歷次變更各為獨立紀錄。**查詢法人目前狀態必須先從 `tw.gov.judicial~ref~foundation` 取得最新公告文號**，再查本資料集。

### ⚠️ 以姓名搜尋董監事可能命中不同人

`?董監事.姓名=王小明` 以字串比對，無法識別身分證號。常見姓名的結果中**可能混入同名同姓的不同人**。呈現結果時必須提示使用者自行交叉核對（法人性質、地址、年代）確認是否同一人。

### ⚠️ 社團法人資料不完整

社團法人依人民團體法第 11 條屬**自願**登記，本資料集僅含選擇辦理者，並非全台所有立案社團。

---

## API 呼叫範例

**Records URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records`

### 查詢某法人的最新登記資料（兩步驟）

**步驟 1**：先到 foundation 用名稱搜尋，取得最新公告文號
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation/records?q=台灣紅十字&per_page=3"
```

**步驟 2**：用最新公告文號查本資料集
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records?公文編號=TPD:114法登財000001"
```

### 查詢台中地院管轄的所有財團法人（設立公告）

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records?公文編號.法院編號=TCD&類別=1&案由=1&per_page=20"
```

### 查詢某人在哪些法人擔任職務

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records?董監事.姓名=王小明&per_page=20"
```

> ⚠️ 以姓名比對，可能混入同名同姓的不同人，請提示使用者交叉核對。

### 查詢最近設立的法人

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records?案由=1&sort=-設立登記日期&per_page=20"
```

### 查詢已解散的社團法人

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records?案由=3&類別=2&per_page=20"
```

---

## 統計聚合（/agg 端點）

**Agg URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/agg`

### 各類別（財團/社團/政黨）的登記筆數

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/agg?group_by=類別"
```

### 各法院管轄的登記筆數

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/agg?group_by=公文編號.法院編號"
```

### 各案由（設立/變更/解散）的分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/agg?group_by=案由"
```

### 現任各法院財團法人財產總額統計

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/agg?group_by=公文編號.法院編號&field=財產總額&類別=1"
```

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.judicial~ref~foundation`](../tw.gov.judicial~ref~foundation/skill.md) | 法人主索引 | 用法人名稱找到公文編號，再查本資料集 |
| [`tw.gov.judicial~ref~court`](../tw.gov.judicial~ref~court/skill.md) | 法院代碼對照表 | 解讀 `公文編號.法院編號` |

---

## 注意事項與限制

1. **每筆是單次公告，不是法人現況快照**：若要取得最新狀態，必須透過 `tw.gov.judicial~ref~foundation` 取得最新公告文號。
2. **財產總額僅供參考**：只記錄設立或本次變更申報時的金額，不反映法人目前實際財產。
3. **董監事為該次公告時的名單**：若要取得目前最新名單，需查最新公告文號對應的記錄。
4. **類別代碼**：`1`=財團法人（108,127 筆）、`2`=社團法人（56,755 筆）、`3`=政黨（391 筆）。
5. **案由代碼**：`1`=設立、`2`=變更（佔大多數）、`3`=解散、`5`=清算終結、`A`=撤銷/廢止。
6. **以姓名搜尋董監事必須提醒同名同姓風險**：`董監事.姓名` 以字串比對，無法區分身分，必須告知使用者需自行交叉核對。
7. **社團法人不完整**：人民團體法第 11 條屬自願登記，本資料集中的社團法人並非全台所有立案社團。
8. **財團法人分政府捐助與民間捐助**：依財團法人法第 2 條，政府機構、公法人或公營事業捐助逾基金 50% 者為政府捐助財團法人，其餘為民間捐助。政府捐助的財團法人通常 `財產總額` 規模較大，兩者在主管機關、財務公開要求上也有差異。本資料集不區分此兩類，查詢時可從 `目的`、`捐助方法` 欄位的文字內容判斷。

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.judicial~ref~foundation-doc/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| 全文搜尋 | `?q=關鍵字`（搜尋法人名稱） |
| 類別篩選 | `?類別=1`（財團）、`?類別=2`（社團）、`?類別=3`（政黨） |
| 案由篩選 | `?案由=1`（設立）、`?案由=2`（變更）、`?案由=3`（解散） |
| 法院篩選 | `?公文編號.法院編號=TCD` |
| 董監事搜尋 | `?董監事.姓名=姓名`、`?董監事.職稱=職稱` |
| 分頁 | `?page=1&per_page=20` |
| Records 回應 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |