> ## 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.

# مسار اتفاقية شراكة الأعمال (BAA)

> نفّذ اتفاقية شراكة الأعمال (BAA) الخاصة بـ HIPAA مع Devotel: أقِرّ بنطاق PHI، وعاين القالب، ووقّع بتوقيع إلكتروني بكتابة الاسم، ونزّل النسخة المنفَّذة.

# اتفاقية شراكة الأعمال (BAA)

تحتاج المنظمات التي ترسل أو تخزّن أو تعالج معلومات صحية محمية (PHI) عبر Devotel Orbit إلى اتفاقية شراكة أعمال (BAA) موثَّقة في الملف. تفرض المنصّة وجود مسار BAA قبل أن يمكن تفعيل وضع HIPAA: حين تدخل PHI في النطاق، تحجب بوّابة وقت الإرسال الحركة بـ`HIPAA_BAA_REQUIRED` حتى يُسجَّل BAA منفَّذ.

تغطّي هذه الإرشادات دورة الحياة الكاملة: حالات `baa_status` القانونية، وكيفية تآلف نقاط النهاية الستّ `/api/v1/compliance/baa`، وأيّ دور يمكنه نداء أيّ نقطة، وما يتغيّر بعد تنفيذ BAA، وكيفية إرجاع اتفاقية منفَّذة إلى الافتراضي المنصّي.

> هذا **ضابط HIPAA مملوك للمستأجر**: تقرّر أنت ما إذا كانت PHI في النطاق، وتنفّذ الاتفاقية عن قصد، وتعيد تنفيذها قبل انقضاء الأجل السنوي. يوفّر Devotel مسار التوقيع الإلكتروني — إخراج القالب، والتقاط التوقيع المكتوب، والإرساء التدقيقي غير القابل للتغيير، وملف PDF المنفَّذ المخزَّن — غير أن القرار القانوني بأن PHI في النطاق قرارك أنت.

***

## حالات `baa_status`

تكون منظّمتك دائمًا في إحدى أربع حالات، تبلغ عنها `GET /api/v1/compliance/baa`:

| الحالة         | المعنى                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `not_required` | أقرّت المنظمة (أو افتراضيًا) بعدم وجود PHI في النطاق. هذا هو الافتراضي لكل منظمة جديدة.                                   |
| `pending`      | PHI في النطاق (`hipaa_required = true`) والـ BAA ينتظر التنفيذ. نموذج التنفيذ متاح من هذه الحالة.                         |
| `executed`     | وُقِّع BAA وهو ضمن أجله السنوي الواحد. هذه هي الحالة الوحيدة التي تُرضي بوّابتي تفعيل HIPAA وإرسال PHI.                   |
| `expired`      | انقضى أجل BAA منفَّذ سنوي. تُحظَر إرسالات PHI مجددًا حتى تعيد التنفيذ. تصبح إعادة التنفيذ متاحة قبل 60 يومًا من الانقضاء. |

يحمل الرد أيضًا تفاصيل الموقّع والعدّ التنازلي للانقضاء:

```json theme={null}
{
  "baa_status": "executed",
  "baa_executed_at": "2026-08-10T14:22:31.410Z",
  "baa_template_version": "v1",
  "baa_signer_name": "Jane Roe",
  "baa_signer_email": "jane@example.com",
  "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
  "hipaa_required": true,
  "expires_at": "2027-08-10T14:22:31.410Z",
  "days_until_expiry": 342
}
```

حين تنقلب `hipaa_required` إلى مفعَّلة بينما الحالة لا تزال `not_required`، تنقل نقطة القراءة المنظمة إلى `pending` تلقائيًا، فتُفتَح خطوة التنفيذ دون نداء منفصل.

***

## لماذا يبدأ المسار بإقرار

يوجد مسار BAA لأن HIPAA ينطبق على *الاستخدام* لا على الحسابات. لا تفترض المنصّة أن كل مساحة عمل تعالج PHI — تُقِرّ المنظمة أولًا بأن PHI في النطاق، ما يرفع راية `hipaa_required` وينقل الحالة إلى `pending`. ذلك الإقرار هو ما يفتح خطوة التنفيذ؛ ثم يُتمّ التنفيذ الاتفاقية. يغلق هذا الترتيب تبعية دائرية: لا يمكن تفعيل وضع HIPAA دون BAA منفَّذ، لكن لوحة التحكم احتاجت أيضًا طريقة *لبدء* الـ BAA قبل وجود وضع HIPAA.

