> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# تهيئة HIPAA: من BAA إلى الجاهزية للتدقيق

> تسلسل لتحويل مساحة عمل رعاية صحية من توقيع BAA إلى الجاهزية لتدقيق PHI — تفعيل وضع HIPAA، وتقييد الأدوار ونطاقات API، وتكوين الاحتفاظ، وقراءة سجل الوصول إلى PHI، وتصدير ملك الدليل.

# تهيئة HIPAA: من BAA إلى الجاهزية للتدقيق

تشرح مرجعية [ضوابط HIPAA](/compliance/hipaa) ما يفعله كل ضابط. يضع هذا الدليل الضوابط بالترتيب — التسلسل الذي يأخذ مساحة عمل رعاية صحية من "نتعامل مع PHI" إلى "يمكننا إظهار مسار تدقيق" دون التعثر في بوابة الإرسال `422 HIPAA_BAA_REQUIRED` — إحدى [بوابات الإرسال](/compliance/send-gates) التي تتحقق من امتثال المرسل قبل إرسال رسالة أو مكالمة.

الترتيب مهم. لا يمكن تفعيل وضع HIPAA قبل تنفيذ BAA، وتُرفض إرسالات PHI حتى يتم، والاحتفاظ يحمي البيانات فقط عند تكوينه. اتبع الخطوات من الأعلى إلى الأسفل.

تعمل كل خطوة أدناه مقابل `https://api.orbit.devotel.io/api/v1` برأس `X-API-Key` على مفتاح **مالك أو مدير**. صدّره قبل البدء:

```bash theme={null}
export ORBIT_KEY="dv_live_sk_…"   # live — أو dv_test_sk_… على sandbox
```

ينطبقان عرفان على كل استجابة في هذه الصفحة:

* **بادئات المفاتيح.** مفاتيح sandbox هي `dv_test_sk_…`؛ مفاتيح live هي `dv_live_sk_…`. كل استدعاء أدناه يعمل على أي منهما — sandbox يعيد نفس المغلفة دون لمس حالة الامتثال الحيّة.
* **المغلف المشترك.** كل جسم نجاح هو `{ "data": { … }, "meta": { "request_id", "timestamp" } }`. الأخطاء هي `{ "error": { code, message, status }, "meta": … }`.

## 1. تنفيذ BAA

لا شيء آخر يُفتح حتى يتم تنفيذ اتفاقية شريك الأعمال (BAA). بوابتان تقرأان حالة BAA مباشرة:

* **تفعيل وضع HIPAA** يعيد `403 Forbidden` طالما حالة BAA ليست `executed`.
* **أي إرسال PHI** يُرفض مع `422 HIPAA_BAA_REQUIRED`.

نفّذها من خلال قسم **Compliance → BAA** في لوحة التحكم، أو قد نفس الاستدعاءات الثلاثة عبر API. استخدم مفتاح مالك لـ `/execute` (يربط الاتفاقية القانونية)؛ مفتاح مالك-أو-مدير يكفي لـ `/require` و `GET /compliance/baa`.

### 1a. تصحيح أن PHI في النطاق

انقل المؤسسة من `not_required` إلى `pending`، ما يفتح مسار التنفيذ:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orbit.devotel.io/api/v1/compliance/baa/require \
    -H "X-API-Key: $ORBIT_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "reason": "Clinic messaging will carry PHI" }'
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/compliance/baa/require",
    {
      method: "POST",
      headers: {
        "X-API-Key": process.env.ORBIT_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ reason: "Clinic messaging will carry PHI" }),
    },
  );
  console.log((await res.json()).data.baa_status); // "pending"
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "baa_status": "pending",
    "baa_executed_at": null,
    "baa_template_version": null,
    "baa_signer_name": null,
    "baa_signer_email": null,
    "baa_pdf_gcs_url": null,
    "hipaa_required": true,
    "expires_at": null,
    "days_until_expiry": null
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
```

`reason` هو نص حر اختياري يسجّل في صف التدقيق، أبداً في عمود.

### 1b. التنفيذ بتوقيع إلكتروني يكبب-الاسم

سجّل التصحيح. `typed_attestation` يجب أن يطابق `signer_name` بالضبط — هو الدفاع ضد توقيع عارض أو نموذج فارغ:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orbit.devotel.io/api/v1/compliance/baa/execute \
    -H "X-API-Key: $ORBIT_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "signer_name": "Ada Lovelace",
      "signer_email": "ada@clinic.example",
      "typed_attestation": "Ada Lovelace"
    }'
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/compliance/baa/execute",
    {
      method: "POST",
      headers: {
        "X-API-Key": process.env.ORBIT_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        signer_name: "Ada Lovelace",
        signer_email: "ada@clinic.example",
        typed_attestation: "Ada Lovelace",
      }),
    },
  );
  console.log((await res.json()).data.baa_status); // "executed"
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "baa_status": "executed",
    "baa_executed_at": "2026-09-23T14:02:11.482Z",
    "baa_template_version": "v1",
    "baa_signer_name": "Ada Lovelace",
    "baa_signer_email": "ada@clinic.example",
    "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
    "hipaa_required": true,
    "expires_at": "2027-09-23T14:02:11.482Z",
    "days_until_expiry": 365,
    "baa_id": "baa_…"
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
```

