Notion API 教學：Token 申請、curl 測試、Typeform 與 n8n 串接（2026）

先說結論（Notion API 教學）

如果你是新手，Notion API 最穩的做法是先完成這 3 步：

1. 建立 Integration 並拿到 Token。
2. 把目標資料來源分享給該 Integration（Connections）。
3. 用 curl 依序跑通 Search、Query、Create page。

先跑通再擴充，成功率最高。

如果你要把 Notion 做成「可交接、可維護」的工作系統，可先看：

• Notion 企業數位大腦與自動化導入是什麼
• 如果你要看完整 n8n 圖解實作，可直接看這篇：別再熬夜排程！用 Notion Webhook 5 分鐘打造社群平台發布機器 n8n 為例。

你要做什麼	最短路徑	你需要準備	最常卡住
驗證 Token 是否可用	curl 打 POST /v1/search	Token、Notion-Version header	401（Token 錯）
讀取資料	POST /v1/data_sources/{id}/query	Data Source ID、欄位型別	403（沒分享）
寫入資料	POST /v1/pages	parent data_source、properties payload	validation_error（欄位對不上）

API 是什麼？新手怎麼理解？

短答：API 就是「兩個軟體溝通的標準說法」。你可以把它想成點餐：

1. 你把「想要什麼」講清楚（Request）。
2. 對方回你「結果是什麼」（Response）。

在 Notion API 裡，你常會看到這幾個關鍵字：

• POST /v1/search：你問 Notion「有哪些符合條件的資料來源？」
• POST /v1/data_sources/{id}/query：你問 Notion「把這個資料來源的資料列給我」
• POST /v1/pages：你請 Notion「幫我新增一列資料」

你做對了，通常會回 200/201；做錯最常見就是 401（Token 錯）或 403（沒授權）。

Notion API 可以拿來做什麼？適合誰？

短答：適合把 Notion 當「資料中樞」的人。你可以用 Notion API 做表單收集、內容同步、CRM/專案資料流整合、備份與自動化寫入。

如果你只是想快速把流程串起來，先用 Typeform/Zapier/Make/n8n 跑通；當你需要更高的可控性（欄位驗證、條件寫入、資料一致性），再回到 API。

Notion API 2026 更新了什麼？為什麼改用 Search + Data Source？

短答：不建議再用舊教學作為主路線。

現在實務上建議用 Search + Data Source 為主。你仍可能在舊專案看到 Database 相關端點，但新流程應以官方現行文件優先。

用途	建議路線（2026）	為什麼
找目標資料來源	POST /v1/search	先找到 page / data source，避免硬貼錯 ID
讀取資料列	POST /v1/data_sources/{id}/query	結構更貼近現在 Notion 資料模型
新增資料列	POST /v1/pages	可直接指定 parent data_source

開始前要準備什麼？

先確認這 5 項，後面就不會一直撞牆：

1. Notion Integration（Internal）。
2. Integration Token（secret_...）。
3. 目標資料來源已分享給 Integration（Connections）。
4. 可跑 HTTP 請求的環境（建議直接用終端機 curl）。
5. 固定的 Notion-Version header。

Notion API Token 怎麼申請？（Integration Token）

在 Notion 的 Integrations 頁面建立一個 Internal Integration，建立完成就能拿到 Token。

讓我們從頭做一次：

一、從左上角的選單，點擊「Settings 」進入設定頁面。

二、在頁面中，點擊左下方的 Connections ，找到頁面下方的 Develop or manage integrations。

三、進入頁面後，點擊 Create a new integration。

幫它取個好記的名字

四、這樣就完成 Internal Integration Token 的申請，請將 Token 存在某個地方，等一下我們需要使用。

Notion API 403 怎麼解？（Connections 授權）

短答：因為 Token 只是鑰匙，資料來源沒有分享給 Integration，一樣沒權限。

你要做的事：

1. 打開目標資料庫（或資料來源）頁面。
2. 點 Connections / Add connections。
3. 指定剛建立的 Integration。
4. 重新送一次 API。

案例 1：用 Typeform 表單寫入 Notion（先做 no-code 驗證）

Typeform 是一個線上表單建立工具，可以讓你輕鬆地建立訪問者可以填寫的表單。( 官網 )

Typeform 是世界上最棒的表單之一，它還有多項整合的功能，像是將名單整合到 Google Excel 、 Mailchimp(Email 行銷系統)，甚至是 Facebook pixel 可做到再行銷廣告。

如果使用 Typeform 和 Notion API 串接的話，讓人在美美的 Typeform 表單上填寫資料，並將資料儲存在 Notion 裡，更方便管理和使用，是不是聽起來還不錯。

所以先用 Typeform 跑通，確認資料真的會進 Notion，再上程式化流程，對新手最穩。

這個案例的目標是「表單送出後，Notion 會新增一列，而且欄位型別不會亂掉」。

你做完這個案例，應該得到 3 個明確結果：

