تكامل REST API وMCP

نظرة عامة على REST API والمصادقة

الاتصال بواجهة ExCoil REST الحالية: الوصول والمسارات الفعلية وأجسام الطلبات والوحدات والاستجابات والحدود التشغيلية.

تاريخ المراجعة 2026-11-02

1. الوصول والفصل بين REST وMCP

يتطلب الوصول عبر REST اشتراك Enterprise أو Manufacturer بحالة active أو trialing. يتحقق الخادم من اشتراك مالك المفتاح الحالي مع كل طلب؛ امتلاك مفتاح قديم لا يحافظ على الوصول بعد خفض الخطة أو فقدان الحالة المؤهلة.

تستخدم REST المسار /api/v1 ومفاتيح API التي تبدأ بـ exk_. أما MCP فهي واجهة Streamable HTTP منفصلة عند /api/mcp، حصرية لخطة Manufacturer، وتستخدم رموز Bearer مخصصة تُضبط يدوياً. لا تحل أي من بيانات الاعتماد محل الأخرى. لا تنفذ مسارات REST هذه تدفق تفويض OAuth.

تتيح المسارات أدناه ستة محركات لحساب الملفات المزعنفة وقائمة المبرّدات. ولا تقدم إنشاء المشاريع أو قراءتها أو تعديلها أو حذفها عبر REST، ولا Shell & Tube أو ملفات التصنيع أو تصدير CAD/PDF. وجود صلاحية projects:read على مفتاح REST لا ينشئ نقطة نهاية للمشاريع. تبقى تفاصيل التصنيع حصرية لخطة Manufacturer؛ ولا يتيحها هذا الدليل عبر REST.

2. عنوان الأساس والمصادقة

استخدم أصل بيئة ExCoil التي نُشرت فيها الواجهة فعلياً، ثم أضف /api/v1. عنوان الأساس لنطاق الإنتاج هو https://excoil.net/api/v1. المعاينة بيئة مختلفة؛ وجود الكود فيها لا يثبت نشره على نطاق الإنتاج.

أنشئ مفتاحاً من صفحة مفاتيح API واحفظ قيمته الكاملة فوراً، إذ تظهر مرة واحدة فقط. أرسل Authorization: Bearer متبوعاً بمفتاح REST في كل طلب، بما في ذلك GET /health وGET /refrigerants. حافظ على كتابة Bearer بحرف B كبير ومسافة بعدها. ملف تعريف ارتباط تسجيل الدخول وحده لا يصادق على هذه المسارات.

أرسل Content-Type: application/json في طلبات POST للحساب. احفظ المفاتيح في مخزن أسرار على الخادم، لا في حزم المتصفح أو العناوين أو التعليمات النصية أو مستودعات الكود أو السجلات المشتركة. عند فقد مفتاح أو كشفه، ألغِه واستبدله؛ تبقى إدارة المفاتيح القديمة متاحة بعد خفض الخطة.

bash

BASE_URL='https://excoil.net/api/v1'
EXCOIL_API_KEY='exk_REPLACE_WITH_YOUR_REST_KEY'
curl --include "$BASE_URL/health" \
  -H "Authorization: Bearer $EXCOIL_API_KEY"

3. المسارات المنفذة

كل المسارات في الجدول نسبية إلى /api/v1، وتتطلب المصادقة واشتراكاً مؤهلاً. تتطلب طلبات POST للحساب و/refrigerants أيضاً صلاحية calc:read. لا يضيف /health فحص هذه الصلاحية.

الطريقة	المسار	الغرض
GET	/health	حالة الواجهة وإصدارها والطابع الزمني
GET	/refrigerants	معرّفات المبرّدات المتاحة
POST	/calculate/chilled-water	ملف الماء المبرّد
POST	/calculate/hot-water	ملف الماء الساخن
POST	/calculate/steam-coil	ملف البخار
POST	/calculate/dry-cooler	المبرّد الجاف
POST	/calculate/dx-evaporator	مبخّر DX
POST	/calculate/dx-evaporator/balanced	مبخّر DX مع محلل التوازن
POST	/calculate/dx-condenser	مكثّف DX
POST	/calculate/dx-condenser/balanced	مكثّف DX مع محلل التوازن

4. إعداد جسم JSON الصحيح

