نظرة عامة على API

يوفّر FreeMaint واجهة برمجية واحدة للتكامل بين الأنظمة: GraphQL على /api/v1/graphql. مسارات REST التي تراها في المتصفح هي واجهة التطبيق نفسه ويتم توثيقها بجلسة مستخدم — ومفتاح API لا يصل إليها. خطّط لتكاملك على GraphQL.

واجهة REST البرمجية

مسارات REST تحت /api/v1/{resource} هي ما تستدعيه تطبيقات FreeMaint للويب والهاتف، بتوثيق جلسة مستخدم (JWT). مفتاح API‏ (fmk_...) لا يوثّقها — بل يُقبل فقط على /api/v1/graphql وعلى نقطة استقبال بيانات الطاقة. للتكامل، اقرأ قسم GraphQL أدناه.

مثال (جلسة مستخدم، وليس مفتاح API — مفتاح fmk_ لا يوثّق هذا المسار): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

واجهة GraphQL البرمجية

نقطة وصول GraphQL هي POST /api/v1/graphql. وهي تغطي مجموعة جزئية مقصودة من المنتج — أوامر العمل والأصول وتوقّفات الآلات وقطع الغيار وحركات مخزونها والعدّادات وأوامر الشراء والمواقع والموردين والعملاء ومخطّطات الطوابق — لا التطبيق بأكمله. استخدم GraphQL عندما يتطلب الأمر خلاف ذلك استدعاء عدة نقاط وصول لتركيب شاشة واحدة: مثل بطاقة تعرض أمر عمل مع تفاصيل أصله والقطع المستهلكة وإجمالي تكلفة العمالة. ويعدّد دليل التكامل مع أنظمة ERP ما لا يبلغه المخطّط.

مثال على الاستعلام: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

المصادقة

تقبل كلتا الواجهتين رمز JWT في ترويسة Authorization، يصدره POST /api/v1/auth/login وصلاحيته ساعتان (يُجدَّد عبر رمز التحديث). أما لتكاملات الخادم إلى الخادم فاستخدم مفتاح API: يُنشئه المسؤول من إعدادات الشركة > API (/company-settings/api)، ويُنشئ الشخص الذي يسمح له دوره مفاتيحه الخاصة من الملف الشخصي > الأمان > مفاتيح API (/profile/api-keys)؛ ثم أرسل Authorization: Bearer fmk_... . يعمل المفتاح بصفة مالكه: له صلاحياته ولا يرى إلا ما يراه. مهم: مفتاح API يصادق نقطة GraphQL (POST /api/v1/graphql) ونقطة استقبال بيانات الطاقة و/public-api/{whoami,ping} — ولا يصادق مسارات REST للموارد، التي تتطلب JWT لمستخدم.

التوفّر حسب الباقة

حدود المعدّل

الحصة عدّاد يومي لكل شركة، مشترك بين GraphQL ونقطة استقبال بيانات الطاقة، ويُعاد ضبطه عند 00:00 بتوقيت UTC. يسمح Business بـ 5,000 استدعاء يوميًا، و Enterprise بـ 100,000. تحمل كل استجابة X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset. لا توجد نافذة بالدقيقة ولا ترويسة Retry-After. على واجهات REST يكون الرفض بالرمز HTTP 403؛ أما على GraphQL فيبقى رمز HTTP هو 200 — إذ يردّ GraphQL دائمًا بـ 200 — ويظهر الرفض في errors[0].extensions.code = FORBIDDEN. لا تتحقق من الرمز HTTP 403 على GraphQL، بل اقرأ مصفوفة errors.

صيغة الأخطاء

يحمل كل خطأ حالة HTTP ورمزًا قابلًا للقراءة آليًا ورسالة مفهومة. أخطاء 4xx هي أخطاء العميل (التحقق، الصلاحيات، غير موجود)؛ وأخطاء 5xx أخطاء خادم يُعاد المحاولة معها بتباعد أسّي. في GraphQL يوجد الرمز في extensions.code، والقيم التي يمكنك مطابقتها هي: BAD_REQUEST وUNAUTHENTICATED وFORBIDDEN وNOT_FOUND وCONFLICT وBAD_USER_INPUT وTOO_MANY_REQUESTS. عند فشل التحقق، تذكر الرسالة الحقول الخاطئة بالتحديد — مثل «quantity must be a number conforming to the specified constraints» — فلن تضطر أبدًا إلى تخمين الحقل الذي أرسله نظامك خطأً. والبحث الذي لا يطابق شيئًا ليس خطأً: يعيد part(barcode:) القيمة null.

حزم SDK الرسمية والأدوات

لا يوجد حالياً SDK رسمي للعميل. نقطة GraphQL تدعم الاستكشاف (introspection)، لذا يمكن لأي عميل GraphQL (مثل Apollo أو graphql-codegen أو Insomnia أو Postman) اكتشاف المخطط بالتوجه إلى POST /api/v1/graphql باستخدام مفتاح الـ API الخاص بك. ولا ننشر حالياً مستند OpenAPI ثابتاً ولا ملف SDL على عنوان ثابت.

مفاتيح API غير متاحة في خطتي Core وStarter.