استعلامات GraphQL (قراءة)

تُتيح نقطة النهاية GraphQL على /api/v1/graphql ما مجموعه 16 استعلامًا للقراءة: whoami وworkOrders وworkOrder(id | reference) وassets وasset(id) وassetDowntimes وmeters(assetId) وparts (مع مرشّح lowStock) وpart (بالمعرّف أو الباركود) وstockMovements وfloorPlans(locationId) وlocations وvendors وcustomers وpurchaseOrders وpurchaseOrder(id | reference | erpReference). ويمكن تصفّح كل قائمة حتى نهايتها عبر limit (1-200) مع offset — باستثناء stockMovements التي تُتصفَّح عبر afterId.

نقطة النهاية

أرسل POST إلى https://freemaint.com/api/v1/graphql مع Content-Type: application/json. يستهلك كل استعلام وحدة واحدة من حصتك اليومية.

مثال: قائمة أوامر العمل

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } يعيد حتى 200 صف؛ الحد الافتراضي هو 50.

جلب قطعة واحدة (بالمعرّف أو الباركود)

جلب قطعة واحدة بالمعرّف أو بالباركود، عبر part(id: N) أو part(barcode: "CODE"). يطابق barcode الباركود ورمز QR ورقم القطعة والمرجع (دون حساسية لحالة الأحرف، القطع النشطة فقط) — وهي المطابقة نفسها التي يستخدمها الماسح داخل التطبيق — ويعيد null عند عدم وجود تطابق. مثال: query { part(barcode: "ABC-123") { id name description partNumber quantity minQuantity maxStockLevel unitOfMeasure imageUrl area location { name } vendor { name website } } } تعيد القطعة أيضًا description و minQuantity و maxStockLevel و imageUrl إضافةً إلى location و vendor المتداخلين — ما يكفي لملء شاشة كشك باستعلام واحد. وهو يطابق أيضاً حقل customReference الخاص بكم، فيستطيع أي تكامل العثور على القطعة بالرمز الذي تحمله في نظامكم.

المرشحات المتاحة

• workOrders(limit, offset, status, updatedSince) — من الأحدث إلى الأقدم؛ التصفّح عبر limit (1-200، والافتراضي 50) مع offset؛ وstatus مرشّح نصّي للحالة؛ وتعيد updatedSince أوامر العمل المعدّلة منذ تلك اللحظة فقط؛ ولا تُعاد أبدًا أوامر العمل الموجودة في المهملات
• workOrder(id:) / workOrder(reference:) — أمر عمل واحد، يُعثر عليه بمعرّفه أو بالمرجع الذي يذكره فريقك (WO-2026-11-016، دون تمييز بين الأحرف الكبيرة والصغيرة)؛ مرّر أحدهما فقط. يُرجع كل أمر عمل أيضًا assetName وlocationName، أي الأسماء التي يطبعها نموذج أو تصريح
• assets(limit, offset, updatedSince) — من الأحدث إلى الأقدم؛ التصفّح عبر limit (1-200، والافتراضي 50) مع offset؛ وتعيد updatedSince الأصول المعدّلة منذ تلك اللحظة فقط
• assetDowntimes(assetId, openOnly, since, limit, offset) — توقّفات الآلات، من الأحدث إلى الأقدم؛ التصفّح عبر limit (1-200، والافتراضي 50) مع offset؛ وتعيد openOnly=true التوقّفات التي لم تنتهِ بعد؛ وتعيد since (ISO 8601) التوقّفات التي بدأت اعتبارًا من طابع زمني، وهي الطريقة الاقتصادية لتعويض تسليم فائت
• parts(limit, offset, lowStock, updatedSince) — تصفّح بـ limit (من 1 إلى 200) مع offset؛ ويعيد updatedSince القطع المعدّلة منذ تلك اللحظة فقط؛ ويعيد lowStock=true الأصناف المخزّنة عند الحد الأدنى minQuantity أو دونه فقط
• locations, vendors, customers (limit, offset, updatedSince) — مرتّبة حسب الاسم؛ التصفّح عبر limit (1-200، والافتراضي 200) مع offset؛ وتعيد updatedSince الصفوف المعدّلة منذ تلك اللحظة فقط
• part(id, barcode) — البحث عن قطعة واحدة؛ يطابق barcode الباركود ورمز QR ورقم القطعة والمرجع والمرجع المخصّص، وهو مثالي للماسحات
• floorPlans(locationId) — مخططات الطوابق لموقع ما مع علاماتها (إحداثيات x/y نسبية)؛ تتيح للكشك عرض مكان تخزين القطعة
• meters(assetId, limit, offset) — العدّادات (ساعات التشغيل، عدّادات القطع، عدّادات المسافة، المقاييس)، الأحدث أولاً؛ التصفّح عبر limit (1-200، والافتراضي 50) مع offset؛ يحصر assetId النتائج في آلة واحدة؛ ويعطي lastReadingValue وlastReadingDate آخر قراءة
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — أوامر الشراء مع بنودها (لكل بند receivedQuantity) وتسليماتها (receipts) ومورّدها، من الأحدث إلى الأقدم؛ التصفّح عبر limit (من 1 إلى 200، والافتراضي 50) مع offset؛ وتكون status إحدى القيم PENDING أو APPROVED أو ORDERED أو PARTIALLY_RECEIVED أو RECEIVED أو CANCELLED؛ وتُعيد updatedSince الأوامر المعدّلة منذ تلك اللحظة فقط
• purchaseOrder(id, reference, erpReference) — أمر شراء واحد، يُعثر عليه بمعرّفه id أو بمرجعه في FreeMaint (PO-12) أو بقيمة erpReference التي كتبها نظام ERP لديك؛ مرّر واحدًا منها فقط
• stockMovements(limit, afterId, since, partId, workOrderId, type) — سجلّ حركات المخزون، من الأقدم إلى الأحدث؛ التصفّح عبر limit (1-200، والافتراضي 50) مع afterId: مرّر id آخر حركة تلقّيتها للحصول على الصفحة التالية، ويبقى ذلك دقيقًا حتى أثناء كتابة حركات جديدة؛ ويبدأ since (ISO 8601) من تاريخ معيّن؛ وتكون type إحدى القيم ADJUSTMENT أو PURCHASE أو WORK_ORDER أو TRANSFER أو RETURN أو SCRAP أو INITIAL أو CORRECTION أو INSPECTION

الاستبطان المخطط

الاستبطان مُفعَّل. لاستكشاف المخطط الكامل بشكل تفاعلي — كل استعلام وعملية تعديل ونوع إدخال مع حقوله — وجِّه عميل GraphQL مكتبيًا (Altair أو Insomnia أو Postman) إلى POST /api/v1/graphql مع رمز Bearer الخاص بك. أما المستكشفات التي تعمل داخل المتصفح، مثل Apollo Sandbox أو GraphiQL عبر الإنترنت، فترفضها سياسة CORS لدينا.