# البدء

> من مفتاح API إلى قراءة وكتابة سجل FHIR R4 لمريض في بيئة الاختبار: المفاتيح، الاستدعاءات الأولى، الكتابات مع المصدر، المستندات، سياق الذكاء الاصطناعي، IPS، الموافقة، خطافات الويب، وتقارير المختبر.

Source: https://developers.anpheros.com/ar/guides/getting-started

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

عنوان URL الأساسي (تتشاركه بيئة الاختبار والإنتاج؛ المفتاح يحدد مستوى البيانات):

```
https://platform.anpheros.com
```

مرجع تفاعلي: `/docs` (OpenAPI) و `/fhir/R4/metadata` (CapabilityStatement).

## 1. الحصول على مفتاح (دقيقة واحدة)

بيئة الاختبار المعزولة (sandbox) ذاتية الخدمة. قم بتسجيل الدخول إلى لوحة التحكم (`https://platform.anpheros.com/dashboard/`)
باستخدام Google واضغط على **الحصول على مفتاح بيئة اختبار معزولة**: ستحصل على مؤسسة، ومشروع بيئة اختبار معزولة مع مرضاه الاصطناعيين الخاصين به، ومفتاح - يظهر مرة واحدة. نفس الشيء عبر واجهة برمجة تطبيقات المسؤول (Admin API)، باستخدام رمز مستخدم Firebase الخاص بك:

```bash
curl -X POST $BASE/admin/sandbox/quickstart -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
# {"organization": {…}, "project": {"id": "proj_…", "environment": "sandbox", …}, "key": {"key": "sk_test_…", …}, "sandbox": {…}}
```

أو خطوة بخطوة:

```bash
# 1. an organization (you become its owner)
curl -X POST $BASE/admin/organizations -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI SRL","kind":"developer","country":"RO"}'
# 2. a sandbox project (it comes with its own synthetic patients)
curl -X POST $BASE/admin/organizations/org_…/projects -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI dev","environment":"sandbox"}'
# 3. a key — the plain key is returned exactly once
curl -X POST $BASE/admin/projects/proj_…/keys -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"local dev","scopes":["read","write"]}'
```

