واجهة برمجة التطبيقات العامة (Public API)

نظرة عامة

تمنح واجهة برمجة التطبيقات العامة لـ AutoGMS شركاء التكامل إمكانية الوصول البرمجي إلى بيانات الكراج. استخدمها لربط أدوات التشخيص ومنصات إدارة الأساطيل ولوحات المعلومات المخصصة وكتالوجات القطع وتطبيقات الجوال بحساب AutoGMS الخاص بك.

الميزات الرئيسية:

• وصول كامل للقراءة والكتابة لجميع بيانات الكراج بما في ذلك الحجوزات والعملاء والمركبات والمخزون والفواتير والمزيد
• الويب هوك (Webhooks) -- استلام إشعارات فورية عند حدوث أحداث في كراجك
• مصادقة بمفتاح API مع تحديد معدل الطلبات لكل مفتاح ومستويات الصلاحيات
• نطاق خاص بالكراج -- كل طلب مرتبط بكراج محدد
• تسجيل النشاط -- يتم تسجيل جميع أنشطة API وعرضها في لوحة الإدارة
• دعم كراجات متعددة -- يمكن لمفتاح واحد الوصول إلى عدة كراجات في مؤسستك

---

المتطلبات الأساسية

الوصول عبر API هو ميزة إضافية مدفوعة. يجب أن تكون ميزة الوصول عبر API مُفعّلة لمؤسستك. إذا لم تكن الميزة مُفعّلة، ستعرض صفحة الوصول عبر API في لوحة التحكم إشعاراً بتعليمات للتواصل مع الدعم.

بمجرد التفعيل، يمكن لمسؤولي المؤسسة إنشاء وإدارة مفاتيح API مباشرة من لوحة التحكم -- لا حاجة للتواصل مع الدعم لعمليات المفاتيح.

---

البدء

الخطوة 1: إنشاء مفتاح API

1. في الشريط الجانبي للوحة التحكم، انتقل إلى مؤسستك وانقر على الوصول عبر API.
2. انقر إنشاء مفتاح في الزاوية العلوية اليمنى.
3. أدخل اسماً وصفياً للمفتاح (مثلاً "الخادم الإنتاجي"، "لوحة معلومات الأسطول"، "اختبار بيئة التطوير").
4. اختر مستوى الصلاحية:
   • قراءة فقط -- يمكنه الوصول لنقاط GET فقط؛ مناسب للوحات المعلومات والتقارير والتكاملات للقراءة فقط.
   • قراءة وكتابة -- وصول كامل لجميع النقاط بما في ذلك إنشاء وتعديل البيانات.
5. انقر إنشاء.
6. يُعرض مفتاح API الكامل مرة واحدة. انسخه فوراً واحفظه بأمان -- لا يمكن استرجاعه مرة أخرى بعد إغلاق هذا الحوار.

تمتلك مؤسستك حداً أقصى لعدد المفاتيح النشطة (يظهر في أعلى الصفحة). يُعطّل زر الإنشاء عند الوصول للحد.

الخطوة 2: إجراء أول طلب

استخدم مفتاح API في عنوان X-API-Key:

GET https://api.autogms.com/api/v1/garages
X-API-Key: agms_pk_live_your_key_here

يُرجع هذا قائمة بجميع الكراجات التي يمكن لمفتاحك الوصول إليها.

الخطوة 3: الوصول إلى بيانات الكراج

تتطلب جميع نقاط البيانات معرّف الكراج في عنوان URL:

GET https://api.autogms.com/api/v1/garages/{garageId}/bookings
X-API-Key: agms_pk_live_your_key_here

---

البيانات المتاحة

توفر واجهة API وصول القراءة والكتابة لجميع المجالات الرئيسية في كراجك:

المورد	القراءة	الكتابة
الكراجات	تفاصيل الموقع، معلومات الاتصال	--
العملاء	ملفات العملاء، سجل الحجوزات، المركبات	إنشاء وتحديث العملاء والمركبات
المركبات	تفاصيل المركبة، فك تشفير VIN	إنشاء وتحديث وحذف المركبات
الحجوزات	جميع الحجوزات مع الحالة والفنيين والقطع والمراحل	إنشاء وتحديث وتغيير الحالة وحذف وتعيين الفنيين والقطع
مراحل الحجز	مراحل العمل مع الفنيين المعينين	إنشاء وتحديث وتغيير الحالة وحذف المراحل
الفنيون	قائمة الفريق، إحصائيات الأداء، العمل المُسند	--
الخدمات	كتالوج الخدمات مع الأسعار	--
المخزون	مستويات المخزون، تنبيهات المخزون المنخفض، البحث بالباركود	إنشاء عناصر، تحديث التفاصيل، تعديل المخزون
الفواتير	تفاصيل الفواتير، حالة الدفع	--
التقديرات	تفاصيل التقديرات، حالة الموافقة، البنود	إنشاء وتحديث وإرسال التقديرات
أوامر الشراء	تفاصيل أوامر الشراء، إحصائيات المشتريات	--
خلجان العمل	توفر الخلجان والتعيينات الحالية	--
الويب هوك	قائمة الاشتراكات، سجل التسليم	إنشاء وتحديث وحذف واختبار الويب هوك

