التقنية في الصحة الأدلة التقنية

الأهلية Eligibility والموافقة المسبقة Prior Authorization

نبني رسائل الأهلية والموافقة المسبقة بدليل نفيس، ونتحقق منها في HAPI FHIR، ونرد عليها بشركة تأمين وهمية تفحص التغطية والحدود والتشخيص.

الأهلية Eligibility والموافقة المسبقة Prior Authorization

إذا كنت تعمل في فريق تقنية المعلومات في مستشفى خاص أو تبني نظاماً لعيادة، فأنت تعرف المشهد التالي جيداً: مريض يقف عند الاستقبال ومعه بطاقة التأمين، والموظف يحتاج أن يعرف خلال ثوان هل هذه الوثيقة سارية اليوم، وهل المستشفى داخل شبكتها، وكم بقي من حد منفعة الأشعة أو العمليات. وبعد ساعة يقرر الطبيب أن المريض يحتاج إجراء مكلفاً، فيأتي السؤال الثاني: هل توافق شركة التأمين على هذا الإجراء قبل أن نبدأ، أم سوف نكتشف بعد شهر أن البند مرفوض ولا نستطيع أن نطلب المبلغ من المريض؟ هذان السؤالان هما التحقق من الأهلية Eligibility والموافقة المسبقة Prior Authorization، وكلاهما يمر اليوم في السعودية عبر منصة نفيس NPHIES برسائل FHIR يحددها دليل التنفيذ.

وقد شرحنا في مقال التأمين الصحي من الداخل من يدفع ماذا ولماذا ترفض المطالبات، وفي مقال المنصات الصحية في السعودية كيف يتصل نظامك بنفيس من الناحية التقنية، ثم شغلنا في مقال خادم FHIR على سيرفرك سيرفر HAPI FHIR محملاً بدليل نفيس وتحققنا به من مريضة واحدة. وهنا نأخذ الخطوة التالية: نبني الرسائل الكاملة لهاتين المعاملتين، ونتحقق منها مقابل ملفات التعريف الرسمية، ونكتب شركة تأمين وهمية صغيرة ترد عليها بقواعد حقيقية، ونقيس كم يأخذ كل جزء من الوقت. والبيانات كلها وهمية، وهذا ليس اختياراً فقط، فالدليل نفسه ينص على أن بيئات الاختبار يجب ألا تحمل أي بيانات مرضى حقيقية.

وسوف نناقش في هذا المقال ما يلي:

  • ماذا يسأل طلب الأهلية بالضبط، وما الذي يرجع في الرد، ومتى تولد المنصة الرد بنفسها.
  • كيف تعمل الموافقة المسبقة كملف حي يتغير، ولماذا يجب أن تحمل كل الخدمات في كل تعديل.
  • بناء حزمة طلب الأهلية من الصفر، ولماذا مرت النسخة الأولى دون أي خطأ رغم أنها ناقصة.
  • بناء طلب موافقة مسبقة لإجراء في جراحة اليوم الواحد، والمشكلات الحقيقية التي واجهتنا مع ICD-10-AM وSNOMED CT.
  • شركة تأمين وهمية تفحص تواريخ التغطية والشبكة وحدود المنافع والتشخيص، وخطأ في منطقها اكتشفناه من المخرج.
  • قاعدتان في دليل نفيس نفسه ترفضان رداً صحيحاً، وكيف تتعامل مع ذلك في نظامك.
  • زمن كل خطوة، ولماذا التحقق هو الجزء الأبطأ وليس شركة التأمين.

لماذا نسأل قبل الخدمة وليس بعدها؟

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

لذلك تنقسم الأسئلة إلى مرحلتين. الأولى عند الاستقبال أو عند حجز الموعد: هل المريض مؤمن في تاريخ الخدمة، وهل هذا المستشفى داخل شبكته، وما المنافع المتبقية له؟ وهذا هو طلب الأهلية، وهو سريع ورخيص ويمكن أن يتكرر لكل زيارة. والثانية قبل الخدمات المكلفة أو الحساسة فقط: هل توافق الشركة على هذه الخدمة بهذه الكمية لهذا التشخيص؟ وهذا هو طلب الموافقة المسبقة، وقد يحتاج مراجعة بشرية في الشركة. والمرحلتان مرتبطتان، فطلب الموافقة يحمل مرجع رد الأهلية، والمطالبة لاحقاً تحمل مرجع الموافقة، وهذه السلسلة هي التي تجعل شركة التأمين تثق بأن ما تراه في المطالبة سبق أن فحص.

مسار من ثلاث رسائل: طلب الأهلية عند الاستقبال يرجع رداً بمعرف elig-resp، ثم طلب الموافقة المسبقة يحمل هذا المعرف في الامتداد eligibility-response ويرجع رداً فيه preAuthRef وفترة صلاحية preAuthPeriod، ثم المطالبة بعد الخدمة تحمل preAuthRef في Claim.insurance، وكل رسالة تمر عبر نفيس التي تتحقق منها ثم توجهها إلى شركة التأمين
كيف ترتبط الأهلية والموافقة المسبقة والمطالبة بالمعرفات

التحقق من الأهلية Eligibility كما يصفه دليل نفيس

تصف صفحة حالة الأهلية في الدليل الغرض منها بأنه أن يتحقق مقدم الخدمة من تغطية المستفيد، وأن الوثيقة سارية، وأن الخطة سوف تدفع عن الخدمات في هذه المنشأة، وأن يطلب تفاصيل المنافع إذا أراد. والمسار الذي تذكره ست خطوات: يرسل المستشفى الطلب إلى نفيس، فتتحقق المنصة منه، ثم توجهه إلى شركة التأمين أو شركة إدارة المطالبات TPA، فترد الشركة في الوقت الحقيقي، ثم تتحقق المنصة من الرد، ثم ترجعه إلى المستشفى. وهذه معاملة فورية Real Time دائماً، وإذا لم تستطع المنصة إيصال الطلب إلى الشركة خلال دقيقة فإنها تولد الرد بنفسها، وتضع في Bundle.meta.tag علامة nphies-generated لتعرف أن هذا الرد ليس قرار الشركة.

والطلب نفسه مورد CoverageEligibilityRequest، والحقل الأهم فيه هو purpose، لأنه يخبر الشركة ماذا تريد منها بالضبط:

القيمة في purposeماذا تطلب من الشركةماذا يجب أن ترسل معه
validationهل التغطية المرسلة سارية في تاريخ الخدمة؟معرف المريض والتغطية، أو معرف المريض مع discovery
benefitsمنافع الخطة، واختيارياً ما استهلك منهامعرف المريض والتغطية، أو معرف المريض مع discovery
discoveryأي تغطيات أخرى تعرفها الشركة لهذا المريض في تاريخ الخدمةمعرف المريض فقط

ويذكر الدليل أيضاً أن المستشفى الذي لا يعرف تأمين المريض أصلاً يستطيع أن يستخدم واجهة أخرى اسمها HIDP-API ليحصل على قائمة تأميناته، ثم يرسل طلب الأهلية إلى كل شركة منها. أما الرد فهو CoverageEligibilityResponse، وأضاف إليه دليل نفيس امتداداً مهماً اسمه أهلية الموقع Site Eligibility، يجيب بكلمة واحدة عن السؤال العملي الذي يهم موظف الاستقبال. والقيم الثمانية التي يقبلها هذا الامتداد مأخوذة من نظام الرموز siteEligibility:

الرمزالمعنىماذا يفعل الاستقبال
eligibleالمريض مؤهليكمل التسجيل
not-activeالوثيقة غير ساريةيخبر المريض بأن الخدمة على حسابه أو يتحقق من الرقم
not-coveredالوثيقة لا تغطي الخدمات المطلوبةيخبر المريض قبل الخدمة
out-networkالمستشفى خارج شبكة المريضيوجه المريض أو يطلب استثناء
provider-contract-suspendedعقد المستشفى مع الشركة موقوفيرفع الأمر لإدارة العقود
coverage-suspendedتغطية المريض موقوفةيتواصل المريض مع جهة عمله
not-direct billingالمريض غير مغطى بالفوترة المباشرةيدفع المريض ويطالب الشركة بنفسه
limit-exhaustedحد الوثيقة أو المنفعة مستنفديخبر المريض قبل الخدمة

ولاحظ أن أحد هذه الرموز فيه مسافة not-direct billing، وهذا مكتوب هكذا في نظام الرموز نفسه، فإذا كان كودك يقسم القيم على المسافات أو يستخدمها كاسم متغير فسوف يتعثر بها. وماذا لو تعطلت المنصة أو شركة التأمين نفسها؟ يقول الدليل إن المستشفى يستخدم في هذه الحالة وسيلة أخرى مثل بوابة شركة التأمين أو مكتب الدعم، ويحتفظ بتاريخ التحقق اليدوي والمرجع الذي أعطته الشركة، لأنه سوف يرسلهما لاحقاً في الموافقة والمطالبة بامتدادين اسمهما eligibility-offline-reference وeligibility-offline-date.