1. 每送出一份表單，Notion 會新增一列（代表串接真的寫進去了）。
2. 每個欄位都落在正確型別（例如 Email 進 email，Need 進 select/multi_select）。
3. 你已經有一組「真實資料樣本」，可拿來驗證後續 n8n 流程。

建議先把 Notion 資料來源做成這種結構（範例）：

Notion 欄位	建議型別	來源（Typeform）	常見踩坑
Name	title	短文字	欄位名稱不一致導致寫不進
Email	email	Email	存成 rich_text 後續難驗證
Need	select / multi_select	單選/多選	選項值不一致造成落空
Source	select	隱藏欄位/UTM	忘了設預設值，變成大量空值
Note	rich_text	長文字	長度過長或塞入不必要內容

使用上也很容易，只要這樣做：

Step1. 加入會員( 免費加入會員 )

Step2. 新增表單

Step3. 設定 Connect 到 Notion

表單完成後，我們要將表單 Connect 到 Notion。

在 Notion 設定資料庫，這樣就完成。

再後，不要忘了新增一個 Notion Database ，並且將 Notion Connecting 設定好。

案例 2：用 n8n + curl 跑一次 API（程式化驗證）

短答：當 Typeform 已經跑通，你就可以用 n8n + curl 驗證「不用表單，也能直接用 API 寫進 Notion」。

先準備環境變數：

export NOTION_TOKEN="<YOUR_NOTION_TOKEN>"
export NOTION_VERSION="2025-09-03"

用 curl 找出 Page 中帶有 Notion 關鍵字

Copy cURL

curl -sS https://api.notion.com/v1/search \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: $NOTION_VERSION" \
  -H "Content-Type: application/json" \
  --data '{"query":"notion","filter":{"value":"page","property":"object"}}'

點擊 Import cURL

輸入你的 API KEY，Notion-Version = 2025-09-03，點擊 Execute Step。成功的話，就會像右側出現你的 Notion Page。

如果你想看 n8n 的完整圖解（Webhook 設定、按鈕觸發、排錯重點），可直接接這篇：別再熬夜排程！用 Notion Webhook 5 分鐘打造社群平台發布機器 n8n 為例。

401/403/404/Validation Error 怎麼排查？

短答：先看狀態碼，再對應權限、ID、欄位型別，5 分鐘內通常能定位問題。

錯誤	最常見原因	快速修復
401 unauthorized	Token 錯、漏 Bearer	重貼 Token，確認 Header 格式
403 forbidden	沒把資料來源分享給 Integration	到 Connections 補授權
404 object_not_found	ID 貼錯或資源不存在	先用 Search 重新取 ID
validation_error	欄位名或型別不符	回 Notion 檢查 property 名稱與 type

Notion API Token 怎麼保存才安全？

短答：Token 當密碼管理，不要硬寫在前端或公開文章。

建議實務：

1. 放在 .env（例如 NOTION_API_KEY）。
2. CI/CD 用 Secrets 管理。
3. 定期輪替，舊 Token 失效。
4. 依環境拆分（dev/staging/prod 不共用）。

下一步行動

1. 先跑 案例 1，用 Typeform 產生第一批可驗證資料。
2. 再跑 案例 2，用 curl 驗證 n8n/API 寫入流程。
3. 想看 n8n 完整圖解可直接看：別再熬夜排程！用 Notion Webhook 5 分鐘打造社群平台發布機器 n8n 為例。

---

常見問題 FAQ

Q: Notion API Token 要去哪裡拿？

到 Notion Integrations 建立 Internal Integration 後即可取得 Token。取得後仍要把目標資料來源分享給該 Integration，否則常見 403。

Q: 為什麼我用 curl 還是遇到 401/403？

401 多半是 Token 或 Header 格式錯；403 多半是沒有做 Connections 授權。先檢查 Authorization 與 Notion-Version，再檢查資料來源權限。

Q: Data Source ID 要怎麼找？

建議先用 POST /v1/search 找，避免手動從網址截錯 ID。若手動複製，也要確認是你要操作的同一個資料來源。

Q: Typeform 串接後為什麼欄位會寫不進 Notion？

通常是欄位型別不一致（例如 Notion 要 select，Typeform 丟純文字）或必填欄位未映射。先用 3 筆測試資料逐欄驗證。

Q: Token 很敏感嗎？怎麼保存比較安全？

很敏感。請放環境變數或 Secrets Manager，不要放在公開 repo、前端程式碼或可被外部讀取的設定檔。

Q: 不想寫程式，可以怎麼入門 Notion 自動化？

可以先從 no-code 路線開始（Typeform、Zapier、Make、n8n），先把資料流跑通，再逐步換成 API 客製流程。

---

資料來源

資料最後查核日期：2026-02-27

• Notion Developers: Introduction
• Notion Developers: Search
• Notion Developers: Query a data source
• Notion Developers: Create a page
• Notion Developers: Databases (deprecated notice)