API

تتيح لكم واجهة Gem Logic البرمجية (API) التكامل مع الأنظمة الخارجية وأتمتة سير العمل. يمكنكم استخدامها لإدارة المنتجات والمبيعات وجهات الاتصال والتصليحات وجرد المخزون ومهام الطباعة برمجياً.

انتقلوا إلى الإعدادات ‣ API لإنشاء مفاتيح API وإدارتها.

المصادقة

يجب أن تتضمن جميع طلبات API مفتاح API في ترويسة HTTP تُدعى x-api-key. يمكنكم إنشاء المفاتيح من صفحة الإعدادات ‣ API. يمكن إلغاء تفعيل المفاتيح أو حذفها في أي وقت.

مثال على طلب:

curl -X GET https://your-instance.gem-logic.com/api/marketplaces/ \
  -H "x-api-key: YOUR_API_KEY"

خطر

احفظوا مفاتيح API الخاصة بكم سرية. لا تشاركوها أبداً في المستودعات العامة أو كود جانب العميل. إذا تعرّض مفتاح للاختراق، ألغوا تفعيله فوراً وأنشئوا مفتاحاً جديداً.

عنوان URL الأساسي

جميع نقاط النهاية نسبية إلى عنوان URL الخاص بنسختكم، تحت البادئة /api/:

https://your-instance.gem-logic.com/api/

تنسيق الاستجابة

تُرجَع جميع الاستجابات بتنسيق JSON. الطلبات الناجحة تُرجع رمز الحالة 200 (لـ GET) أو 201 (لـ POST). الأخطاء تُرجع رمز الحالة المناسب مع رسالة:

• 200 OK — طلب GET ناجح

• 201 Created — طلب POST ناجح

• 400 Bad Request — بيانات غير صالحة أو مفقودة

• 401 Unauthorized — مفتاح API غير صالح أو مفقود

• 404 Not Found — المورد غير موجود

نقاط النهاية

قنوات البيع

الطريقة	GET
عنوان URL	/api/marketplaces/
الوصف	تُرجع قائمة بجميع قنوات البيع.

حقول الاستجابة:

الحقل	النوع	الوصف
id	integer	معرّف فريد
marketplace	string	اسم قناة البيع

المنتجات

سرد المنتجات

الطريقة	GET
عنوان URL	/api/products/{marketplace_id}
الوصف	يُرجع المنتجات المصفّاة حسب قناة البيع. استخدموا معرّف قناة البيع من نقطة النهاية marketplaces.

حقول الاستجابة:

الحقل	النوع	الوصف
id	integer	معرّف فريد
item_sku	string	SKU المنتج
created	datetime	تاريخ الإنشاء
status	string	حالة المنتج
images	array	قائمة صور المنتج (id، image)
item_weight	decimal	الوزن
item_height	decimal	الارتفاع
item_length	decimal	الطول
item_width	decimal	العرض

إنشاء صورة المنتج

الطريقة	POST
عنوان URL	/api/products/create/image/
الوصف	رفع صورة منتج باستخدام ترميز base64. إذا لم يكن SKU المنتج موجوداً بعد، يتم إنشاء منتج جديد تلقائياً.

حقول الطلب:

الحقل	النوع	مطلوب	الوصف
item_sku	string	نعم	SKU المنتج المراد إرفاق الصورة به
image	string (base64)	نعم	بيانات الصورة المرمّزة بـ base64

المبيعات

عرض المبيعات

الطريقة	GET
عنوان URL	/api/sales/
الوصف	يُرجع قائمة بجميع أوامر البيع.

حقول الاستجابة:

الحقل	النوع	الوصف
order_id	string	مُعرّف الطلب الفريد

إنشاء عملية بيع

الطريقة	POST
عنوان URL	/api/sales/create/
الوصف	ينشئ أمر بيع جديد.

جهات الاتصال

الطريقة	GET
عنوان URL	/api/contacts/
الوصف	يُرجع قائمة بجميع جهات الاتصال.

حقول الاستجابة:

الحقل	النوع	الوصف
id	integer	معرّف فريد
complete_name	string	الاسم الكامل
contact_type	string	نوع جهة الاتصال
email	string	عنوان البريد الإلكتروني
phone	string	رقم الهاتف
language	string	اللغة المفضلة

إصلاحات

إنشاء إصلاح

الطريقة	POST
عنوان URL	/api/repairs/create/
الوصف	ينشئ أمر إصلاح جديد مع صنف إصلاح مرتبط. إذا لم يتم توفير قناة البيع أو القسم، يُستخدم الأول المتاح.

