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

تشرح مرجعية ضوابط HIPAA ما يفعله كل ضابط. هذا الدليل هو العرض الرسمي الشامل الذي يرتبها — التسلسل الذي ينقل مساحة عمل الرعاية الصحية من “نتعامل مع PHI” إلى “يمكننا إظهار أثر تدقيق” دون التعثر في بوابة الإرسال 422 HIPAA_BAA_REQUIRED. دليل التفعيل الأول هو الرفيق القائم على قائمة التحقق فقط، الذي يسلم التسلسل نفسه للعمليات دون تكرار العينات هنا. الترتيب مهم. لا يمكن تفعيل وضع HIPAA قبل تنفيذ BAA، وتُرفض إرسالات PHI حتى يتم ذلك، ولا يحمي الاستبقاء البيانات إلا بعد ضبطه. اتبع الخطوات من الأعلى إلى الأسفل. يُنفَّذ كل خطوة أدناه ضد https://api.orbit.devotel.io/api/v1 بترويسة X-API-Key على مفتاح owner أو admin. صدّره قبل أن تبدأ:

export ORBIT_KEY="dv_live_sk_…"   # live — or dv_test_sk_… against the sandbox

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

بادئات المفاتيح. مفاتيح sandbox هي dv_test_sk_…؛ والمفاتيح الحية هي 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. استخدم مفتاح owner لـ /execute (فهو يبرم الاتفاقية القانونية)؛ ويكفي مفتاح owner أو admin لـ /require وGET /compliance/baa.

1أ. أشهد بأن PHI ضمن النطاق

انقل المنظمة من not_required إلى pending، وهو ما يفتح تدفق التنفيذ:

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" }'

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"

{
  "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 نص حر اختياري يُسجَّل في صف التدقيق، ولا يُسجَّل أبدًا على عمود.

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

سجّل الإشهاد. يجب أن يطابق typed_attestation قيمة signer_name تمامًا — إنه الدفاع ضد توقيع عرضي أو بنموذج فارغ:

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"
  }'

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"

{
  "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": "…" }
}

1ج. تأكد من تنفيذ BAA

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

curl https://api.orbit.devotel.io/api/v1/compliance/baa \
  -H "X-API-Key: $ORBIT_KEY"

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); // e.g. 365

{
  "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. ولعرض الكونسول للتنفيذ وإعادة التنفيذ السنوية وضوابط الرفض/التراجع — إضافة إلى كونسولي DPA وموافقة التسجيل الشقيقين — انظر Execute the DPA and BAA, then manage per-call recording consent.

2. فعّل وضع HIPAA

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

لوحة التحكم: Settings → Compliance → HIPAA Mode Toggle.
API:

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 }'

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

{
  "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": "…" }
}

التفعيل استدعاء واحد — فهو يشدّد وضعية مساحة العمل، لذا لا يلزم تحدّي إعادة استوثاق. التعطيل مدمِّر ويتطلب واحدًا؛ ذلك التدفق موثق تحت Disabling HIPAA Mode. إذا لم تكن حالة BAA executed، يعيد الاستدعاء 403 Forbidden.

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

معيار الحد الأدنى الضروري في HIPAA مسؤوليتك أنت — يقع في جانب العميل من جدول المسؤولية المشتركة. ضوابط Orbit اليوم إجمالية، لذا وفّر له بصدق:

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

قيد معروف: لا يقيّد Orbit حاليًا قراءات محتوى الرسائل إلى مجموعة أدوار أضيق تتجاوز حصر الفوترة، ولا تتطلب نقاط نهاية قراءة الرسائل (GET /messages، GET /messages/{id}) رمز سبب يقدمه المشغل. لبِّ معيار الحد الأدنى الضروري بتوفير عضوية مساحة العمل ونطاقات مفاتيح API بحيث لا يصل إلى تلك النقاط إلا الموظفون الذين يحتاجون PHI. إذا كان برنامجك يتطلب تقييد قراءة لكل دور على محتوى الرسائل، فتواصل مع support@orbit.devotel.io قبل الاعتماد عليه.

4. اضبط استبقاء البيانات

اضبط نافذة الاستبقاء قبل أن يتراكم PHI بما يتجاوزها. يقبل data_retention_days قيم 30–3,650؛ والافتراضي 365.

لوحة التحكم: Settings → Compliance → HIPAA → Data Retention.
API (للمالك فقط، نقطة النهاية نفسها كمفتاح التبديل):

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 }'

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