تستقبل مسارات الحساب العادية كائن إدخال المحرك مباشرة، دون تغليف data أو inputs. يستخدم الماء المبرّد والساخن air وwater وcoil وhydraulic وcalib؛ ويستخدم البخار air وsteam وcoil وhydraulic وcalib؛ وللمبرّد الجاف حقوله الخاصة fluid وair وcoil وhydraulic وcalib. يستخدم DX الحقول air وcoil وref وcalib. تختلف الحقول المطلوبة حسب المحرك؛ لا تنسخ كائن العرض من نموذج الويب أو جسم طلب لوحدة أخرى.

مسار balanced لمبخّر DX هو الاستثناء: أرسل كائناً يحتوي inputs وoptions اختيارياً. يحتوي inputs على إدخال محرك المبخّر كاملاً. أما مسار balanced لمكثّف DX فيستقبل إدخال المكثّف مباشرة، دون تغليف inputs/options الخاص بالمبخّر.

في طلبات DX، استخدم ref.fluid بمعرّف مطابق تماماً لما يعيده /refrigerants. يتعرف الموجّه أيضاً على ref.refrigerant القديم أو refrigerant في المستوى الأعلى لاختيار الجدول، لكن الحقل القياسي للمحرك يبقى ref.fluid. مطابقة الجدول لا تغني عن بقية حقول ref المطلوبة.

تجري طبقة REST فحوصاً محدودة للجسم والمبرّد، لا تحققاً شاملاً من المخطط. ولا تحول وحدات الواجهة تلقائياً أو تملأ كل حقول المحرك الناقصة. تحقق في التكامل من القيم المطلوبة والنطاقات الفيزيائية والهندسة والمعايرة قبل الإرسال.

تفاصيل إدخالات الحاسبات ونتائجها

5. الوحدات جزء من العقد

تستخدم الواجهة أسماء حقول المحرك ووحداته، بصرف النظر عن إعدادات وحدات العرض في التطبيق. يجب تحويل القيم الرقمية قبل إرسال JSON؛ لا ترسل نصوص أرقام منسقة محلياً أو أسماء وحدات داخل الحقول الرقمية.

الحقل أو اللاحقة	المعنى والوحدة
Vdot_m3_s; mdot_kg_s	تدفق حجمي بوحدة m³/s؛ وتدفق كتلي بوحدة kg/s
T_in_C; Tevap_C; *_K	درجة حرارة بوحدة °C؛ وفروق الحرارة أو التحميص بوحدة K
height_m; width_m; Do_m; wall_m	الأبعاد بالمتر، لا بالمليمتر
P_Pa; _Pa; _kPa	الضغط بوحدة Pa أو kPa وفق اسم الحقل
RH_in; freeAreaRatio	كسور من 0 إلى 1، لا نسب مئوية
glycol_pct	نسبة الغليكول المئوية لملفات الماء، لا كسر من 0 إلى 1
fpi	عدد الزعانف لكل بوصة، لا لكل متر
P_steam_kPa	ضغط البخار المقاس بالنسبة للجو بوحدة kPa، لا ضغط مطلق بوحدة Pa
Q_total_W; h_out	القدرة بوحدة W؛ إنثالبي الخروج للماء المبرّد/مبخّر DX بوحدة J/kg من الهواء الجاف

6. قراءة الاستجابة والتشخيص الهندسي

تعيد الحسابات الناجحة {"success":true,"data":...}، حيث data كائن نتيجة المحرك. يستخدم GET /refrigerants التغليف نفسه مع مصفوفة معرّفات. يختلف GET /health، إذ يعيد status وversion وtimestamp مباشرة دون success أو data.

تعني HTTP 200 وsuccess:true أن المحلل أعاد نتيجة، وليس أن كل المعايير الهندسية تحققت. افحص flags وحالة التقارب وnotes وتشخيصات الأداء المتاحة للوحدة. احتفظ بالتحذيرات مع نسخة الإدخالات والنتيجة، ولا تتجاهل بصمت إشارة عدم التقارب أو عدم الجدوى.

