المطوّرون
يشارك Casablanca Health Finder بطاقاته مع أنظمة أخرى عبر واجهة برمجة REST وخادم FHIR R4 وسجل للتغييرات. دون بيانات اعتماد ترى ما يراه العموم؛ ويمكن للشركاء الذين لديهم اتفاقية أن يروا أكثر.
واجهة البرمجة REST
ابحث في الخدمات والأماكن والمنظمات والممارسين واقرأها بصيغة JSON. دون بيانات اعتماد يمكنك إرسال 60 طلبًا في الدقيقة و10,000 في اليوم من العنوان نفسه.
https://api.hark.health/v1/d/pilot-casablancaمستند OpenAPI (كل طلب واستجابة) (يُفتح في علامة تبويب جديدة)
خادم FHIR R4
اقرأ وابحث في موارد Organization وLocation وHealthcareService وPractitioner وPractitionerRole وEndpoint بصيغة FHIR 4.0.1، بتنسيق JSON. الخادم للقراءة فقط.
https://api.hark.health/v1/d/pilot-casablanca/fhirCapabilityStatement (ما يدعمه الخادم) (يُفتح في علامة تبويب جديدة)
تصرّح الموارد بهذه الملفات التعريفية ():
سجل التغييرات وخطافات الويب
يحتفظ الشركاء بنسخة محدّثة بتتبّع سجل التغييرات، أو باستقبال التغييرات على نظامهم كخطافات ويب موقّعة. يتطلب الأمران بيانات اعتماد الشريك.
https://api.hark.health/v1/d/pilot-casablanca/changesالحصول على وصول إلى واجهة البرمجة
أنشئ حساب مطوّر لتحصل فورًا على بيانات اعتماد لصندوق الاختبار. ثم اطلب الوصول إلى Casablanca Health Finder من وحدة تحكم المطورين: فريقه يقرر ما يمكن لمنظمتك قراءته.
تعمل بيانات اعتماد صندوق الاختبار فورًا في Highlands Health Finder، مع بياناته التجريبية وحدّ منخفض للطلبات.
التسجيل للوصول إلى واجهة البرمجةفتح وحدة تحكم المطورين
مجموعة واحدة من بيانات الاعتماد تعمل في كل دليل يمنح منظمتك وصولًا. اطلب رمزًا لدليل واحد في كل مرة:
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials -d directory=pilot-casablanca \
https://api.hark.health/oauth/tokenقد يحصر الدليل وصولك في بعض المناطق أو فئات الخدمات أو أنواع السجلات. ما يقع خارج ذلك يجيب كأنه سجل غير موجود في كل مكان: القوائم والبحث وسجل التغييرات وخطافات الويب وFHIR والتصديرات.
ما يمكن السماح لعميل شريك بفعله
- search:read
- Search services and autocomplete
- graph:read
- Read organisations, locations, services, practitioners and roles, including filtered lists
- feed:read
- Read the change feed
- export:run
- Request and download exports
- webhooks:manage
- Register webhook endpoints that receive the change feed (needs feed:read too)
- practitioners:read
- List practitioners and read their profiles, with the privacy rules applied (only what each practitioner shows to the client's tier). Granted only when a directory admin explicitly allows it; never implied by another scope (D-599)
أسئلة عن الوصول؟ لطلب الوصول، تواصل مع Casablanca Health Finder عبر صفحة «عن هذا الدليل».
تغييرات واجهة البرمجة
التغييرات على الطلبات والاستجابات، من الأحدث إلى الأقدم. يذكرها مستند OpenAPI أيضًا.
للفئات وأنواع الخدمات أيقونة: اسم أيقونة من نظام التصميم (مثل stethoscope أو glasses)، تُعرض بجانب الاسم، لا وحدها أبدًا. أضيفت إلى كل فئة في GET /v1/d/{dir}/categories و/categories/{code} (icon)، وإلى كل فئة ونوع محلي ونوع من المنصة في GET /v1/d/{dir}/taxonomy (icon)، وإلى كل بطاقة نتيجة في GET /v1/d/{dir}/search/services، وإلى خدمات المختارات وبطاقات الخدمات (categoryIcon، أيقونة نوع الخدمة، مع categoryCode، فئة نوعها في المنصة، أو null). لكل نوع وفئة أيقونة افتراضية يمكن للمشغلين تغييرها، ويمكن للدليل اختيار أيقونته لأنواعه وفئاته؛ وكل ما عدا ذلك briefcase-medical. إضافة فقط: لم يُغيّر أي حقل ولم يُحذف.
تُكتب التصديرات على أجزاء، فتكتمل حتى التصديرات الكبيرة جدًا؛ لا تتغير سجلاتها ولا ترتيبها. لم يعد ملف تصدير JSON مُزاحًا: سطر واحد من JSON بالمحتوى نفسه. لا تتغير ملفات CSV وFHIR. لعدّادات الفئات وسم تخزين مؤقت خاص بها (cat: متبوعًا باسم الدليل في عنوانه) بدل وسم البحث، يُفرّغ حين تدخل بطاقة أو تخرج أو يتغير نوعها. تستبعد قائمة الخدمات والتصديرات البطاقة المسحوبة فور سحبها.
تُضغط الاستجابات وتحتفظ بها ذاكرات التخزين المؤقت المشتركة مدة أطول؛ لا يتغير محتواها. تصل الاستجابات النصية التي تبلغ 1 كيلوبايت أو أكثر مضغوطة بـ Brotli أو gzip حين يقبل الطلب ذلك (Accept-Encoding، مع Vary: Accept-Encoding). صارت القراءات العامة المجهولة تذكر المدة التي يمكن لذاكرات التخزين المشتركة الاحتفاظ بها، مع وسوم تخزين: الإكمال التلقائي (public, max-age=60, s-maxage=300)، وصفحات الأماكن والمنظمات وقائمة الخدمات دون عميل (s-maxage=60)، وخريطة الموقع (s-maxage=300)؛ وتحصل التصنيفات على وسم تخزين. تضيف الصور المنشورة immutable ووسم ETag (بصمة المحتوى) وتجيب 304 على If-None-Match مطابق. تبقى الاستجابات للمهنيين والشركاء والعملاء المحصورين private, no-store.
تغيير في السلوك: الحصول على الممارسين دفعة واحدة خيار واحد. العميل الشريك الذي لا يملك practitioners:read لم يعد يتلقى أي ممارس في التصديرات أو سجل التغييرات أو خطافات الويب أو _include في FHIR؛ تبقى الأدوار، مع المعرّف العام لممارسها، ولا تتغير قراءة ممارس واحد. دون عميل، يجيب بحث FHIR Practitioner بـ 403 ويغفل السجل الممارسين، ما لم يسمح الدليل للجميع بإدراج الممارسين (إعداد جديد، معطل افتراضيًا)؛ وعندها تعمل قائمة الممارسين أيضًا دون عميل.
نطاق جديد practitioners:read وقائمة جديدة GET /v1/d/{dir}/practitioners: الممارسون الذين لهم دور نشط في خدمة تراها، ولكل منهم ما يُظهره لمستواك فقط، ضمن حدود وصولك. لا يمنحه الدليل إلا باختيار صريح، ولا يملكه صندوق الاختبار. من دونه تجيب القائمة وبحث FHIR Practitioner بالرمز 403 forbidden-scope. تقبل طلبات الوصول الحقل practitionerListReason.
بيانات اعتماد المنظمات الشريكة (client_id hsdp_...) من وحدة تحكم المطورين تعمل في كل دليل منح المنظمة وصولًا: يقبل طلب الرمز directory، وهو المعرّف المختصر للدليل، ويضيف الرد directory وsandbox. العملاء الذين أنشأهم دليل (hsdc_...) يعملون كما كانوا.
يمكن للدليل الآن أن يحصر أي عميل في مناطق أو فئات خدمات أو أنواع سجلات معيّنة (كان ذلك من قبل للأدلة التجميعية فقط). السجلات خارج هذا الحصر تجيب 404 not-found-or-hidden ولا تظهر في القوائم أو البحث أو سجل التغييرات أو خطافات الويب أو FHIR أو التصديرات. يضيف DeveloperInfo الحقل developerPortal.
صار جنس الممارس إحدى القيم woman أو man أو non_binary أو different_term أو prefer_not_to_say (كان نصًا حرًا)، مع حقل اختياري genderOwnTerm، وهو المصطلح الذي يختاره الممارس، مع different_term فقط. لا تتلقى الطلبات العامة prefer_not_to_say أبدًا.