Skip to Content
توثيق المطورين

استخدام 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.jsonOpenAPI 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/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

تدعم المنصة تسجيل 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 المحتوى العام.

هل كان هذا الدليل مفيداً؟

آخر تحديث في

في هذه الصفحة