دليل تكامل MedConnect لنظام المعلومات المخبرية

توثيق واجهة البرمجة ومرجع التكامل — الإصدار 2.0.0

لمزوّدي أنظمة المعلومات المخبرية ونظم معلومات المستشفيات

يوفر هذا الدليل كل ما تحتاجه لربط نظام المعلومات المخبرية (LIS) أو نظام معلومات المستشفيات (HIS) مع MedConnect.

Sham Software Consultancy — 2026

1. نظرة عامة والمصادقة

1.1 ما هو MedConnect؟

MedConnect هو محرك تنسيق يربط أجهزة المختبر الطبية (المحللات) بأنظمة المعلومات المخبرية (LIS/HIS) بتجريد تعقيد بروتوكولات الأجهزة خلف واجهات API بسيطة. يتولى ترجمة البروتوكولات، وربط الاختبارات، وتوجيه الطلبات، وتسليم النتائج، وإعادة المحاولة التلقائية — بحيث لا تحتاج أنظمة HIS/LIS أبداً لفهم ASTM أو HL7 أو البروتوكولات الخاصة مباشرة.

1.2 تدفق الاتصال

يتبع التكامل سير عمل ثلاثي المراحل بغض النظر عن الوضع:

1.3 المصادقة

مصادقة Bearer Token

يدعم MedConnect مصادقة Bearer token اختيارياً. عند التفعيل، يضمّن MedConnect الرمز في كل طلب:

POST /api/orders HTTP/1.1
Authorization: Bearer <your-token-here>
Content-Type: application/json

الإعداد	مطلوب	الوصف
Bearer Token	لا	رمز ثابت يُرسل في ترويسة Authorization

إذا تُرك حقل Bearer Token فارغاً، لن يُرسل MedConnect ترويسة Authorization.

ترويسات الطلب المخصصة

يُرسل MedConnect الترويسات التالية مع كل طلب لتتبع المعاملات:

الترويسة	الوصف
`X-Request-ID`	معرّف فريد لكل طلب (لربط السجلات)
`X-Request-Timestamp`	طابع زمني UTC لوقت إنشاء الطلب
`X-Expected-Sample`	رقم العينة المطلوب الاستعلام عنه (في طلبات الطلبات فقط)
`Content-Type`	application/json
`Accept`	application/json

1.4 سلوك إعادة المحاولة

يطبق MedConnect منطق إعادة المحاولة للتعامل مع الأعطال المؤقتة:

السيناريو	عدد المحاولات	استراتيجية التراجع
استرجاع الطلبات	حتى 3 محاولات	خطي: 100ms × رقم المحاولة
أخطاء HTTP العابرة (5xx، مهلة)	محاولتان إضافيتان	أسي: 2^n ثانية

إرسال النتائج واسترجاع الاختبارات يستخدمان محاولة واحدة. تأكد من موثوقية نقاط النهاية الخاصة بك.

2. مرجع REST API

يوثق هذا القسم REST API الذي يجب على مزود LIS/HIS تنفيذه. يعمل MedConnect كعميل HTTP ويستدعي نقاط النهاية هذه.

جميع نقاط النهاية تستخدم HTTP POST مع حمولات JSON.

2.1 ملخص نقاط النهاية

#	اسم نقطة النهاية	الغرض	مطلوب
1	اختبارات	استرجاع اختبارات LIS المتاحة للربط	نعم
2	طلبات	استرجاع تفاصيل الطلب حسب رقم العينة	نعم
3	نتائج	إرسال نتائج الاختبارات	نعم
4	معالجة	إعلام LIS بمعالجة الطلب	لا

2.2 Tests API

يستخدمها MedConnect للبحث واسترجاع كتالوج اختبارات LIS. يتيح ذلك ربط أكواد اختبارات الأجهزة بأكواد اختبارات LIS.

الطلب

POST <LabTestsAPI URL>
Content-Type: application/json
Authorization: Bearer <token>

الحقل	النوع	مطلوب	الوصف
`Name`	string	لا	فلتر بحث باسم الاختبار (تطابق جزئي)
`Code`	string	لا	فلتر بحث بكود الاختبار (تطابق جزئي)

{"Name": "", "Code": "cbc"}

الاستجابة

الحقل	النوع	مطلوب	الوصف
`ID`	string	نعم	معرّف اختبار LIS الفريد
`Name`	string	نعم	اسم الاختبار المقروء
`Code`	string	نعم	كود اختبار LIS
`Type`	string	لا	نوع العينة لهذا الاختبار

{"tests": [{"ID": "101", "Name": "COMPLETE BLOOD COUNT (CBC)", "Code": "CBC", "Type": "EDTA Whole Blood"}]}

2.3 Orders API

يستخدمها MedConnect لاسترجاع تفاصيل الطلب لعينة محددة. يُرسل MedConnect هذا الطلب عندما يمسح جهاز ما باركود.

POST <TransactionInfoAPI URL>
Content-Type: application/json
X-Request-ID: <unique-uuid>
X-Expected-Sample: <sample-number>

الحقل	النوع	مطلوب	الوصف
`SampleNumber`	string	نعم	رقم الباركود/العينة المطلوب البحث عنها
`allTests`	string	لا	أرسل "1" لاسترجاع جميع الاختبارات. مناسب فقط عند استخدام Processed API.

{"SampleNumber": "2071720201"}

يجب أن يتطابق SampleNumber في الاستجابة مع SampleNumber في الطلب. إذا اختلفا، سيرفض MedConnect الاستجابة ويعيد المحاولة.

