كيف أصل إلى واجهة برمجة التطبيقات (API) الخاصة بـ VeloCMS؟
تعرض كل مدوّنة على VeloCMS واجهة REST API بإصدار محدد تحت المسار /api/v1. صادِق برمز API لقراءة المنشورات والوسائط والأعضاء والإعدادات وكتابتها.
تعرض كل مدوّنة على VeloCMS واجهة REST API عامة تحت المسار /api/v1 على عنوان مدوّنتك نفسه (مثل https://yourblog.com/api/v1/posts). للوصول إليها، أنشئ مفتاح API من لوحة التحكم ← الإعدادات ← متقدم ← مفاتيح API، وضمّن المفتاح كرمز Bearer في ترويسة Authorization لطلباتك، وعندئذٍ تستطيع قراءة الموارد التي تسمح بها نطاقات صلاحياته وكتابتها برمجيًا — المنشورات والوسائط والتعليقات والأعضاء والمنتجات وإعدادات الموقع وWebhooks.
أين توجد وثائق API؟
تُوثَّق الواجهة بمواصفتين مقروءتين آليًا تُقدَّمان من مدوّنتك نفسها: مستند OpenAPI 3.1 على /api/v1/openapi (نقاط النهاية وأشكال الطلبات والاستجابات والنطاقات المطلوبة)، ومستند AsyncAPI 3.0 على /api/v1/asyncapi (فهرس أحداث webhook). استورد أيًّا منهما في Postman أو Insomnia أو مولّد شيفرة OpenAPI للحصول على عميل مُنمَّط. ويعرض أمر الإعداد تحت «إعداد Zapier / Make» في لوحة التحكم ← الإعدادات ← متقدم ← مفاتيح API عنوانك الأساسي بدقة. يعمل VeloCMS على خلفية PocketBase، لكنها واجهة داخلية؛ أما الواجهة العامة المدعومة للتكاملات فهي /api/v1.
كيف أصادق على طلبات API؟
أنشئ رمز API من لوحة التحكم ← الإعدادات ← متقدم ← مفاتيح API. انقر «مفتاح جديد»، وأعطه اسمًا (مثل «تكامل Zapier» أو «سكربت ترحيل»)، واختر نطاقات الصلاحيات التي تحتاج إليها («قراءة المقالات» و«كتابة المقالات» و«قراءة بيانات الأعضاء (مجهولة الهوية)» وغيرها)، ثم انقر «إنشاء مفتاح API». يُعرض الرمز مرة واحدة فقط — انسخه فورًا لأنه يُجزَّأ (hash) قبل التخزين ولا يستطيع VeloCMS عرضه مجددًا. ضمّن الرمز في ترويسة Authorization لطلباتك بالصيغة 'Bearer your-token-here'. ويمكن إلغاء الرموز فرديًا من لوحة الإعدادات نفسها دون التأثير في بقية الرموز النشطة.
ما الموارد المتاحة عبر API؟
تعرض الواجهة v1 نقاط نهاية للموارد التالية: المنشورات (عرض قائمتها وإنشاؤها)، والوسائط (عرض قائمتها ورفعها)، والتعليقات (عرض قائمتها وإنشاؤها، إضافةً إلى نقطة نهاية للإشراف بنطاق comments:moderate)، والأعضاء (عرض قائمة حسابات قرّائك وتحديثها)، وإعدادات الموقع site-settings (قراءة الإعدادات العامة للمدوّنة)، والمنتجات (الإنشاء، لمدوّنات التجارة)، وwebhooks (إدارة اشتراكات webhook واستعلام أحداث التسليم). تتطلب كل نقطة نهاية النطاق المناسب في مفتاح API الخاص بك — فمفتاح ذو نطاق posts:read لا يستطيع الوصول إلى قائمة أعضائك أو إعدادات موقعك، وتُمنح نطاقات الكتابة مثل posts:write وmembers:write بصورة منفصلة عن نطاقات القراءة.
ما حالات الاستخدام الجيدة لـ API الخاصة بـ VeloCMS؟
تتيح الواجهة طيفًا واسعًا من السيناريوهات التي لا تتيحها لوحة التحكم وحدها. فأدوات ترحيل المحتوى تستطيع إنشاء منشورات بالجملة من تصدير JSON أو CSV من منصة أخرى. ويمكن لنشرات الواجهات الأمامية بلا رأس (headless) جلب المنشورات عبر API وعرضها في قالب React أو Next.js مخصص كليًا دون استخدام قوالب VeloCMS المدمجة. ويمكن لمولّدات المواقع الساكنة مثل Astro أو Eleventy سحب منشورات VeloCMS وقت البناء لتوليد موقع ساكن بالكامل. وتستطيع سكربتات الأتمتة نشر المنشورات من قائمة محتوى، أو تحديث بيانات المنشورات الوصفية استنادًا إلى بيانات التحليلات، أو مزامنة قوائم المشتركين مع منصات التسويق عبر البريد. وهكذا يعمل VeloCMS كخلفية CMS بلا رأس كاملة، مع توفير المحرر المُدار وواجهة النشر في الوقت نفسه.
رموز API ذات صلاحيات الكتابة تمنح الأنظمة الخارجية وصولًا مباشرًا إلى بيانات مدوّنتك. تعامل معها كما تتعامل مع كلمات المرور — خزّنها في متغيرات البيئة لا في الشيفرة المصدرية، وبدّلها إن اشتبهت في انكشافها. واحذف رموز التكاملات التي لم تعد تستخدمها.