توثيق التكامل في Fruga
دليل تقني للمنصّة: ربط المتاجر، ودمج تطبيقات الهاتف، ونشر تطبيقاتك الخاصة، وواجهة REST.
نظرة عامة على المنصّة
FrugalDomain منصّة تجمع عمليات الكتالوج والمخزون والمحتوى والطلبات في نظام واحد.
- أدِر بيانات متجرك من لوحة تحكّم واحدة.
- اعتمد محرّك تجارة واحداً مصدراً وحيداً للحقيقة.
- وفّر واجهات برمجية نظيفة لتطبيقات الويب وتطبيقات Flutter للهاتف.
لماذا FrugalDomain مهمّة
صُمّمت المنصّة للفرق التي تحتاج إلى تشغيل يومي سريع من لوحة إدارة واحدة.
- عمليات أسرع على المنتجات والمخزون لفريق العمل اليومي.
- خطوط مزامنة منظّمة مع المراقبة ودعم إعادة المحاولة.
- عقود API قابلة لإعادة الاستخدام للواجهة الأمامية والهاتف والتكاملات.
- عزل على مستوى المتجر، فلا يرى كل متجر إلا بياناته.
مسارات العمل الأساسية
إدارة الكتالوج
- المنتجات والمتغيّرات والمجموعات والوسوم والمورّدون وأنواع المنتجات.
- ظهور المنتجات بحسب المستودع لتقسيم قنوات البيع.
المخزون والتسعير
- إدارة المخزون والتوفّر على مستوى كل متغيّر.
- تحديث الأسعار جماعياً أو انتقائياً مع إرسال المزامنة.
الطلبات وإتمام الشراء
- احتساب إجماليات السلة من الواجهة الخلفية.
- إنشاء مسودّات طلبات كخطوة تسبق إتمام الشراء.
- إتمام مرحلة الدفع بالتحويل إلى رابط إتمام الشراء المضبوط عند تفعيله.
كيف تربط متجراً
- 1. أنشئ سجل المتجر في نظامك وفعّله.
- 2. احفظ نطاق المتجر وتوكن الوصول بأمان.
- 3. شغّل مزامنة أولية كاملة للمنتجات والمتغيّرات والمحتوى والعملاء.
- 4. فعّل مهام المزامنة المستمرة واشتراكات webhook.
- 5. تحقّق من سلامة المزامنة في لوحة التحكم قبل فتح الوصول لفريق المتجر.
استخدم هوية متجر واحدة لكل متجر، ولا تُعِد استخدام التوكنات بين المتاجر أبداً.
دمج تطبيقات Flutter للهاتف
نقاط نهاية تطبيق الهاتف تقع تحت /mobile وتتطلّب سياق المتجر. أرسل store_id دائماً، ويمكنك إرسال warehouse_name للحصول على منتجات قناة بعينها.
- التصفية بـ warehouse_name تشمل منتجات المستودع المطابق إضافةً إلى المنتجات العامة (null/empty/all).
- استخدم نقطة النهاية bootstrap أولاً لتحميل هوية المتجر والمنتجات المميّزة وطرق الدفع مسبقاً.
- استخدم نقطة النهاية quote قبل إنشاء مسودّات الطلبات لعرض إجماليات دقيقة.
GET /mobile/bootstrap?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/products?store_id={uuid}&warehouse_name=BRAND VIP WEB&per_page=20
GET /mobile/collections?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/search?store_id={uuid}&warehouse_name=BRAND VIP WEB&q=lip
POST /mobile/checkout/quote
POST /mobile/checkout/place-draft-orderالأدوات على الموقع
إلى جانب لوحة التحكم، يوفّر الموقع مجموعة من الأدوات التي تعمل في المتصفح. تعمل بالكامل على جهاز الزائر ولا يُرفع منها شيء، لذا تعمل دون اتصال بعد تحميل الصفحة.
مكتبة الأيقونات
- 324 أيقونة بصيغتي SVG وPNG، تُقدَّم عبر شبكة CDN.
- انسخ اسم الكلاس، أو نزّل ملفاً واحداً، أو ابنِ مجموعة.
- تُستخدم بسطرين: اربط ملف الأنماط، ثم استخدم كلاس الأيقونة.
المحوّلات
- الصور بين الصيغ النقطية الشائعة.
- تحويل الصوت والمستندات بتقنية WebAssembly داخل المتصفح.
- الملفات لا تغادر الجهاز أبداً، لذا لا يحدّ حجمَ المدخلات الكبيرة إلا الذاكرة المتاحة.
لوح الرسم والمحاكي
- لوح رسم متجهي مع الطبقات والتراجع والإعادة.
- محاكي لمس يسجّل ضربات الإيماءات ويتعرّف على الحروف العربية.
نشر التطبيقات
يمكن نشر التطبيقات إلى جانب الموقع. يحصل كل تطبيق على بطاقة في المعرض وصفحة توثيق خاصة ومعاينة حيّة مضمّنة، ويُقدَّم من مجلده الخاص فيحتفظ بتوجيهه وملفاته.
- 1. أضف التطبيق من لوحة التحكم (Apps)، مع اختيار نوعه وطريقة المعاينة.
- 2. اكتب أقسام التوثيق التي تظهر في صفحة التطبيق.
- 3. ابنِ التطبيق بمسار أساسي يطابق مجلده، مثل --base=/apps/my-app/
- 4. ارفع محتويات مجلد البناء إلى apps/<slug>/ على الخادم.
- 5. اجعل حالة التطبيق «منشور»، واحفظ الكتالوج، ثم أعد بناء الواجهة الأمامية.
طرق المعاينة
- مجلد فرعي: يُقدَّم على /apps/<slug>. رفع فقط، دون أي إعداد للاستضافة.
- نطاق فرعي: وجّه جذر المستندات لنطاق فرعي إلى مجلد التطبيق وابنِه بالمسار الأساسي "/".
- خارجي: التطبيق مستضاف في مكان آخر ويرتبط به المعرض.
التوجيه
- قاعدة إعادة الكتابة في الموقع تستثني /apps/<slug>/... لكي تُفتح الروابط العميقة داخل التطبيق.
- التطبيق الذي له موجّه خاص في المتصفح يحتاج إلى ملف .htaccess في مجلده يشير إلى ملف index.html الخاص به.
تطبيق React أو Vue يُقدَّم من مجلد فرعي يجب بناؤه بمسار أساسي مطابق. إذا بُني بالمسار الافتراضي فسيطلب ملفاته من جذر الموقع، وسيعود كل طلب منها بالخطأ 404، وستظهر المعاينة فارغة.
دليل واجهة REST (مجموعة التكامل العامة الحالية)
استخدم طلبات واستجابات JSON. أرسل توكن Authorization حين يتطلّب المسار سياقاً محمياً. وفي مسارات واجهة المتجر للهاتف، الحقل store_id مطلوب في الطلب.
- GET
/mobile/bootstrapتُعيد ملف المتجر وكتل الكتالوج المميّزة ومراجع طرق الدفع.
- GET
/mobile/productsقائمة منتجات مقسّمة إلى صفحات، مع بحث وتصفية بالمستودع اختياريين.
- GET
/mobile/products/{id}تفاصيل المنتج مع متغيّراته ومجموعاته ووسومه.
- GET
/mobile/collectionsتسرد المجموعات في سياق المتجر الحالي.
- GET
/mobile/collections/{id}تفاصيل المجموعة مع منتجاتها.
- GET
/mobile/pagesالصفحات الثابتة المنشورة لتطبيق واجهة المتجر.
- GET
/mobile/blogsالمدوّنات المنشورة.
- GET
/mobile/blogs/{blogId}/articlesقائمة مقالات المدوّنة لشاشات المحتوى.
- GET
/mobile/payment-methodsتُعيد خيارات الدفع المحلي المفعّلة ومراجع الطرق المدعومة.
- POST
/mobile/checkout/quoteتحسب إجماليات عرض السعر من أسطر المتغيّرات.
- POST
/mobile/checkout/place-draft-orderتُنشئ مسودّة طلب محلية كخطوة تسبق إتمام الشراء.
{
"store_id": "your-store-uuid",
"warehouse_name": "BRAND VIP WEB",
"lines": [
{ "variant_id": 1201, "quantity": 2 },
{ "variant_id": 1202, "quantity": 1 }
]
}{
"status": "success",
"data": {
"totals": {
"subtotal": 45.0,
"tax": 0,
"shipping": 0,
"discount": 0,
"grand_total": 45.0
}
}
}الأمان وأفضل الممارسات
- تحقّق من store_id ولا تثق أبداً بنطاق المستأجر القادم من جهة العميل.
- استخدم HTTPS فقط في بيئة الإنتاج، وبدّل بيانات الاعتماد دورياً.
- احتفظ بتوكنات الوصول على الخادم فقط.
- اعتمد مبدأ عدم التكرار (idempotency) في عمليات الإنشاء والتحديث الحرجة.
- سجّل إخفاقات المزامنة مع معرّفات الربط لتسهيل التشخيص.
حلّ المشكلات
منتجات مفقودة في إحدى قنوات الهاتف.
راجع قيمة warehouse_name التي يرسلها التطبيق، وتحقّق من قيم warehouse_location في جدول المنتجات.
نقطة النهاية quote تُعيد أسطراً فارغة.
تأكّد أن معرّفات المتغيّرات تتبع المتجر نفسه وتطابق قواعد الظهور للمستودع المختار.
عدّادات المزامنة تبدو قديمة.
حدّث لوحة تحكم الشريك وتحقّق من أن عمّال الطوابير في الخلفية يعملون.