الموافقة المسبقة Prior Authorization: ملف حي وليس طلباً واحداً

تقسم صفحة الموافقات المسبقة في الدليل الموافقات إلى خمسة أنواع بنفس تقسيم المطالبات: موافقة المنشأة Institutional للتنويم والعمليات، والموافقة المهنية Professional للعيادات والإجراءات التشخيصية، وموافقة الصيدلية Pharmacy للأدوية التي تحتاج موافقة قبل الصرف، وموافقة الأسنان Dental، وموافقة البصريات Vision. وكل منها مورد Claim عادي، ولكن الحقل use فيه قيمته preauthorization وليس claim، ويرجع الرد بمورد ClaimResponse بملف تعريف خاص بالموافقات.

والفرق المهم عن الأهلية أن الموافقة قد لا تأتي فوراً. فإذا استطاعت الشركة أن تقرر آلياً جاء القرار في نفس الجلسة، وإذا احتاجت مراجعة بشرية رجع الرد بأن الطلب في الطابور queued، ثم قد يأتي رد جزئي partial، ثم الرد النهائي complete. وهذه الردود المؤجلة لا تدفع إلى نظامك، وإنما يحتفظ بها نفيس حتى يسأل عنها نظامك بالسحب Polling، وهذا موضوع مقال المطالبات في نفس المرحلة. ويذكر الدليل صراحة أن الموافقة نشاط محدود بالوقت، فإذا لم يصل قرار في الوقت المناسب لعلاج المريض فعلى المستشفى أن يستخدم بوابة الشركة أو الهاتف، ولا ينتظر الرسالة.

والفكرة التي تفاجئ أغلب المطورين هي أن الشركة تدير الموافقة كملف ديناميكي Dynamic Authorization File للخدمات المخطط لها. فأول طلب ينشئ الملف ويرجع مرجعاً في ClaimResponse.preAuthRef، وأي تعديل بعد ذلك ليس طلباً بالفرق، وإنما طلب جديد يحمل نفس المرجع ويحمل كل الخدمات من جديد. والدليل يضرب أمثلة بطلب أصلي فيه أربع خدمات وافقت عليها الشركة كلها:

  • لحذف الخدمة الثالثة: ترسل طلباً جديداً بالمرجع وفيه الخدمات 1 و2 و4.
  • لإضافة خدمة: ترسل 1 و2 و3 و4 ثم 5 الجديدة.
  • لتعديل كمية الخدمة الثالثة: إذا لم يقدم منها شيء تحذفها وتضيفها كخدمة 5، وإذا قدم جزء منها تعدل كميتها وتضع تاريخ تقديمها وتضيف الباقي كخدمة 5.

ويشترط الدليل أن يحافظ المستشفى والشركة على أرقام item.sequence كما هي بين الطلبات والردود، وأن الخدمة التي وافقت عليها الشركة وقدمت فعلاً يجب أن ترسل بتاريخ تقديمها، والشركة يجب ألا ترفضها أو تغير موافقتها عليها. وهذا يعني لمن يصمم قاعدة البيانات أن الموافقة ليست سطراً واحداً بحالة واحدة، وإنما سجل له نسخ، وكل نسخة فيها قائمة خدمات كاملة بأرقام ثابتة، تماماً كما رأينا مع نسخ الموارد في مقال سيرفر FHIR. والإلغاء له قاعدته أيضاً: يلغي المستشفى الموافقة بطلب إلغاء يحمل معرفها، ولا يلغي موافقة انتهت فترتها preAuthPeriod لأنها في حكم الملغاة.

وفي الدليل أيضاً مسار للتحويل Transfer: إذا لم يستطع المستشفى الأول تقديم خدمة، يحدث موافقته ليحذفها، ثم يطلب موافقة تحويل بالامتداد extension-transfer، فترد الشركة بمرجع للمستشفى الثاني وتخبر المريض برسالة نصية، ويعامل المستشفى الثاني هذه الموافقة كموافقة غير إلكترونية Offline يرسل تاريخها في المطالبة. والملاحظة المهمة للمطورين هنا أن الدليل يطلب من الشركة ألا ترفض الخدمات المحولة لأن المستشفى الثاني خارج الشبكة، فإذا كنت تكتب قواعد الشركة فهذا استثناء صريح لقاعدة الشبكة.

المختبر: ما الذي سوف نبنيه؟

نحتاج ثلاثة أجزاء. الأول سيرفر HAPI FHIR محمل بحزمة دليل نفيس، وهو نفس إعداد مقال سيرفر FHIR مع PostgreSQL، ولكننا هنا نستخدمه للتحقق فقط بالعملية $validate، ولا نحفظ فيه شيئاً. والثاني مكتبة Python صغيرة تبني الرسائل من بيانات وهمية، وهي ما سوف يكون في نظام المستشفى. والثالث خدمة Python تلعب دور شركة التأمين، تستقبل الرسالة وترد بقرار. ونضع بين الطرفين خطوة التحقق نفسها التي تقوم بها المنصة: التحقق من الطلب قبل إرساله، والتحقق من الرد قبل قبوله. والملفات كلها في مجلد lab مع هذا المقال.

مخطط المختبر: حاوية العميل فيها مكتبة nphies.py تبني حزمة الطلب، فترسلها إلى HAPI FHIR 8.12.0 المحمل بدليل nphies-fs 1.0.0 للتحقق بالعملية Bundle/$validate، ثم إلى شركة التأمين الوهمية payer.py التي تقرأ payer_db.json وترد بحزمة رد، ثم يتحقق العميل من الرد أيضاً، وHAPI يسأل tx.fhir.org عن رموز SNOMED CT فقط، ويحفظ في PostgreSQL 17
أجزاء المختبر، والتحقق في الاتجاهين كما تفعل المنصة

وملف hapi.yaml هو نفسه من مقال سيرفر FHIR، أي أنه يحمل الحزمة من رابطها الرسمي عند التشغيل:

hapi:
  fhir:
    fhir_version: R4
    install_transitive_ig_dependencies: true
    implementationguides:
      nphies:
        name: nphies-fs
        version: 1.0.0
        packageUrl: https://portal.nphies.sa/ig/package.tgz
        installMode: STORE_AND_INSTALL
        reloadExisting: false
echo "DB_PASSWORD=$(openssl rand -hex 16)" > .env
docker compose up -d
docker logs -f nphies-lab-hapi 2>&1 | grep -E "Installing package|Started Application"
... PackageInstallerSvcImpl        : Installing package: nphies-fs#1.0.0
... ca.uhn.fhir.jpa.starter.Application      : Started Application in 384.874 seconds (process running for 394.83)

أكثر من ست دقائق في أول تشغيل هذه المرة، لأن الجهاز كان مشغولاً بأشياء أخرى، وفي إعادة التشغيل اللاحقة احتاج 189 ثانية مع السطر Package nphies-fs#1.0.0 is already installed. ثم نبني حاوية العميل بنفس الطريقة، وهي Alpine فيها curl وjq وPython، ونشغل منها كل الأوامر التالية على شبكة Compose، والمتغير $B هو عنوان السيرفر. وسكربت التحقق الذي سوف نستخدمه كثيراً يرسل الحزمة إلى Bundle/$validate مع ملف تعريف الحزمة في نفيس، ويطبع الأخطاء فقط إلا إذا طلبت كل شيء:

#!/bin/bash
# validate a message bundle against the NPHIES bundle profile; print one issue per line
# usage: ./validate.sh bundle.json [all]   (default: errors only)
P=http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/bundle
curl -s -X POST "$B/Bundle/\$validate?profile=$P" -H "Content-Type: application/fhir+json" \
  --data-binary @"$1" > /tmp/oo.json
if [ "$2" = "all" ]; then F='.issue[]'; else F='.issue[] | select(.severity=="error" or .severity=="fatal")'; fi
jq -r "$F | \"\(.severity)\t\(.expression[0] // \"-\")\t\(.diagnostics)\"" /tmp/oo.json
echo "errors: $(jq '[.issue[] | select(.severity=="error" or .severity=="fatal")] | length' /tmp/oo.json)  warnings: $(jq '[.issue[] | select(.severity=="warning")] | length' /tmp/oo.json)"

أول طلب أهلية: لماذا مر دون أي خطأ؟

بدأنا كما يبدأ أغلب المطورين: قرأنا تعريف المورد في المعيار الأساسي، وصفحة الحالة في الدليل التي تذكر أن الحزمة من نوع message وأن أول مدخل فيها هو رأس الرسالة MessageHeader، ثم كتبنا سكربتاً يبني الحد الأدنى: رأس رسالة بالحدث eligibility-request، وطلب أهلية بالغرضين validation وbenefits، وتغطية، ومريض بمعرف الإقامة، ومنظمتين للمستشفى وشركة التأمين. وأعلنا ملف تعريف الحزمة فقط في Bundle.meta.profile. والمريض هنا وهمي بالكامل، ورقم الإقامة ورقم العضوية ورخصة المستشفى كلها قيم اخترعناها للمختبر:

