API Notiondesk cho phép bạn xuất bản các chỉnh sửa Notion ngay khi chúng sẵn sàng: đồng bộ toàn bộ trung tâm trợ giúp, một bộ sưu tập hoặc một bài viết, từ một tập lệnh, một quy trình CI hoặc công cụ của riêng bạn. Bạn cũng có thể bật hoặc tắt tính năng đồng bộ theo lịch trình. Nội dung của bạn vẫn được lưu trữ trong Notion; quá trình đồng bộ sẽ đọc lại nội dung đó và xuất bản các thay đổi.
| Phương pháp | Con đường | Phạm vi | Làm |
|---|---|---|---|
POST | /sites/{site_id}/sync | sync | Đồng bộ hóa toàn bộ trung tâm trợ giúp |
POST | /sites/{site_id}/categories/{category_id}/sync | sync | Đồng bộ hóa một bộ sưu tập và các bài viết trong đó. |
POST | /sites/{site_id}/articles/{article_id}/sync | sync | Đồng bộ một bài viết |
PATCH | /sites/{site_id}/settings/auto-sync | sync | Bật hoặc tắt tính năng đồng bộ hóa theo lịch trình. |
Bạn mới làm quen với việc đồng bộ hóa? Trước tiên, hãy đọc Hướng dẫn đồng bộ hóa trung tâm trợ giúp của bạn với Notion .
Đồng bộ hóa toàn bộ trung tâm trợ giúp
Notiondesk đọc lại mọi bài viết và bộ sưu tập từ Notion và xuất bản các thay đổi. Tuyến đường trả lời 204 No Content ngay khi quá trình đồng bộ được xếp vào hàng đợi, và quá trình đồng bộ chạy ngầm.
Chỉ có một quá trình đồng bộ hóa trang web chạy tại một thời điểm. Trong khi quá trình đồng bộ hóa trung tâm trợ giúp đang được xếp hàng chờ hoặc đang chạy, cho dù được lên lịch, bắt đầu từ bảng điều khiển hay bắt đầu thông qua API, một trình kích hoạt khác sẽ trả về mã lỗi 409 conflict_error. Hãy đợi vài phút và kích hoạt lại.
Nội dung không thay đổi kể từ lần đồng bộ cuối cùng sẽ không được dịch lại.
Đồng bộ hóa một bộ sưu tập
Sử dụng id của bộ sưu tập từ danh sách bộ sưu tập . Notiondesk đọc lại bộ sưu tập và từng bài viết của nó từ Notion, sau đó chỉ xuất bản những bài viết đã được chỉnh sửa kể từ lần đồng bộ cuối cùng. Những bài viết không thay đổi sẽ không được dịch hoặc tính phí lại.
Đồng bộ một bài viết
Sử dụng id của bài viết từ danh sách bài viết .
curl -i -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Idempotency-Key: 9b2e4c1a-sync-after-notion-edit"curl -i -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories/1761493027/sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Idempotency-Key: 2c8e5b7d-sync-billing"curl -i -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles/1761580412/sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Idempotency-Key: 4d7a0f3e-sync-getting-started"Sự khác biệt giữa đồng bộ hóa bộ sưu tập và bài viết so với đồng bộ hóa trang web
| Đồng bộ hóa trang web | Đồng bộ hóa bộ sưu tập hoặc bài viết | |
|---|---|---|
| Đọc từ Notion | Mỗi bài viết và bộ sưu tập | Một tuyển tập và các bài viết trong đó, hoặc một bài viết |
| Trong khi đó, một quá trình đồng bộ khác của cùng một mục đang diễn ra. | Câu trả lời 409 __ĐÃ BẢO LƯU_45__ | Xếp hàng một lần đồng bộ khác. Nó không bao giờ trả lời conflict_error |
| Bị giới hạn bởi | Đồng bộ từng cái một | Ngân sách ghi của khóa của bạn là 20 yêu cầu mỗi phút. |
Mỗi lần đồng bộ hoàn tất sẽ làm mới toàn bộ trung tâm trợ giúp. Kích hoạt đồng bộ một lần sau mỗi lần chỉnh sửa trong Notion, không phải theo hẹn giờ. Để cập nhật thường xuyên, hãy sử dụng đồng bộ theo lịch trình.
Xác nhận đồng bộ hóa
Trình kích hoạt đồng bộ trả lời 204 khi quá trình đồng bộ được xếp vào hàng đợi, chứ không phải khi nó kết thúc. Các quá trình đồng bộ được bắt đầu thông qua API sẽ không xuất hiện trong trạng thái đồng bộ , trạng thái này chỉ liệt kê các lần chạy đã lên lịch.
Để xác nhận việc đồng bộ hóa, hãy đọc nội dung mà nó công bố:
- Kích hoạt quá trình đồng bộ và ghi lại thời gian.
- Đọc bài viết đã chỉnh sửa với
GET /sites/{site_id}/articles/{article_id}mỗi 30 giây.
- Dừng lại khi
last_updatedmuộn hơn thời gian bạn đã ghi chú, hoặctexthiển thị chỉnh sửa của bạn.
- Nếu
sync_failedlàtrue,sync_error_codesẽ cho biết lý do. Hãy sửa bài viết trong Notion và đồng bộ lại.
Bật hoặc tắt tính năng đồng bộ theo lịch trình
curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/auto-sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Content-Type: application/json" \
-d '{"auto_sync_enabled": true}'| Cánh đồng | Kiểu | Ghi chú |
|---|---|---|
auto_sync_enabled | boolean | Liệu Notiondesk có được đồng bộ từ Notion theo lịch trình hay không. |
Tuyến đường trả lời 204 No Content. Đọc trạng thái mới trong auto_sync_enabled của trung tâm trợ giúp và lịch trình trong trạng thái đồng bộ của nó.
- Gửi các giá trị boolean JSON
truehoặcfalse. Các giá trị0và"false"được đọc làtrue.
- Tần số đồng bộ không thể thay đổi thông qua API: gửi
auto_sync_frequencysẽ trả về 400validation_error. Hãy thay đổi nó trong bảng điều khiển.
- Gói cước của bạn phải bao gồm tính năng đồng bộ hóa theo lịch trình.
- Việc bật tính năng đồng bộ theo lịch trình cho phép các bản dịch tự động bắt đầu được tính phí ngay cả khi tính năng dịch tự động đang hoạt động.
Tuyến đường này cần phạm vi sync, chứ không phải write, vì nó quyết định khi nào các quá trình đồng bộ hóa tự động chạy.
Lỗi
| Trạng thái | Khi | code |
|---|---|---|
| 400 | Chỉ đồng bộ tự động: phần thân chứa một trường không xác định, bao gồm auto_sync_frequency | validation_error |
| 403 | Khóa này thiếu phạm vi sync | insufficient_scope |
| 403 | Trung tâm trợ giúp đã bị vô hiệu hóa, gói dịch vụ của bạn không bao gồm tính năng đồng bộ hóa theo lịch trình hoặc người tạo khóa không thể đồng bộ hóa trung tâm trợ giúp này. | permission_denied |
| 404 | Trung tâm trợ giúp, bộ sưu tập hoặc bài viết này không tồn tại trong không gian làm việc của bạn. | not_found |
| 409 | Chỉ đồng bộ hóa trang web: quá trình đồng bộ hóa trung tâm trợ giúp đã được xếp vào hàng đợi hoặc đang chạy. | conflict_error |
| 409 | Một yêu cầu có cùng mã Idempotency-Key vẫn đang được xử lý. | request_in_progress |
conflict_error và request_in_progress là các lỗi khác nhau nhưng có cùng trạng thái: rẽ nhánh tại code. Xem Xử lý lỗi API Notiondesk, giới hạn tỷ lệ và số lần thử lại .
Câu hỏi thường gặp
Liệu việc thử lại thao tác đồng bộ hóa có an toàn không?
Vâng, với Idempotency-Key. Thử lại với cùng một khóa sẽ trả lời 204 bằng X-Idempotent-Replay: true và không xếp hàng gì cả, ngay cả khi quá trình đồng bộ đầu tiên vẫn đang chạy.
Làm sao tôi biết khi nào quá trình đồng bộ hóa hoàn tất?
Đọc bài viết hoặc bộ sưu tập đã được đồng bộ cho đến khi last_updated muộn hơn thời gian kích hoạt của bạn, hoặc text hiển thị chỉnh sửa của bạn. Không nên chỉ dựa vào sync_in_progress: nó có thể vẫn ở trạng thái false trong vài giây sau khi kích hoạt, trước khi quá trình đồng bộ được xếp hàng bắt đầu. Các quá trình đồng bộ được kích hoạt bởi API không được liệt kê trong trạng thái đồng bộ.
Tôi nên đồng bộ một bài viết hay toàn bộ trung tâm trợ giúp?
Đồng bộ hóa một bài viết sau khi bạn chỉnh sửa bài viết đó, và đồng bộ hóa một bộ sưu tập sau khi bạn chỉnh sửa nhiều bài viết trong đó. Đồng bộ hóa toàn bộ trung tâm trợ giúp sau những thay đổi lớn, chẳng hạn như di chuyển bài viết giữa các bộ sưu tập.
Tôi có thể đồng bộ hóa từ GitHub Actions không?
Vâng. Lưu khóa đó dưới dạng bí mật kho lưu trữ và gọi tuyến đồng bộ hóa trang web trong một bước quy trình làm việc. Xem Tự động hóa các tác vụ trung tâm trợ giúp thông thường với API Notiondesk .