如果您希望将外部系统中的数据自动同步到 Notion 数据库，或让 Notion 中的内容被其他程序实时读取，则需通过 Notion 官方 API 实现双向通信。以下是完成 Notion Integration 创建与数据同步的具体操作步骤：
一、创建 Notion Integration 并获取 Bot Token
Notion API 以 Integration（集成）为身份凭证，每个 Integration 对应一个独立的 Bot Token，用于授权访问指定页面和数据库。
1、登录 https://www.notion.so/my-integrations 页面，点击右上角 “+ New integration” 按钮。
2、在弹出表单中填写 Integration 名称（如 “AutoSync-Webhook”），选择对应的 Workspace，点击 “Submit”。
3、在跳转后的详情页中，复制 “Internal Integration Token” 字段下的完整字符串，该值即为后续调用 API 所需的 Bearer Token。
4、向下滚动至 “Capabilities” 区域，勾选 “Read content” 和 “Write content”，确保具备读写权限。
5、在 “User Connections” 区域点击 “Connect to Notion”，使用当前登录账号完成授权绑定。
二、共享数据库并添加 Integration 为成员
Notion API 无法默认访问任意数据库，必须将目标数据库显式共享给已创建的 Integration，否则会返回 401 或 404 错误。
1、打开需要同步的目标数据库页面，点击右上角 “Share” 按钮。
2、在弹出面板中输入 Integration 名称（如 “AutoSync-Webhook”），从下拉列表中选择对应条目。
3、点击右侧下拉菜单，为该 Integration 分配 “Can edit” 权限。
4、点击 “Invite” 完成添加，此时 Integration 即可对该数据库执行查询与写入操作。
三、获取数据库 ID 并验证可访问性
所有数据库操作均需使用唯一且固定的 database_id，该 ID 隐藏于页面 URL 中，需手动提取并验证其有效性。
1、打开目标数据库页面，查看浏览器地址栏 URL，格式为：https://www.notion.so/xxx/yyy-database_id-zzz，其中横线分隔的 32 位小写字母与数字组合即为 database_id。
2、使用 curl 命令测试读取权限：curl -X GET "https://api.notion.com/v1/databases/{database_id}" -H "Authorization: Bearer {token}" -H "Notion-Version: 2022-06-28"。
3、若响应状态码为 200 且返回包含 title、properties 等字段的 JSON，则说明 database_id 正确且 Integration 已获授权。
四、使用 API 向数据库插入新条目
通过 POST 请求向数据库追加记录，需构造符合 Notion Schema 的 JSON 结构体，每项 property 必须与数据库字段类型严格匹配。
1、确认数据库中各字段名称及类型，例如 “Name”（title）、“Status”（select）、“Due Date”（date）。
2、构建请求体，其中 properties 下的每个键名必须与数据库字段名完全一致（区分大小写）：
{"parent": {"database_id": "xxx"}, "properties": {"Name": {"title": [{"text": {"content": "New Task"}}]}, "Status": {"select": {"name": "To Do"}}, "Due Date": {"date": {"start": "2024-07-15"}}}}
3、发送 POST 请求：curl -X POST "https://api.notion.com/v1/pages" -H "Authorization: Bearer {token}" -H "Notion-Version: 2022-06-28" -H "Content-Type: application/json" -d @payload.json。
五、监听外部变更并触发自动抓取
Notion API 不支持服务端推送（Webhook），需由外部系统主动轮询或借助第三方服务实现事件驱动同步。
1、部署定时任务（如 cron job），每隔 5 分钟调用 /v1/databases/{id}/query 接口，传入 filter 参数筛选 last_edited_time 变更范围。
2、比对上次同步时间戳与响应中 results 数组内各 page 的 last_edited_time 字段，识别新增或更新项。
3、对识别出的变更页面调用 /v1/pages/{page_id} 获取完整内容，解析 blocks 字段提取文本、链接、日期等结构化信息。
4、将提取的数据写入本地数据库或转发至消息队列，供下游业务系统消费。