ستحصل على `sk_test_…`. مفاتيح بيئة الاختبار المعزولة ترى دائمًا بيانات بيئة الاختبار المعزولة فقط. مفاتيح الإنتاج (`sk_live_…`)
تُصدر للمؤسسات المعتمدة مع اتفاقية حماية البيانات (DPA) موقعة - راسل platform@anpheros.com. بيئة الاختبار المعزولة مجانية؛
يبدأ الإنتاج بسعر 99 يورو شهريًا والشهر الأول مجاني (انظر [التسعير](https://developers.anpheros.com/ar/guides/pricing)).

## 2. أول استدعاء (دقيقة واحدة)

يحتوي مشروع sandbox الخاص بك بالفعل على نسخته الخاصة من 30 مريضًا اصطناعيًا، مع ستة أشهر من السجل التاريخي
حتى يوم إنشاء المشروع: بالغين وأطفال وكبار السن من جميع أنحاء الاتحاد الأوروبي، مع
حالات (ICD-10) وأدوية (ATC) وحساسيات ونتائج مختبر وعلامات حيوية (LOINC). النسخة
ملكية لمشروعك: قم بتغيير أو حذف أي شيء - لن يراها أي مشروع آخر. **إعادة تعيين المرضى التجريبيين** في لوحة التحكم (أو `POST /admin/projects/{id}/sandbox/reset`) يعيدهم كما كانوا،
بمعرفات جديدة؛ المرضى الذين أنشأتهم بنفسك لا يتأثرون. يحتفظ كل مريض اصطناعي بمعرف ثابت عبر عمليات إعادة التعيين: `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02`
هو دائمًا Elena Ionescu.

```bash
export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"
```

```json
{"data":[{"id":"…","given":"Elena","family":"Ionescu","birth_date":"1985-09-03","gender":"female",…,"fhir":"Patient/…"}, …],"total":30,"next_cursor":null}
```

حدود Sandbox سخية ولكنها محدودة: 10000 عملية كتابة للموارد يوميًا لكل مشروع، 50 مريضًا خاصًا بك بالإضافة إلى المرضى الاصطناعيين، 250 ميجابايت من المستندات (انظر [الحدود](https://developers.anpheros.com/ar/guides/limits)).

## 3. قراءة سجل

```bash
# lab results, newest first
curl "$BASE/v1/patients/$PID/observations?category=laboratory&limit=10" -H "Authorization: Bearer $KEY"
# active medications
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
# everything on one timeline
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
# the same data, strict FHIR
curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date" -H "Authorization: Bearer $KEY"
```

المعرفات متطابقة في `/v1` و `/fhir/R4`؛ كل كائن v1 يحمل مرجع `fhir` الخاص به.
`_summary=count` تُرجع الإجمالي فقط؛ `_elements=code,effectiveDateTime` تُرجع موارد نحيفة مُعلمة بـ `SUBSETTED`.

## 4. الكتابة

اذكر هوية المؤلف. `author_type` هو `patient`، `practitioner`، `device`، `import` أو `ai`؛
إذا حذفته، تسجل المنصة `import`، ولا تسجل `patient` أبدًا بالافتراض.
الكتابات باستخدام `author_type` `ai` تتبع [شفافية الذكاء الاصطناعي لـ HL7 على FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
المورد يحمل التصنيف الأمني `AIAST` (*تم تأكيده بواسطة الذكاء الاصطناعي*) وله سبب المصدر (Provenance)
`AIAST`، ودور الوكيل `Artificial-Intelligence`، وملف التعريف `AI-Provenance`. لتسمية النموذج، قم بتسجيله كـ
`Device` (النوع `Artificial-Intelligence`، الاسم، الإصدار، الشركة المصنعة) وأرسل `X-Anpheros-Author-Ref: Device/<id>`.

```bash
curl -X POST "$BASE/v1/patients/$PID/observations" -H "Authorization: Bearer $KEY" \
     -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "2339-0", "display": "Glucose", "category": "laboratory",
  "value": 112, "unit": "mg/dL", "effective_at": "2026-09-19T08:10:00Z",
  "author_type": "device"
}'
```

الاستجابة هي الملاحظة المخزنة مع `id`، `fhir` و `updated_at`. تكرار نفس الطلب بالضبط
بنفس `Idempotency-Key` يعيد نفس الاستجابة ولا ينشئ شيئًا.

## 5. المستندات

```bash
# 1. create the document → upload target
curl -X POST "$BASE/v1/patients/$PID/documents" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title":"Analize 2026-09-14","kind":"lab_report","content_type":"application/pdf","date":"2026-09-14"}'
# 2. upload the bytes to the returned url (direct to storage, or through the platform)
curl -X PUT "$BASE/v1/documents/$DOC/content" -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @analize.pdf
```

لا يتم تعديل الأصل أبدًا بعد ذلك؛ يتم تسجيل `sha256` و `size`، وتشير أي قيم تستخرجها لاحقًا إلى المستند عبر `derived_from`.

## 6. المصدر (Provenance)

```bash
curl "$BASE/v1/patients/$PID/provenance/Observation/$OBS" -H "Authorization: Bearer $KEY"
```

إدخال واحد لكل إصدار: من (نوع المؤلف والمشروع)، متى، ومن أي نظام مصدر.

## قواعد جديرة بالمعرفة

- **العزل**: يرى المشروع المرضى الذين أنشأهم (بالإضافة إلى مرضى صندوق الرمل المشترك). مريض أي شخص آخر غير موجود بالنسبة لك: `404`، أبداً `403`.
- **معرفات مزدوجة**: معرف المريض الذي تراه هو معرفك. يرى مشروع آخر نفس الشخص بمعرف مختلف. قم بتخزين معرفاتنا بحرية؛ لا تحاول أبداً ربطها.
- **المصدر**: كل عملية كتابة تترك مورد Provenance. لا شيء يُعاد الكتابة بصمت؛ التاريخ متاح على `/fhir/R4/{Type}/{id}/_history`.
- **الأخطاء**: نقاط نهاية FHIR تُرجع `OperationOutcome`؛ `/v1` و `/admin` تُرجع
  `{"error": {"type", "message", "field"}}`. كل استجابة تحمل `Anpheros-Request-Id`؛ اقتبسها
  عند مراسلتنا.
- **الحدود**: 600 طلب/دقيقة لكل مفتاح افتراضياً، 200 عنصر لكل صفحة، 25 ميجابايت لكل مستند.

## 7. السياق لنموذج الذكاء الاصطناعي

بدلاً من سحب السجلات الأولية وتحديد ما يناسب استعلامًا، اطلب من المنصة توفير سياق:

```bash
curl -X POST "$BASE/v1/context" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -d '{
  "patient": "'$PID'",
  "task": "medication review before a cardiology visit",
  "question": "How did blood pressure evolve over the last 3 months?",
  "budget_tokens": 1500,
  "format": "text"
}'
```

ستحصل على أقسام (بطاقة الملخص، الحالات، الأدوية، الحساسيات، المختبرات، العلامات الحيوية مع اتجاهات أسبوعية وعلامات قبل/بعد العلاج، الأعراض، الجدول الزمني، المستندات)، كل عنصر مُصنّف بـ `author_type` و `source`، وقائمة بما تم حذفه لتناسب الميزانية، وتحذيرات، و `manifest_id` يربط الاستدعاء بسجل التدقيق. القيم التي ينتجها الذكاء الاصطناعي لا تُخلط أبدًا بالحقائق: فهي تظهر فقط تحت `ai_notes`. يتم أيضًا قبول الاحتياجات الصريحة: `"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. المعايير

- `GET /fhir/R4/Patient/{id}/$summary` يُرجع مستند ملخص المريض الدولي (International Patient Summary) من نوع Bundle.
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` يُبلغ عن كيفية قياس نتيجة معملية مقارنةً بملف تعريف نتيجة تقرير المختبر 2.1.0 من HL7 Europe (الأخطاء، التحذيرات، المعلومات): الفئة، الرمز (يفضل LOINC)، الموضوع، وقت السريان، المؤدي، والقيمة ما لم تكن النتيجة مسجلة فقط أو ملغاة.
- `GET /v1/terminology/loinc?q=hba1c` يبحث في مجموعة LOINC المجمعة و `GET /v1/search?q=metformin` في فهرس الأعراض والحالات والأدوية؛ تحصل الملاحظات التي تم إنشاؤها بدون اسم عرض تلقائيًا على اسم LOINC.

## 9. موافقة المريض (OAuth 2.1 + SMART on FHIR)

مفاتيح واجهة برمجة التطبيقات (API) ترى المرضى الذين أنشأهم مشروعك. للوصول إلى سجل شخص موجود، اطلب منهم:

1. تسجيل تطبيق: `POST /admin/projects/{id}/applications` مع عنوان URI لإعادة التوجيه الخاص بك
   (`public` للتطبيقات المتنقلة/الويب مع PKCE، `confidential` للخوادم؛ يتم عرض السر مرة واحدة).
2. إرسال الشخص إلى صفحة الموافقة:
   `GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256&scope=patient/Observation.rs?category=laboratory patient/MedicationStatement.r offline_access&purpose=treatment&lang=ro`
   يسجلون الدخول إلى Anpheros، ويرون ما تطلبه بلغة واضحة، ويختارون السجل (سجلهم الخاص،
   سجل تابع، أو السجل الذي أنشأه تطبيقك لهم) ومدة استمرار الوصول.
3. تبادل الرمز: `POST /oauth/token` (`authorization_code` + `code_verifier`). تتلقى
   رمز وصول (30 دقيقة)، ورمز تحديث (30 يومًا، يتم تدويره عند الاستخدام) ومعرف المريض.
4. استدعاء واجهة برمجة التطبيقات (API) باستخدام `Authorization: Bearer at_…`. ترى فقط هذا المريض، فقط أنواع الموارد
   والإجراءات في النطاقات (scopes)؛ القراءات خارج النطاق تجيب بـ `403`، ويتم تصفية عمليات البحث.

يمكن للشخص الإلغاء في أي وقت من Anpheros؛ الاستدعاء التالي يجيب بـ `401`. كل منحة
تنعكس كمورد FHIR `Consent`، ويتم تسجيل كل وصول تحتها ويكون مرئيًا للشخص. الاكتشاف: `/.well-known/smart-configuration`.

## 10. خطافات الويب (Webhooks)

دع المنصة تتصل بك بدلاً من الاستقصاء:

```bash
curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/anpheros/hook", "events": ["*"]}'
```

احتفظ بـ `secret` من الاستجابة وتحقق من `Anpheros-Signature` عند كل تسليم
(`verifyWebhookSignature` في كلا الـ SDKs). تحمل الأحداث معرفات وإصدارات، وليس بيانات سريرية.
التفاصيل، وإعادة المحاولة، والأمثلة: [webhooks.md](https://developers.anpheros.com/ar/guides/webhooks).

## 11. المنظمات والممارسون

العيادات والمختبرات والأشخاص الذين يعملون فيها هي موارد من الدرجة الأولى: `Organization`،
`Practitioner`، `PractitionerRole`. إنها موارد **دليل**: لا يوجد مريض، يمكن قراءتها بواسطة
كل مشروع في نفس البيئة، ولا يمكن تغييرها إلا بواسطة المشروع الذي أنشأها.

```bash
curl -X POST $BASE/fhir/R4/Practitioner -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Practitioner","active":true,"name":[{"family":"Popescu","given":["Ana"],"prefix":["Dr."]}]}'
```

قم بتسمية الممارس وراء عملية كتابة باستخدام `X-Anpheros-Author-Ref: Practitioner/<id>` (أو
`PractitionerRole`، `Organization`، `Device`): سيحمل سجل الإثبات (Provenance) الذي تم إنشاؤه بواسطة الخادم بعد ذلك
`agent.who.reference`، و `GET /fhir/R4/Provenance?agent=Practitioner/<id>` يسرد كل شيء
قام هذا الشخص بتسجيله. البحث: `Organization?name=`، `?identifier=`، `?type=`، `Practitioner?name=`،
`?family=`، `?given=`، `PractitionerRole?practitioner=`، `?organization=`، `?role=`، `?specialty=`، `?active=`.

من يعمل وراء تطبيقك؟ أرسل `X-Anpheros-Acting-As: PractitionerRole/<id>` (أو
`Practitioner/<id>`) على أي طلب `/v1` أو `/fhir/R4` تم إجراؤه باستخدام مفتاح مشروع. يجب أن
يكون الشخص موجودًا في الدليل ونشطًا. يتم كتابة المرجع إلى سجل الوصول، ويصبح
المؤلف لعمليات الكتابة الخاصة بهذا الطلب (ما لم تقم بتعيين `X-Anpheros-Author-Ref`) ويتم عرضه
للمريض بالاسم في اتصالاته ("د. آنا بوبيسكو · عيادة دينتي قرأت نتائج مختبرك").

## 12. تقارير المختبر في استدعاء واحد

أرسل تقرير مختبر كامل (CSV، HL7 v2 ORU^R01 أو JSON) واحصل على ملاحظات المختبر مع LOINC ونطاقات مرجعية؛ إعادة الإرسال آمنة. التفاصيل: [lab-connector.md](https://developers.anpheros.com/guides/lab-connector).

```bash
curl -X POST "$BASE/v1/patients/$PATIENT/labs/import" -H "Authorization: Bearer $KEY" -H "Content-Type: text/csv" --data-binary @report.csv
```

## ملاحظات المطابقة على عمليات الكتابة

يتم التحقق من كل `POST`/`PUT` لمورد سريري مقابل ملف تعريف IPS الخاص بقسمه، وبالنسبة لملاحظات المختبر، قواعد تقرير المختبر الخاصة بـ HL7 Europe. لا يتم رفض عملية الكتابة أبدًا لأسباب تتعلق بالملف الشخصي (لا تزال أخطاء FHIR الهيكلية تُرفض)؛ عندما يكون هناك شيء مفقود، يحمل الرد

```
Anpheros-Conformance: warnings=2; IPS Condition: Condition without code | ...
```

قم بإصلاح ما يسميه وسيتم تضمين المورد في `$summary` للمريض. أنواع الموارد المضافة في 22 سبتمبر 2026: `Immunization`، `MedicationAdministration` (بحث `statement=MedicationStatement/{id}`)، `RelatedPerson`، `QuestionnaireResponse`، `Basic`. عمليات الكتابة التي تجريها مشاريع أخرى في سجل يمكنك رؤيتها تصل كأحداث webhook مع `data.external = true` — انظر [`docs/webhooks.md`](https://developers.anpheros.com/ar/guides/webhooks).