ملاحظة: تتطلب عمليات الكتابة مفتاح API بصلاحية قراءة وكتابة. مفاتيح القراءة فقط يمكنها الوصول لنقاط GET فقط.

---

حالات الاستخدام الشائعة

تكامل التشخيص

ربط معدات التشخيص للبحث عن المركبات وإنشاء الحجوزات:

GET  /api/v1/garages/{garageId}/vehicles/vin-lookup?vin=JTMHY7AJ5E4012345
POST /api/v1/garages/{garageId}/bookings

لوحة معلومات إدارة الأسطول

مراقبة جميع الأعمال النشطة وأحمال عمل الفنيين وتوفر الخلجان:

GET /api/v1/garages/{garageId}/bookings/counts
GET /api/v1/garages/{garageId}/technicians
GET /api/v1/garages/{garageId}/bays

تكامل كتالوج القطع

التحقق من مستويات المخزون وتعديل المخزون والحصول على تنبيهات المخزون المنخفض:

GET  /api/v1/garages/{garageId}/inventory?lowStock=true
GET  /api/v1/garages/{garageId}/inventory/barcode/6291041500123
POST /api/v1/garages/{garageId}/inventory/{itemId}/adjust

أتمتة الحجوزات

إنشاء الحجوزات وتعيين الفنيين وإدارة مراحل العمل برمجياً:

POST /api/v1/garages/{garageId}/bookings
POST /api/v1/garages/{garageId}/bookings/{bookingId}/status
POST /api/v1/garages/{garageId}/bookings/{bookingId}/technician
POST /api/v1/garages/{garageId}/bookings/{bookingId}/stages

الإشعارات الفورية (الويب هوك)

استلام إشعارات فورية عند حدوث أحداث في كراجك:

POST /api/v1/garages/{garageId}/webhooks

اشترك في أحداث مثل booking.completed و inventory.low_stock و invoice.paid والمزيد. يرسل AutoGMS طلب HTTP POST إلى عنوان URL الخاص بك عند حدوث الحدث.

أحداث Webhook الشائعة في الإصدار v1 تشمل:

• customer.created
• booking.created
• booking.updated
• booking.status_changed
• booking.completed
• technician.assigned
• estimate.created
• estimate.sent
• inventory.low_stock

التقارير المخصصة

سحب البيانات المالية لأدوات التقارير الخارجية:

GET /api/v1/garages/{garageId}/invoices?status=paid&dateFrom=2026-01-01
GET /api/v1/garages/{garageId}/purchase-orders/stats

مزامنة تقويم الأسطول (النمط الموصى به)

للتكاملات مثل AssetMinder، استخدم هذا النمط لتجنب تضارب الجدولة:

1. اقرأ أولاً:
   • GET /api/v1/garages/{garageId}/bookings
   • GET /api/v1/garages/{garageId}/bookings/counts
   • GET /api/v1/garages/{garageId}/bays
2. أنشئ/حدّث فترات التقويم الخارجي من حالات الحجوزات النشطة.
3. كتابة اختيارية لإنشاء حجوزات عبر POST /bookings.
4. التعامل مع حواجز الحجز:
   • GARAGE_CLOSED (409) -- التاريخ المحدد مغلق.
   • DATE_AT_CAPACITY (409) -- السعة اليومية مكتملة.
   • SLOT_AT_CAPACITY (409) -- الفترة الزمنية المحددة ممتلئة.
   • ACTIVE_JOB_EXISTS (409) -- نفس المركبة لديها عمل نشط بالفعل.
5. استخدم الويب هوك لإبقاء التقاويم الخارجية شبه فورية، ثم قم بالمصالحة مع الاستقصاء الدوري.

---

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

جميع الاستجابات تستخدم تنسيق JSON متسق.

استجابة ناجحة:

{
  "success": true,
  "data": { ... }
}

