Đọc các bài viết, bộ sưu tập và mục nhật ký thay đổi bằng API Notiondesk

API Notiondesk đọc tất cả mọi thứ mà trung tâm trợ giúp của bạn xuất bản: mọi bài viết và bộ sưu tập bằng bất kỳ ngôn ngữ nào, với nội dung dưới dạng markdown, trạng thái xuất bản và trạng thái đồng bộ hóa, cùng với các mục nhật ký thay đổi đã xuất bản của bạn. Sử dụng nó để sao lưu trung tâm trợ giúp của bạn, cung cấp nội dung cho một công cụ khác hoặc kiểm tra xem bài viết nào không được đồng bộ hóa thành công.

API chỉ đọc nội dung chứ không ghi nội dung. Các bài viết và bộ sưu tập của bạn vẫn nằm trong Notion: để thay đổi một bài viết hoặc bộ sưu tập nào đó, hãy chỉnh sửa nó trong Notion và kích hoạt quá trình đồng bộ hóa .

Trong API Notiondesk, một tập hợp được gọi là một danh mục .

Chọn ngôn ngữ

Mỗi tuyến đường trên trang này đều có tham số truy vấn tùy chọn locale, ví dụ như ?locale=fr. Nếu không có tham số này, phản hồi sẽ sử dụng ngôn ngữ mặc định của trung tâm trợ giúp. Đối với các tuyến đường dạng danh sách, locale phải là một trong các ngôn ngữ mà trung tâm trợ giúp hỗ trợ: supported_locales của trung tâm trợ giúp . Hãy đọc bài viết "Hỗ trợ nhiều ngôn ngữ trong Trung tâm trợ giúp của bạn" để thêm ngôn ngữ.

Liệt kê các bài viết

Danh sách này bao gồm mọi bài viết ở mọi trạng thái, cả bản nháp và bài viết đã lưu trữ, theo thứ tự tạo ra. Duyệt qua danh sách bằng page_size và cursor, như mô tả trong các yêu cầu API Paginate và phiên bản Notiondesk .

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=100&locale=en" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "id": "1761580412",
      "title": "Connect your Notion workspace",
      "slug": "connect-your-notion-workspace",
      "status": "published",
      "categories": [
        {"id": "910000002", "name": "Connecting Notion", "slug": "connecting-notion", "locale": "en", "status": "published"}
      ],
      "tags": [{"name": "Setup", "slug": "setup"}],
      "locales_count": 2,
      "updated_at": "2026-10-18T14:39:03+00:00",
      "published_at": "2026-10-05T04:39:04+00:00",
      "locale": "en",
      "reading_time": 3,
      "views_count": 42,
      "reactions_percent": {"smiley": 50, "neutral_face": 25, "disappointed": 25},
      "source_notion_page_id": "3d5001d0-2470-8122-a1b2-c3d4e5f60789",
      "notion_article_page_url": "https://www.notion.so/3d5001d024708122a1b2c3d4e5f60789",
      "sync_in_progress": false,
      "sync_timeout": false,
      "sync_failed": false,
      "sync_error_code": null,
      "auto_translated": false
    }
  ],
  "has_more": true,
  "next_cursor": "OPAQUE_CURSOR"
}

Lưu ý: Hãy lọc kết quả trong mã của bạn để tìm tất cả các bài viết có lần đồng bộ cuối cùng thất bại, sau đó sửa lỗi trong Notion và đồng bộ lại .sync_failed: true

Đọc bài viết dưới dạng Markdown

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles/1761580412?locale=en" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "id": "1761580412",
  "type": "article",
  "title": "Connect your Notion workspace",
  "slug": "connect-your-notion-workspace",
  "text": "# Connect your Notion workspace\n\nOpen **Settings**, then **Notion**...",
  "url": "https://help.example.com/en/articles/connect-your-notion-workspace",
  "locale": "en",
  "last_updated": "2026-10-18T14:39:03+00:00",
  "category": {"id": "910000002", "title": "Connecting Notion", "slug": "connecting-notion"},
  "tags": ["setup"],
  "truncated": false,
  "author": {"name": "Ada Lovelace"},
  "status": "published",
  "content_available": true,
  "sync_in_progress": false,
  "sync_timeout": false,
  "sync_failed": false,
  "sync_error_code": null
}