كلّ من `require` (PHI في النطاق) و`decline` (لا PHI في النطاق) يكتب صفًّا في سلسلة التدقيق `compliance.baa.*` يسمّي الفاعل، فيكون الإقرار نفسه حدثًا قانونيًّا مسجَّلًا — لا مجرّد تبديل إعداد عابر.

***

## مسار نقاط النهاية

تقيم كل المسارات تحت `/api/v1/compliance/baa` وتشترط جلسة موثَّقة. العمليات الستّ أدناه هي دورة الحياة الكاملة؛ وتقود صفحة **Settings → Compliance → BAA** في لوحة التحكم هذه النقاط بالضبط.

### 1. اقرأ الحالة الحالية

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa" \
  -H "Authorization: Bearer sk_live_..."
```

يمكن لأي `owner` أو `admin` القراءة. استخدم هذا أولًا — يخبرك ما إذا كانت المنظمة تحتاج إلى الإقرار أو التنفيذ أو إعادة التنفيذ أو التنزيل.

### 2. عاين القالب

قبل التوقيع، راجع نص الاتفاقية النهائي. تُعيد `GET /api/v1/compliance/baa/template` القالب مُخرَجًا واسم منظّمتك القانوني معبَّأ مسبقًا. تظهر حقول وقت التنفيذ (الطوابع الزمنية، مرجع الوثيقة) كعلامات مقروءة بدل مواضع خام، وحقول الموقّع فراغات تعبّئها لوحة التحكم حيًّا بينما تكتب.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa/template?version=v1" \
  -H "Authorization: Bearer sk_live_..."
```

الرد:

```json theme={null}
{
  "version": "v1",
  "covered_entity_name": "Acme Health Ltd",
  "format": "markdown",
  "body": "# Business Associate Agreement\n\nThis Business Associate Agreement..."
}
```

### 3. أقِرّ بأن PHI في النطاق

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/require" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "We began sending patient appointment reminders that contain PHI." }'
```

يقلب هذا `hipaa_required = true` وينقل منظمة `not_required` إلى `pending`. يفتح مسار التنفيذ — و**لا** يفعّل وضع HIPAA. يُسجَّل `reason` الاختياري (حتى 500 حرف) في صفّ التدقيق.

### 4. نفّذ بتوقيع إلكتروني بكتابة الاسم

التنفيذ **للمالك حصرًا** — توقيع click-wrap يُلزم المنظمة، فليس إجراءً من مرتبة المطوّر. يعيد الموقّع كتابة اسمه القانوني في `typed_attestation`، ويشترط الخادم تطابقه مع `signer_name` تمامًا؛ يُرفض الخلاف بـ`400`، ما يحجب أيضًا إرسالات النموذج الفارغة التلقائية.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/execute" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Jane Roe",
    "signer_email": "jane@example.com",
    "typed_attestation": "Jane Roe"
  }'
```

| الحقل               | القاعدة                                                   |
| ------------------- | --------------------------------------------------------- |
| `signer_name`       | اسم الموقّع القانوني (2–200 حرف).                         |
| `signer_email`      | بريد إلكتروني صالح.                                       |
| `typed_attestation` | يجب أن **يطابق** `signer_name` تمامًا. يعيد الخلاف `400`. |
| `template_version`  | اختياري. يفترض النسخة القانونية الحالية.                  |

عند النجاح، الخادم:

1. يُخرج القالب مع تفاصيل الموقّع وطوابع التنفيذ الزمنية ومرجع وثيقة مولَّد
2. يخزّن الوثيقة المُخرَجة كالـ PDF المنفَّذ القانوني
3. يختم المنظمة `executed` مع الموقّع ونسخة القالب وطابع التنفيذ، ويسجّل الانقضاء (التنفيذ مضافًا إليه الأجل القياسي السنوي)
4. يكتب قيد `compliance.baa.executed` في سجل التدقيق مع أسلوب التوقيع (`type_the_name`) — القيد التدقيقي هو الدليل القانوني للإقرار، والـ PDF المخزَّن هو الوثيقة القانونية

يعيد الرد الحالة الجديدة مضافًا إليها مرجع الوثيقة:

```json theme={null}
{
  "baa_status": "executed",
  "baa_executed_at": "2026-08-24T09:41:12.008Z",
  "baa_template_version": "v1",
  "baa_signer_name": "Jane Roe",
  "baa_signer_email": "jane@example.com",
  "baa_id": "baa_9f2k…",
  "expires_at": "2027-08-24T09:41:12.008Z",
  "days_until_expiry": 365,
  "hipaa_required": true
}
```