patient = {"resourceType": "Patient", "id": m["patient_id"],
           "identifier": [{"system": "http://nphies.sa/identifier/iqama", "value": m["iqama"]}],
           "name": [{"text": m["name"], "family": m["family"], "given": m["given"]}],
           "gender": m["gender"], "birthDate": m["birthDate"]}
req = {"resourceType": "CoverageEligibilityRequest", "id": "elig-1", "status": "active",
       "purpose": ["validation", "benefits"], "patient": {"reference": f"Patient/{m['patient_id']}"},
       "servicedDate": "2026-11-18", "created": "2026-11-18",
       "provider": {"reference": "Organization/prov"}, "insurer": {"reference": "Organization/ins"},
       "insurance": [{"coverage": {"reference": "Coverage/cov-1"}}]}
python3 build_v1.py > elig-v1.json && ./validate.sh elig-v1.json all
warning	Bundle.entry[0].resource/*MessageHeader/4df7b6fe-...*/	Constraint failed: dom-6: 'A resource should have narrative for robust management' ...
warning	Bundle.entry[1].resource/*CoverageEligibilityRequest/elig-1*/	Constraint failed: dom-6: ...
...
errors: 0  warnings: 6

صفر أخطاء، وستة تحذيرات كلها نفس التوصية العامة بأن يحمل كل مورد نصاً مقروءاً. وهنا يجب أن تتوقف ولا تفرح، فقد رأينا في مقال سيرفر FHIR أن مريضة صحيحة في المعيار الأساسي فيها أحد عشر خطأ مقابل ملف تعريف نفيس، وهذه الحزمة فيها نفس المريضة تقريباً. فما الذي حدث؟ السبب أن ملف تعريف الحزمة في نفيس يفحص الحزمة نفسها ولا يفرض ملفات التعريف على ما بداخلها، والمدقق Validator لا يطبق على أي مورد إلا ملفات التعريف التي يعلنها المورد في meta.profile أو التي تطلبها أنت صراحة. وبما أن مواردنا لم تعلن شيئاً، فقد فحصها المدقق مقابل المعيار الأساسي فقط، وهي صحيحة فيه.

والدليل يقول في صفحة كل حالة إن كل موارد الرسالة يجب أن تكون بملفات تعريف نفيس، لذلك أضفنا سكربتاً صغيراً يعلن ملف التعريف المناسب على كل مدخل، ثم أعدنا التحقق:

python3 add_profiles.py elig-v1.json > elig-v2.json && ./validate.sh elig-v2.json
error	Bundle.entry[0].resource/*MessageHeader/...*/	MessageHeader.destination: minimum required = 1, but only found 0 (from .../message-header|1.0.0)
error	Bundle.entry[0].resource/*MessageHeader/...*/	MessageHeader.sender: minimum required = 1, but only found 0 (from .../message-header|1.0.0)
error	Bundle.entry[1].resource/*CoverageEligibilityRequest/elig-1*/	CoverageEligibilityRequest.identifier: minimum required = 1, but only found 0 (from .../eligibility-request|1.0.0)
error	Bundle.entry[1].resource/*CoverageEligibilityRequest/elig-1*/	CoverageEligibilityRequest.priority: minimum required = 1, but only found 0 (from .../eligibility-request|1.0.0)
error	Bundle.entry[2].resource/*Coverage/cov-1*/	Coverage.type: minimum required = 1, but only found 0 (from .../coverage|1.0.0)
error	Bundle.entry[2].resource/*Coverage/cov-1*/	Coverage.policyHolder: minimum required = 1, but only found 0 (from .../coverage|1.0.0)
error	Bundle.entry[2].resource/*Coverage/cov-1*/	Coverage.relationship: minimum required = 1, but only found 0 (from .../coverage|1.0.0)
error	Bundle.entry[2].resource/*Coverage/cov-1*/	Coverage.class: minimum required = 1, but only found 0 (from .../coverage|1.0.0)
error	Bundle.entry[3].resource/*Patient/pat-001*/.identifier[0]	This element does not match any known slice ... slicing is CLOSED ...
...
error	Bundle.entry[3].resource/*Patient/pat-001*/	Constraint failed: BV-00339: 'Patient active is not using the specified value 'true'' ...
error	Bundle.entry[4].resource/*Organization/prov*/	Slice 'Organization.extension:providerType' for extension '.../extension-provider-type': a matching slice is required, but not found ...
error	Bundle.entry[5].resource/*Organization/ins*/.identifier[0]	This element does not match any known slice ... Does not match slice 'payor' ...
errors: 26  warnings: 6

من صفر إلى 26 خطأ بنفس البيانات، والفرق الوحيد سطر meta.profile على كل مورد. وهذا أهم درس في المقال كله، ولذلك وضعناه أولاً: إذا كان اختبارك الآلي يتحقق من الحزمة ولا يعلن ملفات التعريف على مواردها، فسوف يمر كل شيء في بيئتك ثم يرفض في المنصة. ونقرأ الأخطاء مجمعة بحسب المورد:

الموردما ينقصهملاحظة
رأس الرسالةdestination وsenderالمنصة توجه الرسالة بهما، فالمرسل والمستقبل بمعرفات الرخص وليس بالروابط
طلب الأهليةidentifier وpriorityالمعرف التجاري للطلب هو ما يرجع في الرد في request.identifier
التغطيةtype وpolicyHolder وrelationship وclassحامل الوثيقة منظمة منفصلة، والفئة Class هي الخطة
المريضنوع المعرف، والمهنة، والحالة الاجتماعية، وامتداد الجنس، وactiveنفس ما رأيناه في مقال سيرفر FHIR، ومعه قاعدة عمل BV-00339 تشترط active = true
منظمة المستشفىامتداد نوع مقدم الخدمة، وactive، وtypeنوع المقدم من قائمة المنصة: مستشفى، عيادة، صيدلية...
منظمة شركة التأميننوع المعرف NII ليطابق الشريحة payorالمعرفات مقسمة إلى شرائح Slices مغلقة كما في المريض

ولاحظ نوعين مختلفين من الأخطاء في المخرج. الأول أخطاء البنية مثل minimum required = 1، ومصدرها ملف التعريف نفسه. والثاني أخطاء بشكل Constraint failed: BV-00339، وهي قواعد العمل Business Validation التي كتبها فريق المنصة بتعبيرات FHIRPath داخل ملفات التعريف. وقد عددنا هذه القواعد في الحزمة فوجدنا 229 قاعدة مختلفة تبدأ بالبادئة BV، منها قاعدتان فقط على طلب الأهلية و14 على رده، و91 على موافقة المنشأة وحدها. وتشرح صفحة معالجة الأخطاء أن رموز الأخطاء تتبع الشكل RR-NNNNN، حيث BV قواعد العمل والتحقق، وDT نوع بيانات خاطئ، وIB ربط بنظام رموز خاطئ، وIC عدد عناصر خاطئ.

المكتبة التي تبني الرسالة الصحيحة

بعد أن عرفنا ما ينقص، كتبنا مكتبة nphies.py فيها دالة لكل مورد، وكل دالة تعلن ملف تعريفها وتضع الحقول الإلزامية. وهذا جزء دالة التغطية ودالة الطلب:

def coverage(m):
    return {"resourceType": "Coverage", "id": "cov-" + m["key"], "meta": prof("coverage"),
        "identifier": [{"system": INS["endpoint"] + "/memberid", "value": m["member_id"]}],
        "status": "active", "type": cc(CS + "coverage-type", "EHCPOL", "extended healthcare"),
        "policyHolder": {"reference": "Organization/ph"},
        "subscriber": {"reference": "Patient/" + m["patient_id"]},
        "beneficiary": {"reference": "Patient/" + m["patient_id"]},
        "relationship": cc("http://terminology.hl7.org/CodeSystem/subscriber-relationship", "self"),
        "period": {"start": m["start"], "end": m["end"]},
        "payor": [{"reference": "Organization/ins"}],
        "class": [{"type": cc("http://terminology.hl7.org/CodeSystem/coverage-class", "plan"),
                   "value": m["plan"], "name": "Plan " + m["plan"]}],
        "network": m["network"]}

def eligibility_request(m, req_id, serviced, purpose=("validation", "benefits")):
    P = PROV["endpoint"]
    req = {"resourceType": "CoverageEligibilityRequest", "id": req_id, "meta": prof("eligibility-request"),
        "identifier": [{"system": P + "/identifiers/coverageeligibilityrequest", "value": req_id}],
        "status": "active", "priority": cc("http://terminology.hl7.org/CodeSystem/processpriority", "normal"),
        "purpose": list(purpose), "patient": {"reference": "Patient/" + m["patient_id"]},
        "servicedDate": serviced, "created": serviced,
        "provider": {"reference": "Organization/prov"}, "insurer": {"reference": "Organization/ins"},
        "insurance": [{"coverage": {"reference": "Coverage/cov-" + m["key"]}}]}
    h = header("eligibility-request", P + "/CoverageEligibilityRequest/" + req_id)
    return bundle([h, req, coverage(m), policyholder(), provider(), patient(m), insurer()], P)