### 1c. تأكيد أن BAA منفّذ

أعد قراءة دورة الحياة وسجّل `days_until_expiry` — BAA منفّذ ينتهي بعد مدته السنوية ويجب إعادة تنفيذه:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.orbit.devotel.io/api/v1/compliance/baa \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/compliance/baa",
    { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
  );
  console.log((await res.json()).data.days_until_expiry); // مثلاً 365
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "baa_status": "executed",
    "baa_executed_at": "2026-09-23T14:02:11.482Z",
    "baa_template_version": "v1",
    "baa_signer_name": "Ada Lovelace",
    "baa_signer_email": "ada@clinic.example",
    "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
    "hipaa_required": true,
    "expires_at": "2027-09-23T14:02:11.482Z",
    "days_until_expiry": 365
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
```

دورة حياة BAA، وتحذير المرآة القديمة، وأشكال الطلب الكاملة موثقة تحت [BAA](/compliance/hipaa#5-business-associate-agreement-baa). لدورة تنفيذ الكونسول، وإعادة التنفيذ السنوية، وضوابط الرفض/العودة — بالإضافة إلى كونسولات DPA وموافقة التسجيل الشقيقة — انظر [نفّذ DPA وBAA، ثم أدر موافقة التسجيل لكل مكالمة](/guides/compliance-dpa-baa-recording-consent).

## 2. تفعيل وضع HIPAA

مع BAA منفّذاً، شغّل علم HIPAA لكل مؤسسة. وضع HIPAA هو علم ميزة لكل مؤسسة ينشّط خمسة ضوابط دفعة واحدة — تشفير أثناء التخزين، ضوابط الوصول، تسجيل تدقيق PHI، الاحتفاظ المُفروض، وتتبّع BAA. وهو استدعاء للمالك فقط.

* **لوحة التحكم:** **الإعدادات → الامتثال → تبديل وضع HIPAA**.
* **API:**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.orbit.devotel.io/api/v1/settings/hipaa \
    -H "X-API-Key: $ORBIT_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "enabled": true }'
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/settings/hipaa",
    {
      method: "PUT",
      headers: {
        "X-API-Key": process.env.ORBIT_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ enabled: true }),
    },
  );
  console.log((await res.json()).data.enabled); // true
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-23T14:05:40.118Z",
    "last_enabled_at": "2026-09-23T14:05:40.118Z",
    "disabled_at": null,
    "enable_history": [
      { "enabledAt": "2026-09-23T14:05:40.118Z" }
    ],
    "baa_status": "executed",
    "hipaa_required": true,
    "baa": {
      "signed": true,
      "signedAt": "2026-09-23T14:02:11.482Z",
      "documentPresent": true,
      "history": []
    },
    "data_retention": { "enabled": true, "days": 365 },
    "encryption_algorithm": "AES-256-GCM",
    "phi_access_log_count": 0
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
```