يُحدَّ التنفيذ بمعدّل حفنة من الطلبات في الدقيقة؛ فهو فعل قانوني متعمَّد، لا حلقة مؤتمتة. (للأساس القانوني لـ click-wrap، راجع [التوقيعات الصوتية](/compliance/voice-signatures).)

### 5. نزّل النسخة المنفَّذة

حين يكون BAA في الملف، يمكن لأي `owner` أو `admin` جلبه لسجلاتك أو لتدقيق عميل أو لمنظّم:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa/download" \
  -H "Authorization: Bearer sk_live_..."
```

يحمل الرد عنوان تنزيل صالحًا **لـ 24 ساعة**:

```json theme={null}
{
  "url": "https://storage.googleapis.com/…/baa/org_…/baa_….pdf?X-Goog-Signature=…",
  "expires_in_seconds": 86400
}
```

شارك العنوان داخل تلك النافذة أو نزّل الملف بنفسك وأرشفه. إن لم يُنفَّذ أي BAA بعد، تعيد النقطة `404`.

### 6. ارجع إلى الافتراضي المنصّي

الرجوع يزيل الاتفاقية الموثَّقة في الملف ويعيد المنظمة إلى `not_required`. وهو **للمالك حصرًا** ولا يُنادى إلا على BAA منفَّذ أو منتهٍ — وبعد تعطيل وضع HIPAA فحسب، حتى لا تستطيع مساحة عمل HIPAA نشطة أن تفكّ دليلها الخاص صامتةً.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/revert" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Organization no longer processes PHI; returning to default posture." }'
```

