توثيق واجهة البرمجة (API Documentation)

مرحباً بك في بوابة المطورين الخاصة باستوديو المنتجات. تتيح لك هذه الواجهة استخدام الاستوديو كمحرك لخدمة المنتجات الرقمية والتطبيقات المصغرة برمجياً. يعمل هذا التطبيق كـ API Gateway و Proxy لخدمة صفحات الويب المولدة بروابط ثابتة، مما يتيح لك دمجها في أنظمتك وتطبيقاتك الخارجية فوراً.

💡 معلومة: تعمل كافة المسارات المعروضة أدناه بشكل نسبي على نفس مضيف الاستوديو.

🏗️ توليد منتج جديد برمجياً

يتيح لك هذا المسار توليد منتج جديد كلياً (صفحة HTML مخصصة) برمجياً عبر الـ LLM، وسيتم تخزينه تلقائياً في قاعدة البيانات وحجز معرف فريد (UUID) ورابط خدمة خاص به.

POST /generate

المعامل	النوع	الوصف
prompt	String (مطلوب)	الوصف التفصيلي للمنتج المطلوب توليده.
name	String (اختياري)	اسم المنتج لحفظه في الاستوديو. إذا لم يُرسل، يتم استخلاص الاسم من الوصف تلقائياً.
skillId	String (اختياري)	معرف المهارة (Skill) المراد استخدامها كمحرك توليد.
designSystemId	String (اختياري)	معرف نظام التصميم لتطبيق سمات الألوان والخطوط.

مثال على الطلب (cURL):

curl -X POST "http://localhost:3456/generate" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "صفحة هبوط لتطبيق توصيل طعام باللغة العربية مع زر اتصال بارز وكروت لعرض المطاعم", "name": "أكلاوي لايت"}'

الاستجابة المتوقعة (JSON):

{
  "id": "e3b320d4-e655-400e-9ee0-e5bf7e0b5f54",
  "url": "/products/e3b320d4-e655-400e-9ee0-e5bf7e0b5f54",
  "html": "<!DOCTYPE html><html>...</html>",
  "meta": {
    "name": "أكلاوي لايت",
    "skillId": null,
    "designSystemId": null
  }
}

📦 سرد المنتجات المولدة

يسترجع هذا المسار قائمة بجميع المنتجات التي تم توليدها مسبقاً في الاستوديو. لا ترجع هذه الاستجابة كود الـ HTML لكل منتج حرصاً على حجم Payload، وإنما ترجع البيانات الفوقية فقط.

GET /api/products

مثال على الطلب (cURL):

curl -X GET "http://localhost:3456/api/products"

⚙️ استرجاع تفاصيل منتج محدد

يسترجع هذا المسار تفاصيل منتج مولد بالكامل، بما في ذلك كود الـ HTML الكامل الخاص بالصفحة، والبيانات الفوقية وتاريخ التوليد وحالته.

GET /api/products/<product_id>

مثال على الطلب (cURL):

curl -X GET "http://localhost:3456/api/products/e3b320d4-e655-400e-9ee0-e5bf7e0b5f54"

🌐 الاستضافة المباشرة للمنتج (Raw HTML View)

يمثل هذا الـ endpoint المحرك الرئيسي لخدمة المنتجات. يقوم الاستوديو هنا بلعب دور الـ Proxy وتقديم محتوى الـ HTML مباشرة للمتصفح بـ Header مناسب Content-Type: text/html. يمكنك مشاركة هذا الرابط كصفحة ويب مستقلة أو تضمينها عبر <iframe> داخل تطبيقاتك الخارجية مباشرة.

GET /products/<product_id>

مثال على الاستدعاء المباشر في المتصفح:

http://localhost:3456/products/e3b320d4-e655-400e-9ee0-e5bf7e0b5f54

🗑️ حذف منتج من الاستوديو

يتيح لك هذا المسار مسح المنتج نهائياً من قاعدة البيانات وإيقاف الرابط المباشر الخاص به.

DELETE /api/products/<product_id>

مثال على الطلب (cURL):

curl -X DELETE "http://localhost:3456/api/products/e3b320d4-e655-400e-9ee0-e5bf7e0b5f54"