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

نظرة عامة

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

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

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

كيفية الوصول

يتم إنشاء وإدارة مفاتيح API بواسطة مسؤول AutoGMS (المسؤول الأعلى). إذا كنت بحاجة إلى الوصول عبر API، تواصل مع المسؤول لطلب مفتاح.

بمجرد استلام مفتاح API الخاص بك، يمكنك البدء بإجراء الطلبات فوراً.

البدء

الخطوة 1: طلب مفتاح API

تواصل مع مسؤول AutoGMS لطلب مفتاح API. عند تقديم طلبك، أخبرهم بما يلي:

الغرض من الاستخدام -- مثل "لوحة معلومات الأسطول"، "تكامل كتالوج القطع"، "أداة التشخيص".
مستوى الصلاحية -- قراءة فقط للوحات المعلومات والتقارير، أو قراءة وكتابة للتكاملات الكاملة.
الكراجات المطلوبة -- حدد إذا كنت تحتاج الوصول لكراجات معينة فقط.

سيزودك المسؤول بمفتاح 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 الخاص بك عند حدوث الحدث.

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

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

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

تنسيق استجابة 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"
  }
}

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

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

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

المعامل	الافتراضي	الحد الأقصى	الوصف
`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 بواسطة مسؤول AutoGMS. إذا كنت بحاجة إلى أي مما يلي، تواصل مع المسؤول:

عرض إحصائيات الاستخدام -- يمكن للمسؤول عرض عدد الطلبات ومعدلات الخطأ والنشاط الأخير لكل مفتاح.
تدوير المفتاح -- إذا كان هناك احتمال لتسريب المفتاح، اطلب من المسؤول تدويره. يتم إنشاء مفتاح جديد وإبطال القديم.
إلغاء المفتاح -- لتعطيل مفتاح نهائياً، اطلب من المسؤول إلغاءه.

تدوير وإلغاء المفاتيح إجراءات نهائية يتم التعامل معها بواسطة المسؤول.

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

جميع نقاط النهاية مسبوقة بـ /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}`	حذف مرحلة

الفنيون

نقطة النهاية	الوصف
`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: تواصل مع مسؤول AutoGMS
مشاكل المفاتيح (تدوير، إلغاء): تواصل مع مسؤول AutoGMS
الدعم العام: أرسل بريداً إلكترونياً إلى support@myautogms.com

نظرة عامة​

كيفية الوصول​

البدء​

الخطوة 1: طلب مفتاح API​

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

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

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

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

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

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

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

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

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

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

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

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

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

الترتيب​

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

تحديد المعدل​

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

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

الكراجات​

العملاء​

المركبات​

الحجوزات​

الفنيون​

الخدمات​

المخزون​

الفواتير​

التقديرات​

أوامر الشراء​

خلجان العمل​

الويب هوك (Webhooks)​

قريباً​

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