سوابق التدقيق للـ BAA المنفَّذ والـ PDF المخزَّن **محفوظان** — الرجوع يزيل الحالة النشطة ولا يمحو الدليل. استخدمه حين تخرج PHI حقًّا من النطاق، أو لإعادة مساحة عمل إلى أساس نظيف؛ واستخدم [decline](#decline-no-phi-in-scope) بدلًا منه حين يتغيّر إقرار «لا PHI».

### Decline: الإقرار بعدم وجود PHI في النطاق

`POST /api/v1/compliance/baa/decline` (مالك أو إداري، مع `reason` اختياري) يسجّل أن PHI ليست في النطاق ويرفع بوّابة وقت الإرسال بعد أن كانت المنظمة مشتركة. يمتنع عن لمس BAA موثَّق في الملف — لا تستطيع decline تفكيك اتفاقية منفَّذة؛ فذلك دور revert. ولأن `require` و`decline` تبديلان إقراريّان متماثلان، يستطيع الإداري الذي يخفض استعادة المطلب لاحقًا إن عادت PHI إلى النطاق.

***

## الأدوار وسلسلة التدقيق

تقبل نقاط القراءة والمعاينة والتنزيل والإقرار `owner` أو `admin`. أما الفعلان اللذان يُلزمان أو يفكّان اتفاقية قانونية — `execute` و`revert` — فهما `owner` حصرًا.

| الإجراء                                                      | `owner` | `admin` | `developer` / `viewer` / `billing` |
| ------------------------------------------------------------ | :-----: | :-----: | :--------------------------------: |
| قراءة حالة BAA                                               |   نعم   |   نعم   |                 لا                 |
| معاينة القالب                                                |   نعم   |   نعم   |                 لا                 |
| تنزيل النسخة المنفَّذة                                       |   نعم   |   نعم   |                 لا                 |
| إقرار PHI في النطاق (`require`) / ليست في النطاق (`decline`) |   نعم   |   نعم   |                 لا                 |
| تنفيذ الـ BAA                                                |   نعم   |    لا   |                 لا                 |
| الرجوع إلى الافتراضي                                         |   نعم   |    لا   |                 لا                 |

كل كتابة تُلحِق قيد `compliance.baa.*` بسجل تدقيق المنظمة — `compliance.baa.hipaa_required` للـ require، و`compliance.baa.declined` للـ decline، و`compliance.baa.executed` للتنفيذ، و`compliance.baa.reverted` للرجوع — حاملًا الفاعل والسبب و(عند التنفيذ) نسخة القالب وأسلوب التوقيع. تلك السلسلة الملحَقة فحسب، لا حقل الحالة الحالي، هي الدليل القانوني للإقرار. ويمكنك تفقّدها من لوحة التحكم ضمن [Settings → Audit log](/guides/audit-log).

***

## ما يتغيّر بعد تنفيذ BAA

تنفيذ الـ BAA يفعل أمرين:

1. **يرفع بوّابة إرسال PHI.** بينما `hipaa_required` صحيح ولا BAA ضمن الأجل في الملف، تُرفض الإرسالات الصادرة التي تمسّ PHI بـ`422 HIPAA_BAA_REQUIRED`. يزيل BAA منفَّذ ذلك الرفض. (نتيجة البوّابة وسلوك fail-closed موثَّقان ضمن [Send gates](/compliance/send-gates#baa-the-hipaa-send-gate).)
2. **يفتح قفل وضع HIPAA.** تفعيل وضع HIPAA يشترط `baa_status = "executed"`؛ تُعيد المحاولة قبل التنفيذ `403`. وحين يكون وضع HIPAA مفعّلًا، تنطبق الضوابط الموصوفة في [ضوابط امتثال HIPAA](/compliance/hipaa) — تسجيل وصول PHI، واستبقاء البيانات، وبقيّتها — على مساحة العمل.

ما **لا** يغيّره: تنفيذ BAA لا يفعّل وضع HIPAA بذاته، ولا يحدّد مشروعية معالجتك، ولا يغني عن برنامج HIPAA الخاص بك. تسجّل الاتفاقية التزامات المنصّة إليك كشريك أعمال؛ وتبقى قرارات أن PHI في النطاق وتعيين جمهورات ملاصقة لـ PHI وتهيئة الاستبقاء مملوكة للمستأجر. لكيفية تآلف القطع، راجع [تهيئة HIPAA](/guides/hipaa-onboarding) و[ضوابط امتثال HIPAA](/compliance/hipaa).

***

## مسار لوحة التحكم

دورة الحياة نفسها متاحة دون لمس الواجهة البرمجية عند **Settings → Compliance → BAA**:

1. **بطاقة الحالة** — تعرض `baa_status` الحالي وتاريخ التنفيذ والموقّع وشعار إعادة تنفيذ حين يكون الأجل ضمن 60 يومًا من الانقضاء
2. **معاينة القالب** — الاتفاقية المُخرَجة واسم منظّمتك معبَّأ
3. **نموذج الإقرار** — اسم الموقّع وبريده مضافًا إلى حقل توقيع كتابة الاسم، معروضًا للمالكين حين تكون الحالة `pending`
4. **تنزيل** — رابط إلى النسخة المنفَّذة بعد التنفيذ، بعنوان جديد لـ 24 ساعة عند كل طلب

إن لم تُقِرّ PHI بعد، تعرض الصفحة دعوة «Start handling PHI» تُقدِّم إقرار `require` وتفتح جزء التنفيذ فورًا — محاكيةً مسار الواجهة البرمجية أعلاه.

***

## أسئلة شائعة

**كم يدوم BAA منفَّذ؟**
سنة من التنفيذ. يحمل رد الحالة `expires_at` و`days_until_expiry`؛ وضمن 60 يومًا من الانقضاء تعرض لوحة التحكم شعار إعادة التنفيذ. بعد الانقضاء تقرأ الحالة `expired` وتُغلَق بوّابة إرسال PHI مجددًا حتى تعيد التنفيذ بالمسار نفسه.

**هل يستطيع إداري تنفيذ الـ BAA لفتح الإرسالات؟**
لا — التنفيذ (والرجوع) للمالك حصرًا لأنه يُلزم المنظمة. يستطيع الإداري *أن* يوسم PHI كمطلوبة أو مخفَضة، وقراءة الحالة، ومعاينة القالب، وتنزيل النسخة المنفَّذة.

**ما الفرق بين `decline` و`revert`؟**
تسجّل `decline` أن لا PHI في النطاق وترفع بوّابة الإرسال؛ وتمتنع عن لمس BAA منفَّذ. أما `revert` فيزيل اتفاقية منفَّذة أو منتهية كليًّا، معيدًا المنظمة إلى `not_required` مع حفظ سوابق تدقيقها والـ PDF المخزَّن. وكلاهما يترك قيدًا في سلسلة التدقيق.

**هل تقبل نقاط النهاية مرآة JSONB قديمة للحالة؟**
مسار `/api/v1/compliance/baa` هو المسار القانوني. المرآة الأقدم `PUT /api/v1/settings/hipaa/baa` (الموثَّقة ضمن [ضوابط امتثال HIPAA](/compliance/hipaa)) هي احتياط للمستأجرين قبل الترحيل فحسب؛ وحين تمتلك المنظمة قيمة `baa_status`، تقرأ البوّابات العمود القانوني وتتجاهل المرآة.

***

*آخر تحديث: سبتمبر 2026*
*لأسئلة حول الـ BAA، راسل: [compliance@devotel.io](mailto:compliance@devotel.io)*