التفعيل استدعاء واحد — يشدد وضع مساحة العمل، لذا لا يلزم تحدي إعادة مصادقة. التعطيل إزالي ويتطلب واحداً؛ ذلك المسار موثّق تحت [تعطيل وضع HIPAA](/compliance/hipaa#6-disabling-hipaa-mode). إذا لم تكن حالة BAA `executed`، يعيد الاستدعاء `403 Forbidden`.

## 3. تقييد الأدوار ونطاقات API إلى الحد الأدنى الضروري

معيار HIPAA *الحد الأدنى الضروري* هو **مسؤوليتك** — يقع على جانب العميل من [جدول المسؤولية المشتركة](/compliance/hipaa#shared-responsibility). ضوابط Orbit اليوم متخشية، لذا جهّز لذلك بصراحة:

* استخدم **دور `billing`** للموظفين الذين يحتاجون فقط السطوح المالية. أعضاء billing محكومٌ بهم على الفاتورة والتسعير والاستخدام — يتلقون `403` على نقاط نهاية محتوى الرسائل.
* أبقِ احتياجات القراءة لكل شخص آخر في الاعتبار: يمكن لـ `owner` و`admin` و`developer` و`viewer` جميعاً قراءة محتوى الرسائل اليوم، وكل قراءة تسقط في سجل الوصول إلى PHI.
* أصدر مفاتيح API بفقط النطاقات التي يحتاجها التكامل، وامنح `messages:read` فقط للخدمات التي تقرأ حقاً محتوى رسائل حاملة PHI.

> **قيود معروفة:** لا يقيد Orbit حاليًا قراءات محتوى الرسائل على مجموعة أدوار أضيق خارج اقتصار billing، ولا تتطلب نقاط نهاية قراءة الرسائل (`GET /messages`، `GET /messages/{id}`) رمز سبب مُرسل من المشغل. حقق معيار الحد الأدنى الضروري بتجهيز عضوية مساحة العمل ونطاقات مفاتيح API بحيث لا يستطيع سوى الموظفين الذين يحتاجون PHI الوصول إلى تلك النقاط. إذا لزم برنامجك تقييد قراءة محتوى الرسائل على دور، فاتصل بـ [compliance@devotel.io](mailto:compliance@devotel.io) قبل الاعتماد عليه.

## 4. تكوين الاحتفاظ بالبيانات

حدد نافذة الاحتفاظ قبل أن يتراكم PHI خلفها. `data_retention_days` يقبل 30–3,650؛ الافتراضي 365.

* **لوحة التحكم:** **الإعدادات → الامتثال → HIPAA → الاحتفاظ بالبيانات**.
* **API** (المالك فقط، نفس نقطة نهاية التبديل):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.orbit.devotel.io/api/v1/settings/hipaa \
    -H "X-API-Key: $ORBIT_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "enabled": true, "data_retention_days": 90 }'
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/settings/hipaa",
    {
      method: "PUT",
      headers: {
        "X-API-Key": process.env.ORBIT_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ enabled: true, data_retention_days: 90 }),
    },
  );
  console.log((await res.json()).data.data_retention.days); // 90
  ```
</CodeGroup>

تكرر الاستجابة كائن الحالة الكامل (نفس شكل استدعاء التفعيل أعلاه)؛ تحقق من `data.data_retention.days`.

تفحص وظيفة خلفية محتوى الرسائل والتسجيلات والمرفقات الوسائط المنتهية وحذفها. سجلات التدقيق وسجلات الوصول إلى PHI تُحفظ بشكل مستقل عن هذه السياسة — ساعة الحذف لا تمحوا مسار الدليل.

إذا كنت تسجّل مكالمات، ثبّت منطقة الصوت لتطابق واجبات إقامتك في نفس الوقت — انظر [إقامة بيانات الصوت والاحتفاظ](/compliance/voice-data-residency) لم手指 الإقامة الذي يحفظ التسجيلات والرسائل الصوتية والوسائط الحية في منطقة واحدة.

## 5. تحقق من التكوين

أكد أن العلم والاحتفاظ سقطا كما أردت (مالك أو مدير):

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.orbit.devotel.io/api/v1/settings/hipaa \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/settings/hipaa",
    { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
  );
  const { data } = await res.json();
  console.log(data.enabled, data.data_retention.days);
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-23T14:05:40.118Z",
    "last_enabled_at": "2026-09-23T14:05:40.118Z",
    "disabled_at": null,
    "enable_history": [ { "enabledAt": "2026-09-23T14:05:40.118Z" } ],
    "baa_status": "executed",
    "hipaa_required": true,
    "baa": { "signed": true, "signedAt": "2026-09-23T14:02:11.482Z", "documentPresent": true, "history": [] },
    "data_retention": { "enabled": true, "days": 90 },
    "encryption_algorithm": "AES-256-GCM",
    "phi_access_log_count": 12
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
```

تحقق من `enabled` و`data_retention.days` في الاستجابة.