حقول الطلب:

الحقل	النوع	مطلوب	الوصف
client_id	integer	لا	معرّف العميل/جهة الاتصال
marketplace	نص / عدد صحيح	لا	معرّف قناة البيع أو اسمها
division_id	integer	لا	معرّف قسم العمل
title	string	لا	عنوان أو وصف صنف الإصلاح
repair_info_1	string	لا	تعليق إصلاح إضافي
repair_info_2	string	لا	تعليق إصلاح إضافي
repair_info_3	string	لا	تعليق إصلاح إضافي
quantity	decimal	لا	الكمية (افتراضياً: 1)
weight	decimal	لا	وزن الصنف
weight_unit	string	لا	وحدة قياس الوزن
size	string	لا	مقاس الصنف
color	string	لا	لون الصنف
engravement	string	لا	نص النقش
client_reference | string		لا	رقم مرجع العميل

مثال على الرد:

{"message": "Repair created successfully.", "order_id": "R-0001"}

إضافة صنف إلى التصليح

الطريقة	POST
عنوان URL	/api/repairs/add-item/
الوصف	يضيف صنفاً جديداً إلى طلب تصليح موجود.

حقول الطلب:

الحقل	النوع	مطلوب	الوصف
order_id	string	نعم	معرّف طلب التصليح المراد إضافة الصنف إليه
item_sku	string	لا	SKU المنتج المراد ربطه بالصنف
title	string	لا	العنوان أو الوصف
repair_info_1	string	لا	تعليق إصلاح إضافي
repair_info_2	string	لا	تعليق إصلاح إضافي
repair_info_3	string	لا	تعليق إصلاح إضافي
quantity	decimal	لا	الكمية (افتراضياً: 1)
weight	decimal	لا	وزن الصنف
weight_unit	string	لا	وحدة قياس الوزن
size	string	لا	مقاس الصنف
color	string	لا	لون الصنف
engravement	string	لا	نص النقش
client_reference | string		لا	رقم مرجع العميل
cost	decimal	لا	تكلفة الصنف

عمليات الجرد

إنشاء عملية جرد

الطريقة	POST
عنوان URL	/api/inventory-counts/
الوصف	ينشئ جلسة جرد جديدة.

حقول الاستجابة:

الحقل	النوع	الوصف
id	string	معرّف عملية الجرد
created_at	datetime	الطابع الزمني للإنشاء
status	string	دائماً active
tag_count	integer	عدد المنتجات المُحصية

عرض منتجات عملية الجرد

الطريقة	GET
عنوان URL	/api/inventory-counts/{inventory_count_id}/products/
الوصف	يُرجع جميع المنتجات المُحصية في عملية جرد محددة.

حقول الاستجابة:

الحقل	النوع	الوصف
id	string	معرّف فريد
created_at	datetime	موعد إحصاء المنتج
product_sku	string	SKU المنتج
product_name	string	اسم المنتج
quantity	integer	الكمية المُحْصاة

مهام الطباعة

الطريقة	POST
عنوان URL	/api/print-pdf/
الوصف	رفع ملف PDF إلى قائمة انتظار الطباعة لطابعة معيّنة. يتم التحقق من صحة الملف من حيث التنسيق والأمان. الحد الأقصى لحجم الملف هو 20 ميجابايت. استخدموا نوع المحتوى multipart/form-data.

حقول الطلب:

الحقل	النوع	مطلوب	الوصف
pdf	ملف	نعم	ملف PDF للطباعة (الحد الأقصى 20 ميجابايت)
printer_uuid	UUID	نعم	UUID الطابعة المستهدفة
landscape	منطقي	لا	الطباعة في الوضع الأفقي (الافتراضي: false)

مثال على طلب:

curl -X POST https://your-instance.gem-logic.com/api/print-pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "pdf=@document.pdf" \
  -F "printer_uuid=YOUR_PRINTER_UUID"

مثال على الرد:

{"status": "queued", "print_job_id": 42}

مُستكشف API تفاعلي

يتضمن Gem Logic مُستكشف API تفاعليًا مُدمجًا يعمل بواسطة Swagger UI. يمكنكم الوصول إليه من رابط توثيق API الموجود في صفحة الإعدادات ‣ API. يتيح لكم المُستكشف تجربة كل نقطة نهاية (endpoint) مباشرةً من متصفحكم.

شاهد أيضا

• التكاملات