استخدام API الموقع / CMS
المصادقة وتحرير المحتوى ونشره عبر API v1 على المنصة أو CMS مستقل.
استخدام API الموقع / CMS
يربط API v1 التكاملات الخارجية ببيانات الموقع وCMS. اقرأ عقد النشر، ثم أنشئ مفتاحاً بصلاحيات محدودة واحفظ مسودة مع حماية الإصدار.
اختيار الخدمة ونوع النشر
اضبط QOKIT_API_URL على أصل خدمة API (محلياً http://localhost:7777) أو التثبيت المستقل. يمثّل QOKIT_PROJECT_ID معرّف المشروع؛ يحفظه التصدير في data/seed.json باسم project.id. تستخدم القراءة العامة قيمة slug للمشروع.
| النشر | الإمكانات |
|---|---|
| المنصة | إدارة CMS والتصدير والنشر على المنصة |
cms-managed | إدارة CMS محلياً وعرض الموقع |
cms-only | إدارة CMS محلياً وقراءة عامة headless؛ دون عرض الموقع |
site-only | صفحات HTML وموارد ثابتة؛ دون API وقت التشغيل |
اكتشاف العقد
تعلن كل خدمة العمليات المدعومة فقط. تعيد العمليات الأخرى 404. يحافظ API 1.0 على توافق المسارات السابقة دون إصدار.
| المسار | الغرض |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: أجسام الطلبات والاستجابات والصلاحيات والشروط المسبقة |
GET /v1/capabilities | إصدار API ونوع النشر والعمليات المدعومة |
GET /v1/sdk/client.mjs | عميل JavaScript دون تبعيات |
GET /v1/sdk/client.d.mts | تعريفات TypeScript المطابقة |
إنشاء مفتاح API
استخدم accessToken الناتج عن تسجيل دخول مكتمل للمنصة بوصفه SESSION_TOKEN. يحتاج الحساب صلاحية إدارة إعدادات الموقع. أكمل المصادقة المطلوبة قبل إصدار المفتاح.
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}'في CMS مستقل، سجّل الدخول ببريد مالك النشر وكلمة مروره، واحفظ Cookie الجلسة ثم أنشئ المفتاح:
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}'يعيد الإنشاء token مرة واحدة. احفظه في متغير الخادم QOKIT_SITE_API_KEY؛ تستخدم الطلبات رموز Bearer تبدأ بـ qk_site_. الصلاحية الافتراضية 90 يوماً ويمكن تحديد 1–365 يوماً، مع 50 مفتاحاً نشطاً كحد أقصى لكل مشروع. استخدم جلسة ذات صلاحية إدارة الإعدادات لعرضها عبر GET /v1/projects/{id}/api-keys وإلغائها عبر DELETE /v1/projects/{id}/api-keys/{keyId}.
اختر الصلاحيات المطلوبة فقط. تُفحص صلاحيات المنشئ وإمكانية وصوله الحالية في كل طلب. يسري انتهاء الصلاحية والإلغاء وتغيير الدور على الطلبات التالية. لا تدير مفاتيح API مفاتيح أخرى.
| Scope | الغرض |
|---|---|
content:read / content:write | قراءة / تحرير المجموعات والمدخلات |
content:publish | النشر الصريح وعمليات الكتابة التي تنشر المدخلات |
pages:read / pages:write | قراءة runtime / تحرير المحتوى والبنية وSEO والنماذج |
media:read / media:write | قراءة / إدارة الوسائط والمجلدات |
settings:read / settings:write | قراءة / تعديل إعدادات الموقع |
users:read / users:write | قراءة / إدارة مستخدمي CMS |
leads:read / leads:write / analytics:read | قراءة / تحديث العملاء المحتملين وقراءة لوحة CMS |
marketing:read / marketing:write | قراءة / توليد المحتوى التسويقي |
deployments:read / deployments:write | مهام التصدير والنشر على المنصة |
sync:write / updates:read / updates:write | المزامنة والتحديثات الموقعة للتثبيتات المستقلة |
حفظ مسودة باستخدام SDK
حزمة workspace هي @qokit/site-api ولم تُنشر على npm بعد. للمشاريع الخارجية، نزّل ملفّي العميل إلى sdk. تتضمنهما التصديرات الجديدة.
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يتطلب المثال content:read وcontent:write. استبدل en بلغة مفعّلة في المشروع. ينشئ المثال مجموعة جديدة؛ استخدم معرّف مجموعة موجودة في التشغيل اللاحق.
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);يحافظ حفظ المسودة على اللقطة العامة السابقة للمدخل المنشور. بعد المراجعة، يمكن لمفتاح يحمل content:publish نشر الإصدار المحفوظ صراحةً. تبقى تعديلات صفحات المنصة مسودات حتى اكتمال نشر الموقع.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });للاستعادة، اقرأ api.entries.revisions(id) ثم استدعِ api.entries.restore(id, revisionId, { expectedUpdatedAt }). استخدم api.request(path, options) للعمليات الأخرى مع دعم idempotencyKey. لا يعيد العميل محاولات الكتابة تلقائياً.
مسارات الإدارة
أضف البادئة /v1/projects/{id} لهذه المسارات. يذكر OpenAPI جميع العمليات والحقول ومتطلبات كل نشر. يؤرشف DELETE المجموعات والمدخلات والوسائط.
| المسار | الطريقة |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, 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/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, PUT |
/cms/users, /cms/users/{memberId} | GET / POST, PUT / DELETE |
/leads, /leads/{leadId} | GET, PUT |
تدعم المنصة تسجيل URL وتجهيز الرفع؛ يستخدم الرفع المستقل fileName وcontentType وcontentBase64 بحد 10 MB وفحص توقيع الملف. تتطلب تغييرات مستخدمي المنصة Idempotency-Key؛ وإنشاء المستخدم المحلي كلمة مرور من 12–1024 حرفاً. CSV والكتابة المجمّعة وروابط الترجمة امتدادات للمنصة.
الإصدارات وتقسيم الصفحات والأخطاء
تتطلب التحديثات والأرشفة واستعادة المراجعات expectedUpdatedAt من آخر قيمة مقروءة لـ updatedAt. غياب الإصدار يعيد 428 والإصدار القديم يعيد 409.
للبنية وSEO والنماذج، اقرأ GET /v1/projects/{id}/runtime وأرسل content.updatedAt وsiteVersion.updatedAt باسم baseContentUpdatedAt وbaseSiteVersionUpdatedAt. تبقى فحوص مراجعة Builder وتأجير التحرير النشط مطبقة على المنصة.
تستخدم القوائم افتراضياً page=1&pageSize=24 بحد 100 عنصر لكل صفحة. تعيد قوائم الإدارة items والقوائم العامة entries. المراجعات والمجلدات تعيد مصفوفات. اقرأ جميع الصفحات عند تصدير المحتوى.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}تتضمن الاستجابات X-Request-Id وX-Qokit-Api-Version. تحمل الأخطاء رمزاً ثابتاً ومعرّف طلب:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}عند 401 افحص المفتاح؛ وعند 403 افحص الصلاحيات ووصول المنشئ. عند 409 أعد القراءة وقارن التغييرات؛ وعند 428 أرسل الإصدار. عند 429 التزم بـ Retry-After. الحد 300 طلب في الدقيقة لكل مفتاح/عنوان، مع حدود IP والكتابة الإضافية للمنصة.
إعداد التثبيت المستقل
تستخدم تكاملات متصفح المنصة CORS_ALLOWED_ORIGINS. تحتاج طلبات المتصفح المستقلة بمفتاح أصولاً دقيقة في SITE_API_ALLOWED_ORIGINS؛ وتبقى إدارة Cookie من الأصل نفسه. يمكن للقراءة العامة استخدام CMS_ALLOWED_ORIGINS. اضبط CMS_PUBLIC_URL لروابط وسائط CMS-only.
انسخ احتياطياً مجلد البيانات والملفات المرفوعة بالكامل، بما فيها الملفان الخاصان data/api-security.json وdata/api-revisions.json. تبقى كلمات المرور والمفاتيح محلياً كقيم تجزئة. تكتب عملية Node واحدة لكل مجلد بيانات.
تحصل التصديرات القديمة على v1 بتحديث runtime موقّع. بعد الترقية، نزّل العقد والعميل الحاليين عبر HTTP؛ ملفات الحزمة لقطات من وقت التصدير.
للقراءة العامة دون بيانات اعتماد، راجع استدعاء API المحتوى العام.
آخر تحديث في