> تحمل الاستجابة أيضًا حقل `encryption_algorithm`. وهو **للتقارير فقط**: يعكس معيار تشفير أثناء التخزين للمنصة (AES-256 مُدار من Google على Cloud SQL)، لا مزخّر طبقة تطبيق لكل مؤسسة. لا تجري Devotel حاليًا تشفير طبقة تطبيق لكل مؤسسة على أجساد الرسائل، لذا لا تقتبس هذا الحقل للمدقّق كدليل على أن أجساد الرسائل مشفرة بشكل فردي في طبقة التطبيق.

## 6. قراءة سجل الوصول إلى PHI

بمجرد تشغيل وضع HIPAA، يُكتب كل وصول إلى بيانات تحتوي على PHI في سجل تدقيق append-only. كل مدخل يسجّل المستخدم، والمورد، والسبب (`read` يُسجّل تلقائيًا على قراءات الرسائل)، والطابع الزمني. بلّغ عبر `?limit=` و`?cursor=` — مرّر `id` آخر المدخلات التي رأيتها كـ `cursor` التالي (مالك أو مدير):

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50" \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50",
    { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
  );
  const { data } = await res.json();
  console.log(data.entries[0]?.resource, data.has_more);
  ```
</CodeGroup>

```json theme={null}
{
  "data": {
    "entries": [
      {
        "id": "phi_…",
        "userId": "user_…",
        "resource": "message:msg_…",
        "reason": "read",
        "accessedAt": "2026-09-23T14:12:07.901Z"
      },
      {
        "id": "phi_…",
        "userId": "user_…",
        "resource": "contact:con_…",
        "reason": "treatment",
        "accessedAt": "2026-09-23T13:58:44.210Z"
      }
    ],
    "has_more": true,
    "total": 12
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}
```

يحفظ السجل حتى 10,000 مدخل لكل مؤسسة مع older تُوارى، وهو متاح لأدور `owner` و`admin` عبر لوحة التحكم أو API، ويمكن تصديره للتدقيقات الخارجية. راجعه على جدول مبكر — فهو كيف تظهر أن الوصول يتبع قرارات الدور والنطاق التي اتخذتها في الخطوة 3. عندما يكون `has_more` `true`، أرسل `id` آخر المدخل كـ `?cursor=` للصفحة التالية.

## 7. تصدير ملك الدليل HIPAA

عندما تحتاج لإظهار وضع لمدقّق أو فريق مشتريات مشترٍ، اطرود حزمة HIPAA من [ملك الدليل](/compliance/evidence-binder) من **الإعدادات → الامتثال → Binder**. إطار HIPAA يجمع تسجيل الوصول إلى PHI، ووضع BAA، واحتفاظك المُكوَّن في حزمة موقعة وجاهزة للتنزيل؛ كل إنتاج يسجّل في سجل تدقيقك، وينتهي رابط التنزيل بعد 24 ساعة.

## حزمة تفعيل الرعاية الصحية

يرسل [سوق مكونات الامتثال](/compliance/plugin-marketplace) حزمة تفعيل **HIPAA healthcare** التي توفر نموذج امتثال مسودة، وحملات مسودة، ووكيل AI مضبوط على القطاع، وتهيئة مسار opt-in في استدعاء واحد. إنه إطار بدء، ليس بديلًا عن هذا التسلسل: تفعيل الحزمة لا ينفّذ BAA أبدًا، ولا يفعّل وضع HIPAA أبدًا، ولا يضع إرسالاً أبدًا. شغّل الخطوات 1–6 أعلاه أولاً، ثم فعّل الحزمة واعمل قائمة go-live من مسودة إلى إنتاج.

## قائمة ترتيب العمليات

* [ ] BAA منفّذ و`baa_status` أكدت كـ `executed` — *دور المالك*
* [ ] وضع HIPAA مفعّل عبر التبديل أو `PUT /settings/hipaa` — *دور المالك*
* [ ] العضوية مشذبة إلى الحد الأدنى الضروري؛ `messages:read` متدرجة فقط على المفاتيح التي تحتاجها — *مدير*
* [ ] `data_retention_days` مُحددة على نافذة سياستك — *مدير*
* [ ] منطقة الصوت مثبتة إذا كانت واجبات إقامتك تقيّد مكان تخزين الصوت المسجل — *مدير*
* [ ] `GET /settings/hipaa` مستعبر، مع `encryption_algorithm` معامل كتقارير فقط — *مسؤول الامتثال*
* [ ] سجل الوصول إلى PHI مراجع على جدول — *مسؤول الامتثال*
* [ ] ملك دليل HIPAA مطروء ومسلّم عبر رابط 24-Saat — *مسؤول الامتثال*