استجابة قائمة مع ترقيم الصفحات:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8,
    "hasMore": true
  }
}

استجابة خطأ:

{
  "success": false,
  "error": {
    "type": "NotFoundError",
    "message": "Booking not found",
    "code": "RESOURCE_NOT_FOUND"
  }
}

أخطاء الجدولة الشائعة في تكاملات الكتابة:

• GARAGE_CLOSED (409)
• DATE_AT_CAPACITY (409)
• TIMESLOT_REQUIRED (400) عندما يتطلب الكراج فترة زمنية ولا يتم إرسال timeslot
• INVALID_TIMESLOT (400) عندما تكون قيمة timeslot غير صالحة لذلك التاريخ
• SLOT_AT_CAPACITY (409)
• ACTIVE_JOB_EXISTS (409)

إذا كان الكراج يستخدم جدولة الفترات الزمنية، فأرسل الحقل timeslot بصيغة HH:MM عند إنشاء أو تحديث الحجز، مثلاً:

{
  "date": "2026-03-04",
  "timeslot": "09:00"
}

---

ترقيم الصفحات والتصفية

ترقيم الصفحات

جميع نقاط القوائم تدعم ترقيم الصفحات:

المعامل	الافتراضي	الحد الأقصى	الوصف
page	1	--	رقم الصفحة
limit	20	100	عدد العناصر في الصفحة

مثال: GET /api/v1/garages/{garageId}/bookings?page=2&limit=50

الترتيب

استخدم معامل sort. أضف - في البداية للترتيب التنازلي:

• sort=-date -- الأحدث أولاً
• sort=name -- أبجدي

تصفية التاريخ

معظم نقاط القوائم تدعم تصفية نطاق التاريخ:

• dateFrom=2026-01-01 -- السجلات من هذا التاريخ فصاعداً
• dateTo=2026-01-31 -- السجلات حتى هذا التاريخ

---

تحديد المعدل

لكل مفتاح API حد طلبات في الدقيقة حسب مستواه:

المستوى	الطلبات في الدقيقة
عادي	60
متميز	300
مؤسسي	1,000

كل استجابة تتضمن رؤوس تحديد المعدل:

RateLimit-Limit: 60
RateLimit-Remaining: 42
RateLimit-Reset: 1706000000

إذا تجاوزت الحد، ستتلقى استجابة 429 Too Many Requests. انتظر حتى تنتهي فترة Retry-After قبل إجراء المزيد من الطلبات.

---

إدارة مفاتيح API

تُدار مفاتيح API من صفحة الوصول عبر API في لوحة تحكم مؤسستك. يمكن لأي مسؤول مؤسسة تنفيذ هذه الإجراءات.

لوحة تحكم الوصول عبر API

تعرض صفحة الوصول عبر API:

• نظرة عامة على الإحصائيات -- أربع بطاقات ملخصة تعرض إجمالي الطلبات (30 يوماً)، ومعدل الأخطاء، ومتوسط زمن الاستجابة (مع مئويات p50/p95/p99 عند توفرها)، وإجمالي البيانات المنقولة.
• جدول المفاتيح -- يسرد جميع المفاتيح (النشطة والملغاة) مع مقاييس لكل مفتاح:

العمود	ما يعرضه
الاسم	اسم المفتاح وبادئة مُقنّعة
الصلاحية	قراءة فقط أو قراءة وكتابة
الطلبات (30 يوماً)	عدد الطلبات لآخر 30 يوماً، مع تفصيل طرق HTTP
مدى الحياة	إجمالي عدد الطلبات عبر كامل المدة
الأخطاء (30 يوماً)	عدد الأخطاء مع كشف الارتفاعات (يُنبّه إذا كان معدل أخطاء 24 ساعة ضعف معدل 30 يوماً)
زمن الاستجابة	متوسط وقت الاستجابة
البيانات	إجمالي البيانات المنقولة
النشاط	تواريخ أول وآخر طلب
الحالة	نشط أو ملغى

إجراءات المفتاح

لكل مفتاح نشط ثلاثة إجراءات في الجدول:

• عرض الاستخدام -- يفتح تفصيلاً يومياً مفصلاً للاستخدام وإحصائيات لكل نقطة نهاية لذلك المفتاح المحدد.
• تدوير -- يُنشئ مفتاحاً جديداً ويُبطل القديم. يُعرض المفتاح الجديد مرة واحدة -- انسخه فوراً. استخدم هذا إذا كان هناك احتمال لتسريب المفتاح.
• إلغاء -- يُعطّل المفتاح نهائياً. تبقى المفاتيح الملغاة مرئية في الجدول (باللون الرمادي) لأغراض التدقيق لكن لا يمكن استخدامها لطلبات API بعد ذلك.