تردد الاستجابة كائن الحالة الكامل (الشكل نفسه لاستدعاء التفعيل أعلاه)؛ تحقق من data.data_retention.days. تفحص مهمة خلفية محتوى الرسائل المنتهي الصلاحية وتسجيلات المكالمات ومرفقات الوسائط وتحذفها. يحتفظ بسجلات التدقيق وسجلات وصول PHI بشكل مستقل عن هذه السياسة — ساعة الحذف لا تمحو أثر أدلتك. إذا كنت تسجل المكالمات، ثبّت منطقة الصوت لتطابق التزامات الإقامة لديك في الوقت نفسه — انظر Voice Data Residency & Retention لضبط الإقامة الذي يبقي التسجيلات والبريد الصوتي والوسائط الحية في منطقة واحدة.

5. تحقق من الإعدادات

تأكد من أن العلم والاستبقاء هبطا كما قصدت (owner أو admin):

curl https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY"

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);

{
  "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 في سجل تدقيق إلحاقي فقط. يسجل كل مدخل المستخدم والمورد والسبب (read يُسجل تلقائيًا عند قراءات الرسائل) والطابع الزمني. تصفح فيه بـ ?limit= و?cursor= — مرّر id آخر مدخل رأيته كـ cursor تالٍ (owner أو admin):

curl "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50" \
  -H "X-API-Key: $ORBIT_KEY"

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);

{
  "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 مدخل لكل منظمة مع تدوير الأقدم خارجًا، ويمكن الوصول إليه لدورَي owner وadmin عبر لوحة التحكم أو الـ API، ويمكن تصديره للتدقيقات الخارجية. راجعه وفق جدول مبكرًا — بهذه الطريقة تثبت أن الوصول يتبع قرارات الدور والنطاق التي اتخذتها في الخطوة 3. حين يكون has_more بقيمة true، أرسل id آخر مدخل كـ ?cursor= لجلب الصفحة التالية.

7. صدّر ملف أدلة HIPAA

حين تحتاج إلى إظهار الوضعية لمدقق أو لفريق مشتريات مشترٍ، أنشئ حزمة HIPAA من ملف الأدلة من Settings → Compliance → Binder. يجمع إطار HIPAA تسجيل وصول PHI ووضعية BAA والاستبقاء المضبوط في حزمة موقعة جاهزة للتنزيل؛ يسجل كل إنشاء في سجل التدقيق، وتنتهي صلاحية رابط التنزيل بعد 24 ساعة.

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

يشحن سوق إضافات الامتثال حزمة تفعيل HIPAA healthcare تجهز ملف امتثال مسودة، وحملات مسودة، ووكيل AI مضبوطًا على القطاع، وإعداد تدفق انضمام في استدعاء واحد. إنها سقالة بداية، لا بديلًا عن هذا التسلسل: تفعيل الحزمة لا ينفذ BAA أبدًا، ولا يفعّل وضع HIPAA أبدًا، ولا يضع إرسالًا أبدًا. نفّذ الخطوات 1–6 أعلاه أولًا، ثم فعّل الحزمة واعمِل قائمة go-live الخاصة بها من المسودة إلى الإنتاج.

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

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

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

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

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

1. نفّذ BAA

1أ. أشهد بأن PHI ضمن النطاق

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

1ج. تأكد من تنفيذ BAA

2. فعّل وضع HIPAA

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

4. اضبط استبقاء البيانات

5. تحقق من الإعدادات

6. اقرأ سجل وصول PHI

7. صدّر ملف أدلة HIPAA

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

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

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

​1. نفّذ BAA

​1أ. أشهد بأن PHI ضمن النطاق

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

​1ج. تأكد من تنفيذ BAA

​2. فعّل وضع HIPAA

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

​4. اضبط استبقاء البيانات

​5. تحقق من الإعدادات

​6. اقرأ سجل وصول PHI

​7. صدّر ملف أدلة HIPAA

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

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

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

1. نفّذ BAA

1أ. أشهد بأن PHI ضمن النطاق

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

1ج. تأكد من تنفيذ BAA

2. فعّل وضع HIPAA

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

4. اضبط استبقاء البيانات

5. تحقق من الإعدادات

6. اقرأ سجل وصول PHI

7. صدّر ملف أدلة HIPAA

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

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