2.4 Results API

يستخدمها MedConnect لإرسال نتائج الاختبارات المكتملة إلى LIS.

POST <ResultAPI URL>
Content-Type: application/json

الحقل	النوع	مطلوب	الوصف
`SampleNumber`	string	نعم	رقم العينة التي تنتمي لها النتيجة
`TestCode`	string	نعم	كود اختبار LIS
`SubTestCode`	string	لا	كود الاختبار الفرعي (مستخدم في لوحات الفحوصات)
`Result`	string	نعم	قيمة نتيجة الاختبار

{"results": [{"SampleNumber": "2071630101", "TestCode": "15/11012", "SubTestCode": "", "Result": "36.19"}]}

2.5 Processed API (اختياري)

يستخدمها MedConnect لإعلام LIS بأن الطلب قد تم استلامه ومعالجته بواسطة الجهاز. يتيح ذلك لـ LIS تتبع حالة الطلب ومنع المعالجة المكررة.

POST <OrderCompletedAPI URL>
Content-Type: application/json

الحقل	النوع	مطلوب	الوصف
`SampleNumber`	string	نعم	رقم عينة الطلب المعالج
`Tests`	string	نعم	سلسلة JSON لمصفوفة معرّفات الاختبارات التي تمت معالجتها

{"SampleNumber": "2071720201", "Tests": "[\"100\",\"102\",\"300\"]"}

2.6 خادم API المحلي (دفع وارد)

يمكن لـ MedConnect تشغيل خادم HTTP محلي لاستقبال دفع الطلبات من LIS. هذا مفيد لأنظمة LIS التي تفضل دفع الطلبات بدلاً من انتظار MedConnect للاستقصاء.

POST http://<LocalAPIAddress>:<LocalAPIPort>/api/getSampleData
Content-Type: application/json

الحالة	الشرط
422	بيانات الطلب مفقودة أو فارغة
404	مسار غير معروف
405	طريقة HTTP خاطئة (فقط POST مقبول)
500	خطأ داخلي في الخادم

يتطلب خادم API المحلي صلاحيات مسؤول للتشغيل والربط بالعنوان/المنفذ المحدد.

2.7 معالجة الأخطاء

تنسيق استجابة الخطأ HTTP

عندما يُرجع LIS خطأ، يتوقع MedConnect بنية JSON التالية:

{"message": "Description of what went wrong", "errors": ["Detailed error 1"]}

رموز حالة HTTP

الرمز	المعنى	سلوك MedConnect
200	نجاح	معالجة الاستجابة بشكل طبيعي
400	طلب خاطئ	فشل مع رسالة خطأ
401	غير مصرح	فشل (تحقق من Bearer token)
404	غير موجود	فشل — عنوان URL خاطئ
408	مهلة الطلب	إعادة محاولة (حتى محاولتين إضافيتين)
5xx	خطأ خادم	إعادة محاولة مع تراجع أسي

الأخطاء العابرة (5xx، 408) تؤدي إلى إعادة محاولة تلقائية مع تراجع أسي. الأخطاء غير العابرة (4xx) تفشل فوراً.

3. البيانات المرجعية

يحدد هذا القسم جداول الأكواد والقوائم والقواميس المستخدمة عبر MedConnect API.

3.1 أنواع العينات

القيمة	الوصف
`EDTA`	دم كامل مع EDTA
`Serum`	مصل (دم متخثر، بدون مضاد تخثر)
`Plasma`	بلازما (هيبارين، سيترات، إلخ)
`Urine`	عينة بول
`CSF`	سائل نخاعي
`Whole blood`	دم كامل (بدون مضاد تخثر)
`Other`	أخرى / غير محدد

3.2 ربط الاختبارات

ربط الاختبارات هو عملية ربط أكواد اختبارات LIS بأكواد اختبارات الأجهزة. هذه خطوة إعداد حاسمة.

عملية الربط:

MedConnect يستدعي Tests API لاسترجاع كتالوج اختبارات LIS
يربط المشرف كل اختبار LIS باختبار الجهاز المقابل في واجهة MedConnect
يُخزَّن هذا الربط داخلياً ويُستخدم لتحويل أكواد اختبارات LIS إلى أكواد اختبارات الأجهزة والعكس

4. أمثلة وسير العمل

4.1 أمثلة API تفاعلية — مجموعة Postman

مجموعة Postman كاملة وجاهزة للاستخدام مقدمة مع هذا المستند:

ملف: MedConnect_LIS_API.postman_collection.json

تتضمن المجموعة كل نقطة نهاية API مع أمثلة واقعية للطلبات والاستجابات، وترويسات المصادقة، ومتغيرات البيئة.

⬇ تحميل مجموعة Postman

4.2 سير عمل التكامل الكامل

يتبع التكامل من طرف إلى طرف أربع خطوات متسلسلة:

ربط الاختبارات — استرجاع كتالوج الاختبارات: يستدعي MedConnect Tests API لاسترجاع كتالوج اختبارات LIS، ثم يربط المشغل كل اختبار LIS باختبار الجهاز المقابل.
استرجاع الطلب — الحصول على الطلب بواسطة الباركود: عند مسح جهاز لباركود، يستعلم MedConnect من LIS عن تفاصيل الطلب.
إرسال النتائج — إرسال النتائج إلى LIS: بعد اكتمال الاختبار على الجهاز، يُرسل MedConnect النتائج إلى LIS.
وضع علامة معالجة (اختياري): إعلام LIS بأن الطلب قد تم استلامه ومعالجته بواسطة الجهاز.