التدوير والإلغاء إجراءات نهائية لا يمكن التراجع عنها.

بطاقات التحليلات

أسفل جدول المفاتيح، تعرض الصفحة تحليلات إضافية عند توفر البيانات:

• تفصيل الطرق -- شريط مرئي يعرض توزيع الطلبات عبر طرق HTTP (GET، POST، PUT، PATCH، DELETE)
• أكثر نقاط النهاية استخداماً (30 يوماً) -- مسارات API الأكثر استدعاءً مع أعداد الطلبات والأخطاء ومتوسط زمن الاستجابة
• الأخطاء الأخيرة (7 أيام) -- أنماط الأخطاء مع رموز الحالة ورموز الخطأ وأعداد الحدوث ومسارات نموذجية
• الطلبات حسب الساعة (30 يوماً) -- رسم بياني يعرض توزيع الطلبات عبر ساعات اليوم (بتوقيت UTC)
• توزيع حجم الاستجابات -- كيفية توزيع أحجام حمولات الاستجابة
• أكثر وكلاء المستخدم استخداماً (30 يوماً) -- أي مكتبات العملاء أو الأدوات تستدعي API
• أكثر عناوين IP نشاطاً (30 يوماً) -- أي عناوين IP تولّد أكثر حركة مرور
• الاستخدام حسب الكراج -- توزيع الطلبات لكل كراج مع معدلات الأخطاء وزمن الاستجابة

---

مرجع نقاط النهاية الكامل

جميع نقاط النهاية مسبوقة بـ /api/v1. نقاط الموارد تستخدم /garages/{garageId}/.

الكراجات

نقطة النهاية	الوصف
GET /garages	قائمة جميع الكراجات المتاحة لهذا المفتاح
GET /garages/{garageId}	تفاصيل الكراج

العملاء

نقطة النهاية	الوصف
GET /garages/{gid}/customers	قائمة عملاء الكراج
GET /garages/{gid}/customers/search?q=ahmed	البحث بالاسم أو البريد أو الهاتف
POST /garages/{gid}/customers	إنشاء عميل
PATCH /garages/{gid}/customers/{cid}	تحديث عميل
GET /garages/{gid}/customers/{cid}	عرض العميل مع إحصائيات الحجوزات
GET /garages/{gid}/customers/{cid}/vehicles	قائمة مركبات العميل
POST /garages/{gid}/customers/{cid}/vehicles	إضافة مركبة للعميل
GET /garages/{gid}/customers/{cid}/bookings	قائمة حجوزات العميل

المركبات

نقطة النهاية	الوصف
GET /garages/{gid}/vehicles	قائمة جميع المركبات
POST /garages/{gid}/vehicles	إنشاء مركبة
PATCH /garages/{gid}/vehicles/{vid}	تحديث مركبة
DELETE /garages/{gid}/vehicles/{vid}	حذف مركبة
GET /garages/{gid}/vehicles/{vid}	تفاصيل المركبة
GET /garages/{gid}/vehicles/vin-lookup?vin=...	فك تشفير VIN

الحجوزات

نقطة النهاية	الوصف
GET /garages/{gid}/bookings	قائمة الحجوزات (تصفية حسب الحالة، التاريخ، العميل، الفني)
POST /garages/{gid}/bookings	إنشاء حجز
GET /garages/{gid}/bookings/counts	عدد الحجوزات حسب الحالة
GET /garages/{gid}/bookings/{bid}	تفاصيل الحجز الكاملة
PATCH /garages/{gid}/bookings/{bid}	تحديث حجز
DELETE /garages/{gid}/bookings/{bid}	حذف حجز (معلق/مؤكد فقط)
POST /garages/{gid}/bookings/{bid}/status	تغيير حالة الحجز
POST /garages/{gid}/bookings/{bid}/technician	تعيين فني
GET /garages/{gid}/bookings/{bid}/inventory	قائمة القطع المعينة
POST /garages/{gid}/bookings/{bid}/inventory	تعيين قطع للحجز
GET /garages/{gid}/bookings/{bid}/parts	قائمة القطع المعينة (بديل)
GET /garages/{gid}/bookings/{bid}/attachments	قائمة المرفقات
GET /garages/{gid}/bookings/{bid}/stages	قائمة مراحل المشروع
POST /garages/{gid}/bookings/{bid}/stages	إنشاء مرحلة
PATCH /garages/{gid}/bookings/{bid}/stages/{sid}	تحديث مرحلة
POST /garages/{gid}/bookings/{bid}/stages/{sid}/status	تغيير حالة المرحلة
DELETE /garages/{gid}/bookings/{bid}/stages/{sid}	حذف مرحلة

