Skip to Content
Tài liệu dành cho nhà phát triển

Sử dụng API trang web / CMS

Xác thực, chỉnh sửa và xuất bản nội dung qua API v1 trên nền tảng hoặc CMS độc lập.

Sử dụng API trang web / CMS

API v1 kết nối tích hợp bên ngoài với dữ liệu trang web và CMS. Đọc hợp đồng của bản triển khai, tạo khóa có quyền hạn giới hạn rồi lưu bản nháp với bảo vệ phiên bản.

Chọn dịch vụ và cách triển khai

Đặt QOKIT_API_URL thành origin dịch vụ API (cục bộ là http://localhost:7777) hoặc bản cài đặt độc lập. QOKIT_PROJECT_ID là ID dự án; bản xuất lưu trong data/seed.json dưới project.id. Đọc công khai dùng slug dự án.

Triển khaiKhả năng
Nền tảngQuản lý CMS, xuất và xuất bản trên nền tảng
cms-managedQuản lý CMS cục bộ và kết xuất trang web
cms-onlyQuản lý CMS cục bộ và đọc headless công khai; không kết xuất trang web
site-onlyTrang HTML và tài nguyên tĩnh; không có API runtime

Khám phá hợp đồng

Mỗi dịch vụ chỉ công bố thao tác được hỗ trợ. Thao tác khác trả về 404. API 1.0 giữ tương thích với tuyến cũ không có phiên bản.

Đường dẫnMục đích
GET /v1/openapi.jsonOpenAPI 3.1: thân yêu cầu, phản hồi, quyền và điều kiện tiên quyết
GET /v1/capabilitiesPhiên bản API, kiểu triển khai và thao tác hỗ trợ
GET /v1/sdk/client.mjsClient JavaScript không phụ thuộc
GET /v1/sdk/client.d.mtsKhai báo TypeScript tương ứng

Tạo khóa API

Dùng accessToken sau khi hoàn tất đăng nhập nền tảng làm SESSION_TOKEN. Tài khoản cần quyền quản lý cài đặt trang web. Hoàn tất xác thực cần thiết trước khi cấp khóa.

curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'

Với CMS độc lập, đăng nhập bằng email và mật khẩu chủ bản triển khai, lưu Cookie phiên rồi tạo khóa:

curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'

Chỉ khi tạo mới trả về token. Lưu trong biến máy chủ QOKIT_SITE_API_KEY; yêu cầu dùng token Bearer bắt đầu bằng qk_site_. Thời hạn mặc định 90 ngày, tùy chỉnh 1–365 ngày, tối đa 50 khóa hoạt động mỗi dự án. Dùng phiên có quyền quản lý cài đặt để liệt kê qua GET /v1/projects/{id}/api-keys và thu hồi qua DELETE /v1/projects/{id}/api-keys/{keyId}.

Chỉ chọn quyền cần thiết. Mỗi yêu cầu kiểm tra lại quyền truy cập hiện tại của người tạo. Hết hạn, thu hồi và đổi vai trò có hiệu lực với yêu cầu tiếp theo. Khóa API không quản lý khóa khác.

ScopeMục đích
content:read / content:writeĐọc / sửa bộ sưu tập và mục
content:publishXuất bản rõ ràng và thao tác ghi xuất bản mục
pages:read / pages:writeĐọc runtime / sửa nội dung, cấu trúc, SEO và biểu mẫu
media:read / media:writeĐọc / quản lý media và thư mục
settings:read / settings:writeĐọc / sửa cài đặt trang web
users:read / users:writeĐọc / quản lý người dùng CMS
leads:read / leads:write / analytics:readĐọc / cập nhật khách hàng tiềm năng và bảng điều khiển CMS
marketing:read / marketing:writeĐọc / tạo nội dung tiếp thị
deployments:read / deployments:writeTác vụ xuất và xuất bản nền tảng
sync:write / updates:read / updates:writeĐồng bộ và cập nhật có chữ ký của cài đặt độc lập

Lưu bản nháp bằng SDK

Gói workspace là @qokit/site-api; chưa được phát hành lên npm. Với dự án ngoài, tải hai tệp client vào sdk. Bản xuất mới đã có sẵn.

mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mts

Ví dụ cần content:read và content:write. Thay en bằng ngôn ngữ dự án đã bật. Ví dụ tạo bộ sưu tập mới; lần chạy sau dùng lại ID bộ sưu tập có sẵn.

import { createSiteApiClient } from './sdk/client.mjs';

const api = createSiteApiClient({
  baseUrl: process.env.QOKIT_API_URL,
  projectId: process.env.QOKIT_PROJECT_ID,
  token: process.env.QOKIT_SITE_API_KEY
});

const collection = await api.collections.create({
  key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
  title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
  expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);

Lưu bản nháp giữ nguyên ảnh chụp công khai trước đó của mục đã xuất bản. Sau khi xem xét, khóa có content:publish có thể xuất bản rõ ràng phiên bản đã lưu. Sửa trang trên nền tảng vẫn là bản nháp cho đến khi hoàn tất xuất bản trang web.

await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });

Để khôi phục, đọc api.entries.revisions(id) rồi gọi api.entries.restore(id, revisionId, { expectedUpdatedAt }). Thao tác khác dùng api.request(path, options), hỗ trợ idempotencyKey. Client không tự thử lại thao tác ghi.

Tuyến quản lý

Thêm tiền tố /v1/projects/{id} vào các đường dẫn này. OpenAPI liệt kê thao tác, trường và yêu cầu theo bản triển khai. DELETE lưu trữ bộ sưu tập, mục và media.

Đường dẫnPhương thức
/cms/collectionsGET, POST
/cms/collections/{collectionId}PUT, DELETE
/cms/collections/{collectionId}/entriesGET, POST
/cms/entries/{entryId}GET, PUT, DELETE
/cms/entries/{entryId}/publishPOST
/cms/entries/{entryId}/revisionsGET
/cms/entries/{entryId}/revisions/{revisionId}/restorePOST
/cms/media, /cms/media/foldersGET, POST
/cms/media/{assetId}, /cms/media/folders/{folderId}PUT, DELETE
/runtime, /content/{locale}GET; PUT /content/{locale}
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/formsPOST, DELETE, PUT, PUT
/cms/settingsGET, PUT
/cms/users, /cms/users/{memberId}GET / POST, PUT / DELETE
/leads, /leads/{leadId}GET, PUT

Media nền tảng hỗ trợ đăng ký URL và chuẩn bị tải lên; tải lên độc lập dùng fileName, contentType và contentBase64, giới hạn 10 MB và kiểm tra chữ ký tệp. Thay đổi người dùng nền tảng cần Idempotency-Key; người dùng cục bộ cần mật khẩu 12–1024 ký tự. CSV, ghi hàng loạt và liên kết bản dịch là mở rộng nền tảng.

Phiên bản, phân trang và lỗi

Cập nhật, lưu trữ và khôi phục sửa đổi cần expectedUpdatedAt lấy từ updatedAt đọc gần nhất. Thiếu phiên bản trả về 428; phiên bản cũ trả về 409.

Với cấu trúc, SEO và biểu mẫu, đọc GET /v1/projects/{id}/runtime rồi gửi content.updatedAt và siteVersion.updatedAt thành baseContentUpdatedAt và baseSiteVersionUpdatedAt. Kiểm tra sửa đổi Builder và phiên thuê chỉnh sửa đang hoạt động vẫn áp dụng trên nền tảng.

Danh sách mặc định page=1&pageSize=24, tối đa 100 mục mỗi trang. Quản lý trả về items, công khai trả về entries. Sửa đổi và thư mục trả về mảng. Đọc mọi trang khi xuất nội dung.

{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}

Phản hồi có X-Request-Id và X-Qokit-Api-Version. Lỗi có mã ổn định và ID yêu cầu:

{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}

Với 401, kiểm tra khóa; với 403, kiểm tra quyền và truy cập của người tạo. Với 409, đọc lại và so sánh thay đổi; với 428, bổ sung phiên bản. Với 429, tuân theo Retry-After. Giới hạn 300 yêu cầu mỗi phút theo khóa/địa chỉ, cộng giới hạn IP và ghi của nền tảng.

Cấu hình cài đặt độc lập

Tích hợp trình duyệt nền tảng dùng CORS_ALLOWED_ORIGINS. Yêu cầu trình duyệt độc lập có khóa cần origin chính xác trong SITE_API_ALLOWED_ORIGINS; quản lý Cookie vẫn cùng origin. Đọc CMS công khai cũng có thể dùng CMS_ALLOWED_ORIGINS. Cấu hình CMS_PUBLIC_URL cho URL media CMS-only.

Sao lưu toàn bộ thư mục dữ liệu và tệp tải lên, gồm tệp riêng data/api-security.json và data/api-revisions.json. Mật khẩu và khóa lưu dạng hash cục bộ. Mỗi thư mục chỉ có một tiến trình Node ghi.

Bản xuất cũ nhận v1 qua cập nhật runtime có chữ ký. Sau nâng cấp, tải hợp đồng và client hiện tại qua HTTP; tệp trong gói là ảnh chụp tại thời điểm xuất.

Để đọc công khai không cần thông tin xác thực, xem Gọi API nội dung công khai.

Hướng dẫn này có hữu ích không?

Cập nhật lần cuối vào

Trong trang này