Mọi trạng thái đều có thể đọc được, vì vậy bạn có thể đọc bản nháp trước khi xuất bản. Một bài viết không có bản dịch trong yêu cầu locale sẽ trả về 404 not_found.

Liệt kê các bộ sưu tập

Mỗi mục là một tập hợp các nội dung bằng ngôn ngữ được yêu cầu, theo thứ tự các tập hợp đó được tạo ra:

Xây dựng lại cây bộ sưu tập của bạn với ba trường:

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories?page_size=100" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "id": "910000001",
  "name": "Getting Started",
  "slug": "getting-started",
  "updated_at": "2026-10-18T14:39:12+00:00",
  "locale": "en",
  "is_parent": true,
  "source_notion_page_id": "5d5001d0-2470-8122-a1b2-c3d4e5f60789",
  "notion_category_page_url": "https://www.notion.so/5d5001d024708122a1b2c3d4e5f60789",
  "sync_in_progress": false,
  "sync_timeout": false,
  "sync_failed": false,
  "sync_error_code": null,
  "parent_ids": [],
  "children_ids": ["910000002"],
  "locales_count": 2,
  "status": "published",
  "auto_translated": false
}

Danh sách này không hiển thị số lượng bài viết. Để đếm số bài viết trong một bộ sưu tập, hãy liệt kê các bài viết và nhóm chúng theo categories. Tìm hiểu cách các bộ sưu tập sắp xếp trung tâm trợ giúp của bạn trong Sử dụng bộ sưu tập để sắp xếp bài viết của bạn .

Đọc một tuyển tập

Phản hồi có cấu trúc tương tự như một bài viết: type là category, title, slug, url, status, các trường đồng bộ, và text với nội dung riêng của bộ sưu tập dưới dạng markdown, trống khi không có nội dung nào.

Liệt kê các mục nhật ký thay đổi

Nhật ký thay đổi liệt kê các bài viết đã xuất bản được lưu trữ trong bộ sưu tập nhật ký thay đổi của bạn, bài mới nhất được hiển thị trước. Thiết lập nhật ký thay đổi bằng cách làm theo hướng dẫn trong trung tâm trợ giúp của bạn .

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories/910000001?locale=en" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/changelog?page_size=50&locale=en" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "id": "article:1761497350",
      "title": "Multilingual sync is now available",
      "slug": "multilingual-sync-is-now-available",
      "text": "Help centers on the Enterprise plan can now sync every configured locale in a single run instead of one language at a time.",
      "published_at": "2026-10-13T09:12:44+00:00",
      "last_updated": "2026-10-18T14:39:03+00:00",
      "tags": [],
      "url": "https://help.example.com/en/changelogs",
      "locale": "en"
    }
  ],
  "has_more": true,
  "next_cursor": "OPAQUE_CURSOR"
}

Thông tin hữu ích:

• Một mục chỉ hiển thị khi bộ sưu tập nhật ký thay đổi của nó được xuất bản bằng ngôn ngữ được yêu cầu.

• Trên trung tâm trợ giúp sử dụng tài khoản khách, danh sách chỉ hiển thị các mục mà mọi người dùng đều có thể xem.

• Danh sách chỉ hiển thị tối đa 1.000 mục mới nhất. Sau đó, has_more sẽ trở thành false ngay cả khi có các mục cũ hơn.

• Trong một số trường hợp hiếm gặp, khi xảy ra sự cố tạm thời, danh sách có thể bị bỏ qua hoặc lặp lại một mục. Hãy đọc lại sau để có danh sách đầy đủ.

Lỗi

Mỗi tuyến đường cũng có thể trả lời invalid_version, authentication_error, rate_limited và internal_error. 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

Tiếp theo là gì?

• Trigger Notion đồng bộ với API Notiondesk

• Quản lý ngôn ngữ và dịch tự động bằng API Notiondesk

• Tự động hóa các tác vụ thường gặp trong trung tâm trợ giúp bằng API Notiondesk