python3 build_elig.py m1 req-1001 2026-11-18 > elig-v3.json && ./validate.sh elig-v3.json all | grep -v dom-6
information	Bundle.entry[5].resource/*Patient/pat-001*/.maritalStatus	Code validation occurred using a ValueSet expansion that was pre-calculated at 2026-11-18T14:13:39.782+00:00
information	Bundle.entry[6].resource/*Organization/ins*/.identifier[0].type	Code validation occurred using a ValueSet expansion that was pre-calculated at 2026-11-18T14:13:40.333+00:00
errors: 0  warnings: 7

الآن صفر أخطاء ونحن نعلن ملفات التعريف، وهذا صفر له معنى. والحزمة النهائية فيها سبعة مدخلات وحجمها 5,582 بايت بعد ضغط المسافات، أي أن طلباً يسأل سؤالاً واحداً يحمل معه المريض كاملاً والتغطية وحامل الوثيقة والمنظمتين، وهذا طبيعي في الرسائل لأن كل رسالة يجب أن تكون مفهومة وحدها كما شرحنا في مقال المنصات.

ثلاث محاولات لطلب الأهلية: النسخة الأولى دون meta.profile على الموارد مرت بصفر أخطاء لأن المدقق فحصها بالمعيار الأساسي، والنسخة الثانية بنفس البيانات مع إعلان ملفات التعريف فيها 26 خطأ، والنسخة الثالثة من المكتبة صفر أخطاء. وتحتها محاولات الموافقة المسبقة: خمسة أخطاء بسبب ICD-10-AM وSNOMED CT، ثم ستة بعد رفع جزء ICD-10-AM بشكل fragment مع خطأ BV-00846، ثم صفر بعد content complete وإعادة التشغيل وربط SNOMED بخادم مصطلحات
عدد الأخطاء في كل محاولة، وما الذي غيرناه بين كل محاولة والتي بعدها

طلب موافقة مسبقة لإجراء في جراحة اليوم الواحد

الحالة في المختبر مريض وهمي عمره 47 سنة يعاني من نوبات خفقان، وشخص الطبيب عنده رجفاناً أذينياً انتيابياً، وقرر إجراء الكي بالقسطرة Catheter Ablation في جراحة اليوم الواحد. وطلب الموافقة فيه بندان: استشارة أخصائي برمز 83600-00-10، والإجراء برمز 38287-02-00، وكلاهما من الرموز المنشورة في الدليل نفسه، لأن نظام الفوترة السعودي SBS كاملاً ينشره مجلس الضمان الصحي وقد شرحناه في مقال الترميز الطبي. والأسعار في المختبر وهمية: 350 ريالاً للاستشارة و18,500 ريال للإجراء.

واخترنا ملف تعريف موافقة المنشأة institutional-priorauth مع زيارة من نوع جراحة اليوم الواحد encounter-auth-SS. وهذا الملف أثقل ملفات التعريف في الحزمة كما رأينا، لأنه يطلب العلامات الحيوية كلها، والشكوى الرئيسية، والتاريخ المرضي، وخطة العلاج، والفحص السريري، ونتائج الفحوص، والمدة المتوقعة للإقامة، وكل منها عنصر في supportingInfo برقم تسلسل، ثم يشير كل بند في الطلب إلى هذه الأرقام. وهذا جزء الدالة التي تبنيها:

rows = [("vital-sign-systolic", q(v["sys"], "mm[Hg]")), ("vital-sign-diastolic", q(v["dia"], "mm[Hg]")),
        ("vital-sign-height", q(v["height"], "cm")), ("vital-sign-weight", q(v["weight"], "kg")),
        ("pulse", q(v["pulse"], "/min")), ("temperature", q(v["temp"], "Cel")),
        ("oxygen-saturation", q(v["spo2"], "%")), ("respiratory-rate", q(v["rr"], "/min"))]
info = []
for cat, val in rows:
    info.append({"category": cc(CS + "claim-information-category", cat), "timingPeriod": per, "valueQuantity": val})
info.append({"category": cc(CS + "claim-information-category", "chief-complaint"),
             "code": cc("http://hl7.org/fhir/sid/icd-10-am", v["complaint_code"], v["complaint"])})

ولاحظ أن الوحدات ليست نصاً حراً، فقواعد العمل في الدليل تحدد وحدة UCUM لكل علامة: mm[Hg] للضغط، و/min للنبض والتنفس، وCel للحرارة، وkg للوزن. والتشخيص الرئيسي I48.0 بنظام ICD-10-AM، والشكوى الرئيسية الخفقان كتبناها في المحاولة الأولى بنفس النظام R00.2. ثم تحققنا:

error	.../diagnosis[0].diagnosis.ofType(CodeableConcept)	CodeSystem is unknown and can't be validated: http://hl7.org/fhir/sid/icd-10-am for 'http://hl7.org/fhir/sid/icd-10-am#I48.0'
error	.../supportingInfo[8].code.coding[0]	CodeSystem is unknown and can't be validated: http://hl7.org/fhir/sid/icd-10-am for 'http://hl7.org/fhir/sid/icd-10-am#R00.2'
error	.../supportingInfo[8].code.coding[0]	The Coding provided (http://hl7.org/fhir/sid/icd-10-am#R00.2) was not found in the value set 'SNOMED CT Clinical Findings' (http://hl7.org/fhir/ValueSet/clinical-findings|4.0.1), and a code is required from this value set. ...
error	.../diagnosis[0].diagnosis.ofType(CodeableConcept)	Unable to expand ValueSet because CodeSystem could not be found: http://hl7.org/fhir/sid/icd-10-am
error	.../diagnosis[0].diagnosis.ofType(CodeableConcept)	None of the codings provided are in the value set 'ICD-10-AM' (http://nphies.sa/terminology/ValueSet/diagnosis-icd-10-am|1.0.0), and a coding from this value set is required) ...
errors: 5  warnings: 14

هنا مشكلتان حقيقيتان سوف تواجه أي فريق يبني هذا الربط. الأولى أن الشكوى الرئيسية في ملف التعريف مربوطة بقائمة قيم من SNOMED CT هي الموجودات السريرية Clinical Findings، وليس بنظام ICD، رغم أن نص إحدى قواعد العمل يذكر ICD 10. والأمثلة المنشورة داخل الحزمة نفسها تستخدم SNOMED CT في هذا الحقل، لذلك اتبعنا الربط وغيرنا الرمز إلى 80313002 وهو رمز الخفقان في SNOMED CT. والقاعدة العامة هنا: عندما يختلف النص عن الربط Binding في ملف التعريف، فالمدقق يتبع الربط، والأمثلة الرسمية هي أفضل دليل على ما تتوقعه المنصة.

والمشكلة الثانية أكبر: قائمة قيم التشخيص في الحزمة تقول ببساطة «كل رموز النظام http://hl7.org/fhir/sid/icd-10-am»، ولكن الحزمة لا تحمل هذا النظام نفسه، والسبب أن ICD-10-AM تصنيف مرخص كما شرحنا في مقال المصطلحات الطبية الموحدة. ونفس الشيء مع SNOMED CT. فالمدقق في سيرفرك لا يعرف إن كان I48.0 رمزاً صحيحاً، ويرفض الحقل لأن الربط إلزامي Required.

الحل الأول: جزء من ICD-10-AM في السيرفر، ومشكلة لم نتوقعها

الحل البسيط في بيئة الاختبار أن ترفع إلى السيرفر مورد CodeSystem بنفس الرابط فيه الرموز التي تستخدمها اختباراتك فقط، والمعيار يسمح بوصف هذا النوع من الموارد بأنه جزء من نظام أكبر بالقيمة content: fragment كما في تعريف الحقل content. فكتبنا هذا الملف ورفعناه:

{
  "resourceType": "CodeSystem",
  "id": "icd-10-am-lab-fragment",
  "url": "http://hl7.org/fhir/sid/icd-10-am",
  "version": "lab-fragment",
  "title": "ICD-10-AM: the few codes used in this lab only (not the licensed classification)",
  "status": "active",
  "content": "fragment",
  "concept": [
    { "code": "I48.0", "display": "Paroxysmal atrial fibrillation" },
    { "code": "J45.9", "display": "Asthma, unspecified" },
    { "code": "R00.2", "display": "Palpitations" }
  ]
}

وأعدنا التحقق، فبقيت أخطاء ICD-10-AM الثلاثة كما هي. وسألنا السيرفر مباشرة بالعملية $validate-code عن الرمز I48.0، فرجع result: false مع نفس الرسالة CodeSystem is unknown. فغيرنا القيمة إلى content: complete، وانتظرنا عشر دقائق نسأل كل 15 ثانية، ولم يتغير شيء. ثم جربنا نفس الملف برابط مختلف لم يسأل عنه السيرفر من قبل وبالقيمة complete، فرجع result: true فوراً. فأعدنا تشغيل HAPI، ورفعنا ملف ICD-10-AM من جديد بالقيمة fragment فرجع false، ثم بالقيمة complete فبقي false، حتى أعدنا التشغيل مرة ثانية، فرجع بعدها:

{"resourceType":"Parameters","parameter":[{"name":"result","valueBoolean":true},{"name":"display","valueString":"Paroxysmal atrial fibrillation"}]}

أي أن السلوك الذي رأيناه في HAPI 8.12.0 له جزءان: النظام بالقيمة fragment لم يستخدم في التحقق إطلاقاً، وبعد أن سأل السيرفر عن نظام لا يعرفه بقيت النتيجة السلبية محفوظة في الذاكرة حتى بعد أن أضفنا النظام، فلم يظهر التغيير إلا بعد إعادة التشغيل. لذلك إذا رفعت أنظمة رموز إلى سيرفر التحقق في بيئتك، فارفعها قبل أول طلب تحقق، أو أعد التشغيل بعدها، ولا تحكم على النتيجة من أول محاولة. ولاحظ أننا كتبنا في عنوان الملف أنه رموز المختبر فقط، لأن القيمة complete هنا ليست صحيحة من حيث المعنى، وهذا مقبول في سيرفر اختبار لا يرى أحد غيرك، ولكن لا تضعه في سيرفر يعتمد عليه فريق آخر.

الحل الثاني: خادم مصطلحات Terminology Server لرموز SNOMED CT

أما SNOMED CT فالفحص فيه أصعب، لأن قائمة الموجودات السريرية ليست قائمة رموز، وإنما قاعدة «كل ما هو تحت المفهوم كذا في الشجرة»، ولا يستطيع جزء صغير من الرموز أن يجيب عنها. والحل الذي يقدمه HAPI هو أن يسأل خادم مصطلحات بعيداً عن نظام معين، وهو مذكور في ملف الإعداد الافتراضي للإصدار الذي نستخدمه. فأضفنا إلى hapi.yaml:

    # SNOMED CT is not in the NPHIES package: ask a terminology server for it (test only)
    remote_terminology_service:
      snomed:
        system: "http://snomed.info/sct"
        url: "https://tx.fhir.org/r4/"

والخادم tx.fhir.org خادم اختبار عام يديره مجتمع HL7، وهو مناسب لمختبر ببيانات وهمية، ولكن لا ترسل إليه شيئاً من بيئة فيها بيانات حقيقية، لأن الرمز وحده قد يكشف تشخيص مريض إذا ارتبط بسياقه. وفي الإنتاج يكون هذا خادم مصطلحات داخلياً مرخصاً، وهذا موضوع قسم خادم المصطلحات في مقال المصطلحات الطبية. وبعد إعادة التشغيل اختفت أخطاء SNOMED CT. وكان قد ظهر في المحاولة السابقة نفسها، التي رفعنا فيها جزء ICD-10-AM أول مرة، خطأ جديد ليس من أخطاء الرموز:

error	.../supportingInfo[14]	Constraint failed: BV-00846: 'Supporting information 'investigation-result' requires a attachment when attachment code is used with Code = 'IRA'.' (defined in .../institutional-priorauth)

وقصة هذا الخطأ تستحق أن تروى. ففي المحاولة الأولى كتبنا نتيجة الفحوص بالرمز NA ونص العرض «Normal and abnormal results»، لأننا افترضنا أن NA اختصار لهذا المعنى، فجاء تحذير بأن العرض الصحيح للرمز هو «Not applicable». أي أن افتراضنا كان سيرسل للشركة أن الفحوص لا تنطبق على مريض أجرى تخطيط قلب. فقرأنا نظام الرموز في الحزمة، ووجدنا خمسة رموز فقط: الفحوص لم تجر INP، والنتائج مرفقة IRA، وأخرى other، ولا ينطبق NA، والنتائج معلقة IRP. فاخترنا IRA، فطلبت القاعدة BV-00846 مرفقاً فعلياً، وهذا منطقي. وفي المختبر لا نريد إرفاق ملفات، فاخترنا other مع نص يصف النتيجة، وهذا ما تشترطه قاعدة أخرى للرمز other. والدرس هنا أن تحذيرات عرض الرموز Display ليست تفاصيل شكلية، فقد تكون الإشارة الوحيدة إلى أنك فهمت الرمز خطأ.

warning	.../extension[0].value.ofType(Reference)	Found multiple matching profiles for Encounter/enc-auth-2001 among choices: .../encounter-auth-IMP|1.0.0, .../encounter-auth-SS|1.0.0
warning	.../Coverage/cov-m1*/.type	A definition for CodeSystem 'http://nphies.sa/terminology/CodeSystem/coverage-type' could not be found, so the code cannot be validated
errors: 0  warnings: 12

صفر أخطاء، والحزمة فيها تسعة مدخلات وحجمها 14,687 بايت، أي قرابة ثلاثة أضعاف طلب الأهلية، وأغلب الفرق في المعلومات الداعمة. وبقي تحذير يقول إن الزيارة تطابق ملفي تعريف معاً: زيارة التنويم IMP وزيارة اليوم الواحد SS، والسبب أن الزيارة نفسها تعلن SS، ولكن المرجع من الطلب يقبل أكثر من ملف تعريف، والمدقق يخبرك أنه لا يستطيع أن يعرف أيهما تقصد من البنية وحدها. وتحذير آخر غريب بأن نظام رموز نوع التغطية غير موجود رغم أنه في الحزمة، ولم يظهر قبل إعادة التشغيل، وهو من نفس عائلة مشكلة الذاكرة المؤقتة، ولا يمنع الإرسال.

نجرب العطل: علامة حيوية ناقصة وعملة خاطئة

ماذا يحدث لو نسي نظام المستشفى النبض لأن الممرضة لم تقسه، وأرسل الإجراء بالدولار بالخطأ؟ حذفنا من الحزمة عنصري النبض والمدة المتوقعة للإقامة، وغيرنا عملة البند الثاني:

jq '(.entry[1].resource.supportingInfo) |= map(select(.category.coding[0].code != "pulse" and .category.coding[0].code != "estimated-Length-of-Stay"))
    | .entry[1].resource.item[1].net.currency = "USD"' pa-v3.json > pa-broken.json
./validate.sh pa-broken.json
error	.../Claim/auth-2001*/	Claim.supportingInfo: minimum required = 14, but only found 13 (from .../institutional-priorauth|1.0.0)
error	.../Claim/auth-2001*/	Slice 'Claim.supportingInfo:pulse': a matching slice is required, but not found ...
error	.../item[1].net	Constraint failed: BV-00093: 'Claim Item Net Currency is not SAR.' ...
error	.../item[1].net.currency	Value is 'USD' but is fixed to 'SAR' in the profile .../DP-Money-SAR|1.0.0#Money.currency
error	.../Claim/auth-2001*/	Constraint failed: BV-00765: 'Pulse SHALL be provided in institutional claim or authorization.' ...
errors: 5  warnings: 12

في المخرج أعلاه لاحظ التالي:

  • النبض الناقص ظهر ثلاث مرات بثلاث صياغات: العدد الأدنى للمعلومات الداعمة، والشريحة المطلوبة، وقاعدة العمل BV-00765. فلا تعد الأخطاء لتعرف حجم المشكلة، واجمعها بحسب المكان.
  • العملة ظهرت مرتين: قيمة ثابتة Fixed في نوع البيانات، وقاعدة BV-00093.
  • المدة المتوقعة للإقامة حذفت ولم تظهر لها قاعدة خاصة، رغم أن في الحزمة قاعدة BV-00802 تقول إنها إلزامية في موافقة المنشأة. وكل ما كشفها هو العدد الأدنى 14.
  • بعد الحذف أصبحت أرقام informationSequence في البنود تشير إلى أرقام لم تعد موجودة، ولم يعترض المدقق على ذلك.

وهذه النقطتان الأخيرتان هما سبب أن نجاح التحقق في سيرفرك لا يعني قبول المنصة، فمدقق المنصة قد يطبق قواعد لا يعبر عنها ملف التعريف، وقد يقرأ نفس القاعدة بشكل مختلف. لذلك أضف إلى اختباراتك فحوصاً بسيطة من عندك، مثل أن كل رقم في informationSequence موجود فعلاً في supportingInfo.

شركة تأمين وهمية بقواعد حقيقية

الآن الطرف الآخر. كتبنا خدمة payer.py بمكتبة Python القياسية فقط، تستقبل الحزمة بطلب POST، وتقرأ رمز الحدث من رأس الرسالة، وترد بحزمة رد كاملة. وبياناتها في ملف payer_db.json: عضوان وهميان، وخطة اسمها SILVER-B بحد سنوي مليون ريال وحد منفعة للعمليات 60 ألفاً وللاستشارات ثمانية آلاف، ونسبة تحمل 20% على الاستشارات بسقف 75 ريالاً، وما استهلكه العضو الأول هذه السنة: 48 ألفاً من حد العمليات. وفيها أيضاً جدول الخدمات التي تحتاج موافقة مسبقة، ومع كل منها بادئات التشخيصات التي تبررها:

"prior_auth": {
  "38287-02-00": {"dx_prefixes": ["I47", "I48", "I49"]},
  "33509-00-00": {"dx_prefixes": ["I70", "I71"]}
}

والأرقام والخطة كلها افتراضية للمختبر، ولا تمثل جدول منافع أي وثيقة حقيقية. أما المنطق فهو ترتيب الفحوص التالي، والترتيب هنا قرار تصميم وليس تفصيلاً:

def site_check(member, provider_license, date):
    """order matters: unknown member, then coverage dates, then network"""
    if member is None:
        return "not-active", "Member not found"
    if not (member["start"] <= date <= member["end"]):
        return "not-active", "Coverage is not in force on " + date
    if member["network"] not in DB["provider_networks"].get(provider_license, []):
        return "out-network", "Provider is outside the member network " + member["network"]
    return "eligible", "Coverage is in force"

def adjudicate_item(it, dx_codes, remaining):
    """returns (outcome, approved amount, reason code, benefit category)"""
    code = it["productOrService"]["coding"][0]["code"]
    cat = DB["service_category"].get(code, "1")
    net = it["net"]["value"]
    rule = DB["prior_auth"].get(code)
    if rule is None:
        return "not-required", net, None, cat
    if not any(d.startswith(p) for d in dx_codes for p in rule["dx_prefixes"]):
        return "rejected", 0, "AD-1-4", cat           # diagnosis does not support the procedure
    left = min(remaining.get(cat, 0), remaining["1"])  # the sub-limit and the annual limit
    if left <= 0:
        return "rejected", 0, "CV-1-8", cat           # limit already exhausted
    if net > left:
        return "partial", left, "CV-1-8", cat         # approve what is left
    return "approved", net, None, cat

وقد يتساءل البعض: لماذا نفحص التواريخ قبل الشبكة؟ والإجابة أن الرد يحمل رمزاً واحداً في أهلية الموقع، فإذا كانت الوثيقة منتهية والمستشفى خارج الشبكة معاً، فالرمز المفيد للاستقبال هو أن الوثيقة غير سارية، لأن تغيير المستشفى لن يحل المشكلة. وكل رمز رفض في الكود من قائمة أسباب التسوية في الدليل: AD-1-4 أي التشخيص لا يتوافق مع الخدمة، وCV-1-8 أي تجاوز الحد السنوي أو حد المنفعة، وCV-2-1 أي المريض ليس عضواً مغطى، وCV-1-1 أي مقدم الخدمة خارج شبكة المستفيد. ونشغل الخدمة في Container من نفس صورة العميل على شبكة المختبر، ثم نمرر عنوانها لسكربتات العميل في المتغير $PAYER:

docker build -t nphies-lab-client -f client.Dockerfile .
docker run -d --name nphies-lab-payer --network nphies-lab -v "$PWD:/lab" -w /lab nphies-lab-client python3 payer.py
docker run --rm -it --network nphies-lab -e B=http://hapi:8080/fhir -e PAYER=http://nphies-lab-payer:8080 \
  -v "$PWD:/lab" nphies-lab-client bash
ترتيب فحوص شركة التأمين الوهمية: العضو موجود؟ ثم التاريخ داخل فترة التغطية؟ وإلا not-active، ثم المستشفى داخل الشبكة؟ وإلا out-network، ثم لكل بند: يحتاج موافقة؟ وإلا not-required، ثم التشخيص يبرره؟ وإلا رفض AD-1-4، ثم المتبقي من حد المنفعة والحد السنوي يكفي؟ وإلا موافقة جزئية بالمتبقي مع CV-1-8، ثم نسبة التحمل على الاستشارات 20 بالمئة بسقف 75 ريالاً
ترتيب الفحوص في شركة التأمين الوهمية، ورمز السبب الذي يرجع مع كل رفض

نشغل المسار كاملاً: أربع حالات

السكربت flow.py يمثل نظام المستشفى في زيارة واحدة: يبني طلب الأهلية، ويتحقق منه، ويرسله، ويتحقق من الرد، ثم إذا كان المريض مؤهلاً يبني طلب الموافقة ومعه معرف رد الأهلية في الامتداد eligibility-response، ويتحقق منه، ويرسله، ويتحقق من الرد. ويقيس زمن كل خطوة. وشغلناه في أربع حالات: العضو الأول بتشخيص الرجفان الأذيني، ثم نفس العضو بتشخيص الربو بدل الرجفان، ثم العضو الثاني الذي انتهت وثيقته في مايو، ثم العضو الأول في مستشفى ثان رخصته PR-DEMO-0002 وشبكته أدنى من شبكة العضو:

python3 flow.py m1 af 1; python3 flow.py m1 asthma 2; python3 flow.py m2 af 3
PROVIDER_LICENSE=PR-DEMO-0002 python3 flow.py m1 af 4
eligibility: eligible | inforce=True | Coverage is in force | response errors=0
  benefit  1 Annual limit  allowed   1000000 used    52300
  benefit  2 Surgical      allowed     60000 used    48000
  benefit  3 Consultation  allowed      8000 used     1250
priorauth: partial | preAuthRef=PA-09D03132 | response errors=0
  item 1: not-required eligible      350 copay  70.0
  item 2: partial      eligible    12000 copay     0 CV-1-8
timings (ms): build eligibility 0, validate request 2594, payer eligibility 5, validate response 13796, build priorauth 0, validate request 6571, payer priorauth 6, validate response 5913
---
eligibility: eligible | inforce=True | Coverage is in force | response errors=0
  ...
priorauth: partial | preAuthRef=PA-4F31FFC3 | response errors=0
  item 1: not-required eligible      350 copay  70.0
  item 2: rejected     eligible        0 copay     0 AD-1-4
---
eligibility: not-active | inforce=False | Coverage is not in force on 2026-11-25 | response errors=2
---
eligibility: out-network | inforce=True | Provider is outside the member network N2 | response errors=2

في المخرج أعلاه لاحظ التالي:

  • الحالة الأولى: رد الأهلية يرجع المنافع الثلاث مع المستهلك منها، فيعرف المستشفى قبل أن يطلب الموافقة أن المتبقي من حد العمليات 12 ألفاً فقط، والإجراء بـ 18,500. ثم جاءت الموافقة جزئية بالمبلغ المتبقي بالضبط، مع السبب CV-1-8. وهذه المعلومة يجب أن تصل إلى الطبيب والمريض قبل الإجراء، لأن الفرق 6,500 ريال سوف يدفعه المريض أو يتحمله المستشفى.
  • الاستشارة لا تحتاج موافقة، فرجعت not-required مع نسبة التحمل 70 ريالاً، أي 20% من 350، وهو أقل من السقف 75.
  • الحالة الثانية: التشخيص الربو لا يبرر الكي بالقسطرة، فرفض الإجراء بالسبب AD-1-4. ولكن النتيجة الإجمالية partial ومعها مرجع موافقة. توقف عند هذا السطر، وسوف نعود إليه.
  • الحالتان الثالثة والرابعة: الوثيقة المنتهية رجعت not-active مع inforce=False، والمستشفى خارج الشبكة رجع out-network مع inforce=True، لأن الوثيقة سارية فعلاً والمشكلة في المكان. ولم ينتقل السكربت إلى الموافقة في الحالتين. ولكن لاحظ response errors=2: رد شركة التأمين نفسه فشل في التحقق.

خطأ في منطقنا: موافقة جزئية على لا شيء

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

# the overall outcome looks only at the items that needed authorization:
# a consultation that never needed approval must not turn a refusal into a partial approval
outs = {x["extension"][0]["valueCodeableConcept"]["coding"][0]["code"] for x in items} - {"not-required"}
outs = outs or {"approved"}
priorauth: rejected | preAuthRef=- | response errors=0
  item 1: not-required eligible      350 copay  70.0
  item 2: rejected     eligible        0 copay     0 AD-1-4

والملاحظة المهمة أن المدقق لم يعترض على النسخة الخاطئة، فالرد كان صحيحاً تماماً من حيث البنية. فالتحقق يضمن أن الرسالة مفهومة، ولا يضمن أن القرار فيها معقول، وهذا ما تحتاج له اختبارات بأمثلة تعرف نتيجتها مسبقاً، كما سوف نفعل بتوسع في مقال تدقيق المطالبات.

ردان صحيحان يرفضهما الدليل

نعود الآن إلى الخطأين في رد الحالتين الثالثة والرابعة:

error	.../CoverageEligibilityResponse/elig-resp-req-m2-x*/	Constraint failed: BV-00559: 'The CoverageEligibiltyResponse.extension.siteEligibility value SHALL be 'eligible' if at least in one array entry of CoverageEligibiltyResponse.insurance the related CoverageEligibilityResponse.insurance.siteEligibility is 'eligible'.' ...
error	.../CoverageEligibilityResponse/elig-resp-req-m2-x*/	Constraint failed: BV-00561: 'The CoverageEligibiltyResponse.extension.siteEligibility value SHALL not be 'eligible' if for every array entry of CoverageEligibiltyResponse.insurance the related CoverageEligibilityResponse.insurance.siteEligibility is not 'eligible'.' ...
errors: 2  warnings: 9

اقرأ نص القاعدتين: الأولى تقول إن القيمة العامة يجب أن تكون مؤهلاً إذا كانت إحدى التغطيات مؤهلة، والثانية تقول إن القيمة العامة يجب ألا تكون مؤهلاً إذا لم تكن أي تغطية مؤهلة. وردنا فيه القيمة not-active في المكانين، أي أنه يطابق النصين. فلماذا فشل؟ قرأنا تعبير FHIRPath للقاعدتين في ملف التعريف داخل الحزمة، فوجدنا أن الفرع الذي يعالج القيمة غير المؤهلة في كل منهما يرجع false بدل true، أي أن أي رد بقيمة غير مؤهلة سوف يفشل مهما كان. ولكي نتأكد أن الخطأ ليس في ردنا، أخذنا مثال رد الأهلية المنشور في الحزمة نفسها، وهو بقيمة eligible، وغيرنا فيه القيمة فقط:

# ig-example-eligible
errors: 0  warnings: 2
# ig-example-not-active
BV-00559
BV-00561
errors: 2  warnings: 2
# ig-example-not-active-noins
BV-00561
errors: 1  warnings: 2

المثال الرسمي كما هو يمر، وبعد تغيير القيمة إلى not-active في المكانين يفشل بنفس القاعدتين، وحتى بعد حذف القيمة من مستوى التغطية تبقى القاعدة الثانية. وبما أن قاعدة أخرى BV-00503 تشترط وجود أهلية الموقع في كل رد نتيجته complete، فالنتيجة أن الإصدار 1.0.0 من الحزمة لا يقبل في المدقق أي رد أهلية بقيمة غير مؤهلة. ولا نعرف إن كان مدقق المنصة الفعلي يطبق التعبير بنفس الشكل، فقد يكون هذا خطأ في نسخة الحزمة المنشورة فقط.

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

زمن كل خطوة Timings: أين يذهب الوقت؟

في التشغيل الأول كانت الأرقام كبيرة: 13.8 ثانية للتحقق من أول رد أهلية، و6.5 ثانية لأول طلب موافقة، لأن المدقق يحمل ملفات التعريف وقوائم القيم إلى الذاكرة عند أول استخدام. ثم شغلنا الحالة الأولى عشر مرات متتالية، وهذه المخرجات كما هي:

timings (ms): build eligibility 0, validate request 466, payer eligibility 4, validate response 370, build priorauth 1, validate request 900, payer priorauth 4, validate response 1045
timings (ms): build eligibility 0, validate request 536, payer eligibility 4, validate response 538, build priorauth 1, validate request 1404, payer priorauth 3, validate response 450
timings (ms): build eligibility 0, validate request 537, payer eligibility 3, validate response 651, build priorauth 1, validate request 1379, payer priorauth 4, validate response 423
timings (ms): build eligibility 0, validate request 402, payer eligibility 4, validate response 481, build priorauth 1, validate request 944, payer priorauth 4, validate response 511
timings (ms): build eligibility 0, validate request 318, payer eligibility 5, validate response 354, build priorauth 1, validate request 863, payer priorauth 4, validate response 546
timings (ms): build eligibility 0, validate request 414, payer eligibility 3, validate response 512, build priorauth 1, validate request 1351, payer priorauth 5, validate response 469
timings (ms): build eligibility 0, validate request 463, payer eligibility 4, validate response 1059, build priorauth 1, validate request 2452, payer priorauth 15, validate response 2047
timings (ms): build eligibility 0, validate request 1094, payer eligibility 22, validate response 1731, build priorauth 1, validate request 4365, payer priorauth 12, validate response 1024
timings (ms): build eligibility 0, validate request 299, payer eligibility 7, validate response 397, build priorauth 1, validate request 966, payer priorauth 5, validate response 524
timings (ms): build eligibility 0, validate request 311, payer eligibility 4, validate response 695, build priorauth 1, validate request 1306, payer priorauth 17, validate response 757
الخطوةالوسيط Median في عشر مراتأقل وأعلى
بناء طلب الأهليةأقل من 1 ms0
التحقق من طلب الأهلية440 ms299 إلى 1,094
قرار شركة التأمين الوهمية4 ms3 إلى 22
التحقق من رد الأهلية525 ms354 إلى 1,731
التحقق من طلب الموافقة1,328 ms863 إلى 4,365
التحقق من رد الموافقة535 ms423 إلى 2,047

والمعنى العملي واضح: منطق القرار نفسه يأخذ أجزاء من الألف من الثانية، والتحقق يأخذ مئات أضعافه. وطلب الموافقة أبطأ من غيره لأنه أكبر، ولأن الشكوى الرئيسية فيه برمز SNOMED CT يسأل عنه المدقق خادماً بعيداً عبر الإنترنت، والتذبذب الكبير في المرة الثامنة على الأغلب من هذا الطلب الخارجي ومن الجهاز نفسه. وهذه أرقام مختبر على جهاز واحد، ولا تمثل زمن المنصة، ولكنها تكفي لاستنتاج قرارات تصميم:

  • لا تجعل موظف الاستقبال ينتظر التحقق المحلي قبل كل طلب أهلية. تحقق من القوالب في اختبارات النظام وعند كل تحديث للحزمة، واترك التحقق الفعلي للمنصة التي سوف تفعله على أي حال.
  • إذا أردت التحقق المحلي قبل الإرسال، فشغل المدقق دافئاً، أي أرسل له طلباً تجريبياً عند التشغيل، لأن أول طلب قد يأخذ عشرات الثواني.
  • لا تجعل التحقق يعتمد على خادم مصطلحات خارجي في مسار الطلب الحي، فتعطله يعني أن الاستقبال يتوقف.
  • تذكر حد الدقيقة في المنصة: إذا لم تستطع المنصة إيصال الطلب خلال دقيقة فإنها ترد بنفسها، فاجعل مهلة Timeout الطلب في نظامك أطول من ذلك، وإلا قطعت الاتصال قبل أن يأتي رد المنصة.
أعمدة أفقية للوسيط في عشر مرات: التحقق من طلب الموافقة 1328 مللي ثانية، والتحقق من رد الموافقة 535، والتحقق من رد الأهلية 525، والتحقق من طلب الأهلية 440، وقرار شركة التأمين الوهمية 4 مللي ثانية، وبناء الرسالة أقل من 1، ومعها أول تشغيل بارد 13796 مللي ثانية للتحقق من أول رد
الوسيط في عشر مرات بعد أن سخن المدقق: القرار أجزاء من الألف، والتحقق مئات المللي ثانية

كيف تصمم هذا في نظام المستشفى؟

بعد المختبر نستطيع أن نرتب ما يحتاجه نظام المستشفى، والقاعدة العامة أن كل رسالة وكل رد يحفظ كما هو، لأن كل واحد منهما مرجع قانوني ومالي لاحقاً:

  • الأهلية عند الحجز وعند الاستقبال: طلب عند حجز الموعد يعطي المريض فرصة أن يحل مشكلة وثيقته قبل أن يأتي، وطلب آخر يوم الزيارة لأن الحالة قد تتغير. واحفظ معرف كل رد، لأن الموافقة والمطالبة سوف تشيران إليه.
  • شاشة واحدة بالرمز وليس بالنص: اعرض على الاستقبال قيمة أهلية الموقع مترجمة إلى إجراء، كما في الجدول أعلاه، ولا تعرض نص disposition وحده، فهو نص حر قد يختلف بين شركة وأخرى.
  • المنافع قبل الموافقة: استخدم المنافع والمستهلك منها في رد الأهلية لتنبيه الطبيب قبل أن يطلب إجراء يتجاوز المتبقي، كما رأينا في الحالة الأولى.
  • الموافقة كسجل له نسخ: كل طلب تعديل نسخة جديدة بكل البنود، وأرقام البنود ثابتة، والمرجع preAuthRef وفترة الصلاحية preAuthPeriod حقلان يراقبهما النظام، فينبه قبل انتهاء الفترة إذا لم تقدم الخدمة.
  • الربط بين أوامر الطبيب والموافقة: الأمر الذي يحتاج موافقة لا ينفذ في النظام حتى يوجد له بند موافق عليه بنفس الرمز والكمية، أو يسجل الطبيب سبباً لتجاوز ذلك كحالة طارئة.
  • الردود المؤجلة: طلب موافقة رجع queued يجب أن يظهر في قائمة متابعة، ومهمة خلفية تسأل المنصة دورياً، كما شرحنا في مقال المهام الخلفية.
  • التحقق اليدوي: عندما تتعطل المنصة يجب أن يكون في الشاشة مكان لتسجيل مرجع التحقق اليدوي وتاريخه، لأنهما يرسلان بالامتدادين الخاصين بهما.
  • إعادة الإرسال: إذا انقطع الاتصال بعد إرسال طلب الموافقة ولم يصل رد، فلا ترسل طلباً جديداً بمعرف جديد، وإنما اسأل عن حالة الطلب الأول أو أعد إرساله بنفس المعرف، وهذه فكرة Idempotency نفسها.
حالات طلب الموافقة في نظام المستشفى: مسودة، ثم أرسل، ثم إما رد فوري complete بموافقة أو رفض أو موافقة جزئية، أو queued ينتظر السحب Polling ثم partial ثم complete، أو خطأ OperationOutcome يعود إلى المسودة للتصحيح، وبعد الموافقة: تعديل بطلب جديد يحمل نفس preAuthRef وكل البنود، أو إلغاء قبل انتهاء preAuthPeriod، أو انتهاء الفترة، أو استخدام في المطالبة
حالات الموافقة المسبقة كما يجب أن يتتبعها نظام المستشفى

أخطاء شائعة

  • الاختبار دون إعلان ملفات التعريف: رأينا صفر أخطاء تتحول إلى 26 بسطر واحد. أعلن meta.profile على كل مورد، واجعل الاختبار يفشل إذا غاب.
  • افتراض معنى الرمز من اختصاره: NA كانت «لا ينطبق» وليس ما افترضناه. اقرأ نظام الرموز في الحزمة، وانتبه لتحذيرات العرض.
  • اتباع نص القاعدة بدل الربط: الشكوى الرئيسية بنظام SNOMED CT في الربط والأمثلة، رغم ذكر ICD في نص قاعدة.
  • رفع أنظمة الرموز بعد أن يسأل عنها المدقق: النتيجة السلبية بقيت في الذاكرة حتى إعادة التشغيل، والنظام بالقيمة fragment لم يستخدم أصلاً.
  • إرسال رموز من بيانات حقيقية إلى خادم مصطلحات عام: مقبول لرموز وهمية في مختبر فقط.
  • نتيجة إجمالية من كل البنود: خدمة لا تحتاج موافقة حولت الرفض إلى موافقة جزئية في منطقنا الأول.
  • تعديل الرد ليمر من قاعدة معطلة: وثق الاستثناء وأبلغ عنه، ولا تغير القرار.
  • إرسال التعديل بالفرق: تعديل الموافقة يحمل كل البنود بأرقامها، وليس البند الجديد وحده.
  • مهلة أقصر من دقيقة: تقطع الاتصال قبل أن ترد المنصة نيابة عن الشركة المتأخرة.

قائمة تحقق Checklist قبل أن تربط نظامك

البندكيف تتحقق منه
إصدار الحزمة مثبت في النظام والاختباراترقم الإصدار وتاريخه في الإعداد، واختبار يفشل إذا تغير دون مراجعة
كل مورد يعلن ملف تعريفهاختبار يفحص meta.profile في كل مدخل
التحقق من كل نوع رسالة بأمثلة صحيحة وخاطئةمثال يجب أن يمر، ومثال يجب أن يفشل بقاعدة تعرف رقمها
أنظمة الرموز المرخصة في سيرفر الاختبارICD-10-AM وSNOMED CT من مصدر مرخص أو جزء للاختبار، والتحقق من رمز معروف بعد كل تشغيل
قائمة القواعد المعروف أنها معطلةملف واحد فيه رقم القاعدة والسبب ورابط البلاغ
حفظ الطلبات والردود كما هيكل رد قابل للاسترجاع بمعرفه بعد سنوات
معرفات الردود تنتقل بين المراحلطلب الموافقة يحمل رد الأهلية، والمطالبة تحمل preAuthRef
التحقق اليدوي له مكانحقلان للمرجع والتاريخ في الشاشة
الردود المؤجلة لها مهمة سحب ومراقبةتنبيه إذا لم تعمل المهمة خلال مدة تحددها
مهلة الطلب أطول من دقيقةإعداد صريح في عميل HTTP

تنظيف المختبر

docker rm -f nphies-lab-payer
docker compose down -v
docker rmi nphies-lab-client

والخيار -v يحذف قاعدة البيانات مع الحزمة المحملة فيها، فإذا كنت سوف تكمل مع مقال المطالبات فاتركه، لأن تحميل الحزمة من جديد يأخذ دقائق.

تدريب عملي

  • أضف إلى شركة التأمين الوهمية الرمز limit-exhausted في رد الأهلية عندما يكون الحد السنوي مستهلكاً بالكامل، ثم تحقق من الرد وانظر أي القاعدتين المعطلتين تظهر.
  • أرسل طلب تعديل للموافقة بنفس preAuthRef يحذف الاستشارة ويبقي الإجراء، واجعل الشركة ترفض أي طلب تعديل لا يحمل كل البنود الموافق عليها سابقاً.
  • غير طلب الأهلية ليكون discovery فقط دون تغطية، وتحقق منه، واقرأ ما يطلبه ملف التعريف عندها.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • الأهلية سؤال فوري عند الحجز والاستقبال، يرجع فيه رمز أهلية الموقع والمنافع والمستهلك منها، والمنصة ترد بنفسها إذا لم تصل إلى الشركة خلال دقيقة.
  • الموافقة المسبقة ملف حي: كل تعديل طلب جديد بنفس المرجع وكل البنود بأرقامها الثابتة، وقد يأتي قرارها مؤجلاً بالسحب.
  • حزمة لا تعلن ملفات التعريف على مواردها مرت بصفر أخطاء، ونفس البيانات مع الإعلان فيها 26 خطأ.
  • ICD-10-AM وSNOMED CT ليسا في الحزمة، والمدقق يرفض الرمز دونهما. في HAPI لم يستخدم النظام بالقيمة fragment، وبقيت النتيجة السلبية في الذاكرة حتى إعادة التشغيل.
  • شركة التأمين الوهمية أعطت موافقة جزئية بالمتبقي من حد العمليات، ورفضت الإجراء لتشخيص لا يبرره، وكشف المخرج خطأ في منطق النتيجة الإجمالية لم يكشفه المدقق.
  • قاعدتان في الحزمة 1.0.0 ترفضان أي رد أهلية بقيمة غير مؤهلة، وأثبتنا ذلك على المثال الرسمي نفسه، والحل توثيق الاستثناء والإبلاغ عنه.
  • القرار يأخذ أجزاء من الألف من الثانية، والتحقق مئات المللي ثانية وأول مرة عشرات الثواني، فصمم النظام بحيث لا ينتظر الاستقبال المدقق المحلي.
دليلالتأمين الصحي من الداخل: الشركة وTPA والوسيط والمستشفىمن يدفع القسط ومن يقرر الموافقة ومن يدير المطالبة في التأمين الصحي السعودي، وكيف يتحرك المال من صاحب العمل إلى المستشفى.دليلالمنصات الصحية في السعودية: نفيس NPHIES وصحتي ووصفتيمن يملك كل منصة صحية وطنية وماذا تفعل، من صحتي ومستشفى صحة الافتراضي إلى نفيس والسجل الموحد، وما يعنيه ذلك لمن يبني نظاماً.دليلخادم FHIR على سيرفرك: تجربة عملية مع HAPI FHIRكيف تشغل سيرفر FHIR يحفظ في PostgreSQL ويتحقق من البيانات بدليل نفيس، مع البحث بالأسماء العربية والنسخ والمعاملات.دليلالمصطلحات الطبية الموحدة: ICD وSNOMED CT وLOINCكيف تفهم الآلة أن الأسماء الطبية المختلفة مفهوم واحد، وكيف تختار نظام الرموز المناسب للتشخيص والتحليل والدواء، برموز حقيقية.دليلالترميز الطبي Clinical Coding: من ملف المريض إلى المطالبةكيف يحول المرمز توثيق الطبيب إلى رموز تشخيص وإجراءات ومجموعات DRG، وما الذي يلزم به مجلس الضمان الصحي في السعودية.دليلربط المطالبات بمنصة نفيس NPHIES: الرسائل والأخطاءنبني مطالبة من كل نوع بدليل نفيس ونتحقق منها، ونشغل محاكياً يرد فورياً ومؤجلاً ويطلب معلومات ويقبل الإلغاء، ثم نجمع الأخطاء الشائعة ومن يصلح كل واحد.دليلتدقيق المطالبات Claims Adjudication: محرك القواعدنبني محرك قواعد صغيراً لتدقيق المطالبات الصحية بمراحل مرتبة، ونشغله على 200 مطالبة وهمية فيها 70 مشكلة مزروعة، ونقيس ما أمسكه وما فاته ولماذا.دليلالمهام الخلفية Background Jobs: لماذا لا ينتظر المستخدم؟كيف تخرج إرسال البريد ومعالجة الملفات من الطلب إلى عامل يعمل في الخلفية، مع تجربة على Celery وRedis تقيس زمن الطلب قبل وبعد وتقتل العامل في منتصف مهمة.

سجل التحديثات

  • 2026-11-18: كتابة المقال، وتنفيذ المختبر على HAPI FHIR 8.12.0 (hapiproject/hapi:v8.12.0-2) بإصدار FHIR R4 4.0.1 مع PostgreSQL 17 ودليل نفيس nphies-fs 1.0.0، وشركة تأمين وهمية بلغة Python 3.14 على alpine 3.24، وDocker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.