تعيد نقاط النهاية المتوازنة نتيجة محللها الخاصة داخل data. راجع عقد النتيجة المحدد، ولا تفترض مسارات perf أو flags متطابقة في كل النقاط. انخفاض خطأ توازن الطاقة تشخيص عددي، وليس تحققاً مستقلاً أو شهادة أو تصريحاً بالتصنيع.

json

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "<طابع زمني ISO-8601>"
}

7. حدود الطلبات وإعادة المحاولة

يعمل المحدد لكل مفتاح REST ولكل عملية خادم. يستخدم rateLimit المضبوط للمفتاح، مع قيمة احتياطية قدرها 100 طلب في الدقيقة إذا كان غائباً أو صفراً. تبدأ نافذة الستين ثانية مع أول طلب مقبول؛ لا تفترض إعادة الضبط في بداية كل دقيقة من الساعة.

بعد المصادقة وفحص الخطة، يستهلك الطلب المقبول من الحد قبل فحص صلاحية المسار أو الحساب. لذا قد تستهلك فحوص الصحة وقوائم المبرّدات وفشل الصلاحيات وأخطاء الحساب من الحد. أما فشل المصادقة أو الخطة فيحدث قبل هذا المحدد.

اقرأ X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. قيمة Reset طابع Unix بالثواني، وليست ميلي ثانية أو مدة انتظار. تتضمن استجابة 429 هذه الرؤوس وrate_limit_exceeded؛ ولا تضبط هذه الطبقة Retry-After. انتظر إعادة الضبط وراعِ اختلاف الساعات واستخدم محاولات محدودة بدلاً من حلقة متواصلة.

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

8. تشخيص أخطاء HTTP والحساب

تعيد أخطاء الموجّه error وmessage دون success:false. افحص حالة HTTP ورمز الخطأ واحتفظ برسالة منقحة من البيانات الحساسة للتشخيص. قد تستخدم أخطاء المحلل أو الوكيل أو البنية التحتية جسماً مختلفاً؛ افحص نوع المحتوى قبل افتراض JSON.

HTTP / error	المعنى	الإجراء
400 / bad_request	جسم عادي غائب/ليس كائناً، أو مبرّد DX غائب/مجهول، أو inputs للمبخّر المتوازن غائب	صحح بنية الجسم ومعرّف المبرّد
401 / unauthorized	رأس Bearer غائب/خاطئ، أو بادئة مفتاح خاطئة، أو مفتاح غير معروف	افحص الرأس ومفتاح REST، لا رمز MCP
403 / forbidden	مفتاح ملغى/منتهي، أو خطة/حالة غير مؤهلة، أو صلاحية ناقصة	افحص المفتاح واشتراك مالكه وcalc:read
422 / calculation_error	استثناء داخل معالج المحلل	راجع الرسالة والإدخالات والوحدات ونطاق التشغيل؛ لا تكرر بلا تغيير إلى ما لا نهاية
429 / rate_limit_exceeded	استنفد المفتاح النافذة الحالية في الذاكرة	استخدم رؤوس الحد وأخّر إعادة المحاولة

json

{
  "error": "unauthorized",
  "message": "Invalid API key."
}

9. قائمة عملية للتكامل

أكد البيئة المستهدفة والاشتراك المؤهل ومفتاح REST المخصص. احفظ المفتاح الكامل بأمان واستخدم بادئته فقط في التشخيص المعتاد.
تحقق من الاتصال عبر /health المصادق عليه، ثم استعلم عن /refrigerants لحسابات DX. احسب الطلبين ضمن ميزانية الطلبات.
اختر المسار وعقد إدخال المحرك بدقة، وحوّل الوحدات صراحة وتحقق من الحقول المطلوبة قبل الطلب. راجع دليل الحاسبات لتفاصيل الوحدة.
أضف Authorization وContent-Type إلى POST وسلسل الإدخال الكامل. استخدم تغليف inputs/options فقط لمبخّر DX المتوازن.
افحص الحالة وشكل الاستجابة ورؤوس الحد والتشخيص الهندسي. احتفظ بالإدخالات المرسلة وإصدار المحرك عند إعادته وجميع التحذيرات مع النتيجة.
صحح أسباب 400/401/403/422 بدلاً من المحاولة العمياء؛ وانتظر عند 429. ألغِ المفاتيح المكشوفة واحصل على مراجعة هندسية قبل الاختيار أو الشراء أو التصنيع.