قيم دورة حياة المراحل المستخدمة عادةً في سير عمل المشاريع:

• draft
• open
• in_progress
• completed
• invoiced
• closed

الفنيون

نقطة النهاية	الوصف
GET /garages/{gid}/technicians	قائمة الفنيين
GET /garages/{gid}/technicians/{tid}/stats	إحصائيات الأداء
GET /garages/{gid}/technicians/{tid}/bookings	الحجوزات المُسندة

الخدمات

نقطة النهاية	الوصف
GET /garages/{gid}/services	كتالوج الخدمات
GET /garages/{gid}/services/{sid}	تفاصيل الخدمة
GET /garages/{gid}/services/{sid}/prices	الأسعار حسب نوع المركبة

المخزون

نقطة النهاية	الوصف
GET /garages/{gid}/inventory	قائمة العناصر
POST /garages/{gid}/inventory	إنشاء عنصر مخزون
GET /garages/{gid}/inventory/{iid}	عرض عنصر
PATCH /garages/{gid}/inventory/{iid}	تحديث عنصر
POST /garages/{gid}/inventory/{iid}/adjust	تعديل المخزون (إضافة أو خصم)
GET /garages/{gid}/inventory/low-stock	العناصر تحت الحد الأدنى
GET /garages/{gid}/inventory/categories	الفئات مع العدد
GET /garages/{gid}/inventory/stats	إحصائيات المخزون
GET /garages/{gid}/inventory/barcode/{code}	البحث بالباركود

الفواتير

نقطة النهاية	الوصف
GET /garages/{gid}/invoices	قائمة الفواتير
GET /garages/{gid}/invoices/{iid}	تفاصيل الفاتورة

التقديرات

نقطة النهاية	الوصف
GET /garages/{gid}/estimates	قائمة التقديرات
POST /garages/{gid}/estimates	إنشاء تقدير
GET /garages/{gid}/estimates/{eid}	تفاصيل التقدير
PATCH /garages/{gid}/estimates/{eid}	تحديث تقدير
POST /garages/{gid}/estimates/{eid}/send	إرسال تقدير للعميل

أوامر الشراء

نقطة النهاية	الوصف
GET /garages/{gid}/purchase-orders	قائمة أوامر الشراء
GET /garages/{gid}/purchase-orders/{pid}	تفاصيل أمر الشراء
GET /garages/{gid}/purchase-orders/stats	إحصائيات المشتريات

خلجان العمل

نقطة النهاية	الوصف
GET /garages/{gid}/bays	قائمة الخلجان مع الحالة الحالية

الويب هوك (Webhooks)

نقطة النهاية	الوصف
GET /garages/{gid}/webhooks	قائمة اشتراكات الويب هوك
POST /garages/{gid}/webhooks	إنشاء اشتراك ويب هوك
PATCH /garages/{gid}/webhooks/{wid}	تحديث ويب هوك
DELETE /garages/{gid}/webhooks/{wid}	حذف ويب هوك
POST /garages/{gid}/webhooks/{wid}/test	إرسال حدث تجريبي
GET /garages/{gid}/webhooks/{wid}/deliveries	عرض سجل التسليم

---

قريباً

• OAuth 2.0 -- مصادقة الطرف الثالث لتكاملات السوق

---

هل تحتاج مساعدة إضافية؟

• تفعيل الوصول عبر API: أرسل بريداً إلكترونياً إلى support@myautoGMS.com لإضافة إضافة الوصول عبر API إلى اشتراكك
• إدارة المفاتيح: استخدم صفحة الوصول عبر API في لوحة تحكمك لإنشاء وتدوير وإلغاء المفاتيح
• الدعم العام: أرسل بريداً إلكترونياً إلى support@myautoGMS.com
• مراجعة نطاق التكامل والتصميم التقني: أرسل بريداً إلكترونياً إلى support@myautoGMS.com وأرفق:
  • الكراج(ات) المستهدفة
  • الصلاحيات المطلوبة (read أو read_write)
  • اتجاه المزامنة المتوقع (سحب فقط مقابل دفع + سحب)
  • الحجم المتوقع (طلبات/دقيقة، حجوزات/يوم)