> ## 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.
# طلبات الوصول إلى بيانات صاحب البيانات (DSAR)
> تلقَّى طلبات أصحاب البيانات وفق GDPR وCCPA وCPRA وLGPD وPDPA وDPDP، وتحقّق منها، ونفّذها على Orbit عبر مسارات المشغّل أو البوابة العامة للخدمة الذاتية.
# طلبات الوصول إلى بيانات صاحب البيانات (DSAR)
**طلب الوصول إلى بيانات صاحب البيانات** (يُسمّى أيضًا طلب الخصوصية أو
طلب حقوق المستهلك) هو الآلية الرسمية التي يستخدمها الشخص لممارسة
حقوقه على البيانات الشخصية التي تحتفظ بها عنه — حق **الوصول**،
و**الحذف**، و**التصحيح**، و**النقل**، و**إلغاء الاشتراك في بيع**
تلك البيانات. تمنحك معظم قوانين الخصوصية موعدًا نهائيًا صارمًا للرد
(30 يومًا بموجب GDPR و45 يومًا بموجب CCPA/CPRA).
تمنحك Orbit مسارَين للاستقبال ومسارًا واحدًا للتنفيذ:
* **DSAR المقدَّم من المشغّل** — يقدّم فريق الدعم أو الامتثال لديك
الطلب نيابةً عن عميل عبر واجهة API المعرَّفة أو لوحة التحكم.
* **البوابة العامة للخدمة الذاتية** — يقدّم صاحب البيانات طلبه
بنفسه عبر مسار عام غير متطلِّب للمصادقة يثبت هويته برمز OTP
**لعامِلَين عبر البريد الإلكتروني + SMS** قبل إضافة أي شيء إلى
قائمة الانتظار.
تصف هذه الصفحة الضوابط المنصّية لـ Orbit. وهي **ليست نصيحة
قانونية.** تعتمد التزاماتك — القوانين التي تنطبق وما يجب عليك
كشفه والمدة المتاحة لك — على مكان إقامة أصحاب البيانات لديك وما
تعالجه من بيانات. تأكد لدى مستشار قانوني مؤهّل.
جميع نقاط النهاية أدناه متجذِّرة على
`https://api.orbit.devotel.io/api/v1/compliance`.
***
## الاختصاصات القضائية المدعومة والمواعيد النهائية
يتحكم `applicable_jurisdiction` على الطلب في الساعة القانونية التي
يطبّقها متعقّب SLA في Orbit. ويمكن للمشغّلين إعادة تصنيف الطلب بعد
الاستقبال.
| الاختصاص القضائي | الرمز | SLA للرد |
| ---------------------------------------------------- | -------- | -------- |
| GDPR الاتحاد الأوروبي / المنطقة الاقتصادية الأوروبية | `gdpr` | 30 يومًا |
| كاليفورنيا CCPA | `ccpa` | 45 يومًا |
| كاليفورنيا CPRA | `cpra` | 45 يومًا |
| البرازيل LGPD | `lgpd` | 15 يومًا |
| سنغافورة / تايلند PDPA | `pdpa` | 30 يومًا |
| كندا PIPEDA | `pipeda` | 30 يومًا |
| الهند DPDP | `dpdp` | 30 يومًا |
## أنواع الطلبات
يصف `request_type` ما يطلبه الصاحب. مجموعة أفعال CCPA/CPRA الكاملة
متاحة للمشغّلين؛ وتكشف البوابة العامة مجموعة فرعية أكثر ودية تُعرَض
عليها.
| `request_type` للمشغّل | المعنى | فعل البوابة العامة |
| ---------------------- | -------------------------------------------------------------------- | ------------------ |
| `know` | الوصول — كشف البيانات المُحتفَظ بها (GDPR المادة 15، CCPA §1798.110) | `access` |
| `delete` | الإزالة (GDPR المادة 17، CCPA §1798.105) | `delete` |
| `correct` | التصحيح (GDPR المادة 16، CPRA §1798.106) | — |
| `portability` | تصدير قابل للقراءة آليًا (GDPR المادة 20) | `portability` |
| `opt_out_sale` | إلغاء الاشتراك في البيع/المشاركة (CCPA §1798.120) | `opt_out` |
| `limit_sensitive_pi` | الحدّ من استخدام المعلومات الشخصية الحسّاسة (CPRA §1798.121) | — |
| `non_discrimination` | حق عدم التمييز (CCPA §1798.125) | — |
لطلبات وصول CCPA يمكنك أيضًا إرفاق `consumer_categories` — فئات
CCPA §1798.100(b) التي يسأل عنها الصاحب: `identifiers`،
`customer_records`، `protected_classifications`، `commercial`،
`biometric`، `internet_activity`، `geolocation`، `sensory`،
`professional`، `education`، `inferences`، `sensitive_pi`.
***
## طلبات المقدَّمة من المشغّل
### إنشاء طلب
`POST /compliance/dsar` — يتطلّب مفتاح API لمسؤول أو مالك. قدّم
معرّفًا واحدًا على الأقل لصاحب البيانات (`contact_id` أو
`subject_email` أو `subject_phone`) بالإضافة إلى `requester_email`
الذي يمُسّى تلقّي المراسلات.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dsar \
-H "X-API-Key: dv_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"subject_email": "jordan@example.com",
"requester_email": "jordan@example.com",
"applicable_jurisdiction": "gdpr",
"request_type": "know",
"verification_method": "email_link"
}'
```
يعيد `202 Accepted`:
```json theme={null}
{
"id": "dsar_8x2k…",
"status": "received",
"applicable_jurisdiction": "gdpr",
"request_type": "know",
"verification_status": "pending",
"message": "Request received and queued for verification."
}
```
| الحقل | النوع | الملاحظات |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact_id` | string | اختياري. يربط الطلب بجهة اتصال معروفة. |
| `subject_email` | email | يلزم أحد email / phone / contact\_id. |
| `subject_phone` | string | E.164. |
| `requester_email` | email | **مطلوب.** إليها تُرسَل تحديثات الحالة. |
| `applicable_jurisdiction` | enum | الافتراضي `gdpr`. يجب ضبطه صراحةً على `ccpa` أو `cpra` عندما يكون `request_type` هو `opt_out_sale` أو `limit_sensitive_pi` (راجع الملاحظة أدناه). |
| `request_type` | enum | الافتراضي `know`. |
| `consumer_categories` | string\[] | فئات CCPA (الوصول فقط). |
| `verification_method` | enum | `email_link`، `email_phone`، `document`، `manual_review`. |
| `requester_statement` | string | نص حر، ≤ 4096 حرفًا. |
| `authorized_agent` | object | `{ agent_name, agent_email, permission_document_id? }` عندما يقدّم وكيل نيابةً عن الصاحب. |
> **ملاحظة** — `applicable_jurisdiction` يفترض `gdpr` فقط للحقوق
> الموجودة بموجب GDPR. نوعا الطلب `opt_out_sale` و`limit_sensitive_pi`
> خاصّان بـ CCPA/CPRA ولا يقابلهما مقابل في GDPR، لذا يجب ضبط
> `applicable_jurisdiction` صراحةً على `ccpa` أو `cpra` لهما. إغفاله
> (أو ترك الافتراضي `gdpr`) يُرفَض بـ `422 VALIDATION_ERROR`.
### دورة حياة الحالة
ينتقل الطلب عبر:
`received` → `processing` → `completed`
مع فروع نهائية `failed` و`expired` و`cancelled`. تُتعقَّب حالة
**التحقق** الفرعية باستقلالية: `pending` → `verified` (يتابع العامل)
أو `rejected` (يتوقّف العامل). تفترض صفوف GDPR/المُقدَّمة من المسؤول
`not_required`.
### التحقق من الهوية أو رفضها
تتطلب الطلبات عالية الضمان (الحذف، وإلغاء الاشتراك، والحدّ من
الحسّاسة) قرار مشغّل قبل أن يستمر التنفيذ:
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dsar/dsar_8x2k…/verification \
-H "X-API-Key: dv_live_sk_..." \
-H "Content-Type: application/json" \
-d '{ "decision": "verified", "notes": "Matched gov-ID upload." }'
```
`decision` هو `verified` أو `rejected`؛ و`notes` اختياري
(≤ 2048 حرفًا). يعيد `verification_status` الجديد و`verified_at`.
### إلغاء طلب
`POST /compliance/dsar/{id}/cancel` يسحب طلبًا جاريًا (GDPR المادة
7(3)). يعمل فقط ما دام الطلب `received` أو `processing`؛ والطلب
النهائي يعيد `409 Conflict`.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dsar/dsar_8x2k…/cancel \
-H "X-API-Key: dv_live_sk_..." \
-H "Content-Type: application/json" \
-d '{ "reason": "Duplicate of dsar_7a1f…" }'
```
### إدراج الطلبات وقراءتها
* `GET /compliance/dsar` — قائمة مُرَحَّلة. الاستعلام: `page` (≥ 1)
و`page_size` (≤ 100، الافتراضي 25) ومُرشِّح `status` اختياري.
* `GET /compliance/dsar/{id}` — جلب طلب واحد. يتضمّن الرد
`export_url` الموقَّع (و`export_expires_at`) بمجرد أن يُنتَج تصدير
الوصول/النقل، بالإضافة إلى `tables_exported` التي تصف عدد الصفوف
لكل جدول.
### طلبات الإزالة
تُتعقَّب عمليات إزالة GDPR المادة 17 كمورد مستقل حتى تتمكن من
التدقيق والتدخل قبل إتلاف البيانات:
* `GET /compliance/dsar/erasure-requests` — القائمة. الاستعلام:
`status` (`pending`، `cancelled`، `executing`، `executed`،
`failed`) و`limit` (≤ 500).
* `POST /compliance/dsar/erasure-requests/{id}/cancel` — إلغاء إزالة
**معلَّقة** قبل تنفيذها. `reason` اختياري (≤ 500 حرفًا). يعيد `409`
إذا كانت تنفَّذ أو اكتملت.
### لوحة SLA
`GET /compliance/dsar/sla` يعيد لقطة SLA مشترَكة للتصدير والإزلة حتى
لا تفوّت موعدًا نهائيًا قانونيًا أبدًا:
```json theme={null}
{
"items": [
{
"id": "dsar_8x2k…",
"kind": "export",
"status": "processing",
"days_elapsed": 22,
"days_remaining": 8,
"severity": "amber",
"sla_deadline_at": "2026-07-01T00:00:00.000Z",
"approaching": true,
"breach": false,
"escalation_due": false
}
],
"alerts": {
"breached": 0,
"approaching": 1,
"escalation_due": 0,
"worst_severity": "amber",
"has_alert": true
},
"sla_days": 30
}
```
مستويات الخطورة **تتناسب طَرديًا مع نافذة SLA الخاصة بكل اختصاص
قضائي** — مُثبَّتة عتبات الأيام إلى حالة GDPR الـ30 يومًا وتُضرَب
بالنسبة `slaDays / 30`، حتى يتحوّل الطلب دائمًا إلى كهرماني وأحمر
عند النسبة ذاتها من موعده النهائي. `escalation_due` ينفّز 5 أيام قبل
الموعد النهائي القانوني (`slaDays − 5`).
بالنسبة لـ **GDPR** (`sla_days: 30`): **أخضر** (\< 20 يومًا مُنقضت)،
و**كهرماني** (20–25)، و**أحمر** (26–30)، و**أحمر + خرق** (> 30)؛
`escalation_due` عند يوم 25.
بالنسبة لـ **CCPA/CPRA** (`sla_days: 45`) تعطي النسب ذاتها **أخضر**
(\< 30) و**كهرماني** (30–38) و**أحمر** (39–45) و**أحمر + خرق** (> 45)؛
`escalation_due` عند يوم 40. اقرأ دائمًا حدود المستوى مقابل
`sla_days` المعادة لذلك الطلب، لا الأرقام الثابتة 20/25/30.
***
## البوابة العامة للخدمة الذاتية
يتيح المسار العام لصاحب البيانات تقديم طلب دون حساب. الهوية تُثبَت
بـ **OTP لعامِلَين** — رمز بريد إلكتروني ورمز SMS — قبل إضافة أي
طلب إلى قائمة الانتظار. تعيش نقاط النهاية تحت
`/compliance/public/dsar` وهي غير متطلِّبة للمصادقة، لكنها مُحَصَّنة
بـ Cloudflare Turnstile وحدود المعدّل لكل IP ولكل مُعرِّف، وشكل الرد
المناسِك للخصوصية لا يكشف أبدًا إن تُطابَقت ثنائية البريد/الهاتف
جهة اتصال حقيقية.
رموز التحقق عبر SMS تُسلَّم عبر softswitch من Devotel (مسار SMS
الصادر الوحيد للمنصّة). وهي OTP منصّية، لا حركة قابلة للفوترة من
المستأجر، ولا تحمل أي دوام لإيصالات التسليم.
### نظرة عامة على المسار
`POST /compliance/public/dsar/begin` مع `email` و`phone` (E.164)
و`request_type` (`access` | `delete` | `portability` | `opt_out`)
و`turnstile_token` من Cloudflare (مطلوب في الإنتاج). يعيد
`claim_id` غير شفّاف و`email_sent: true` و`expires_in: 600`. يُرسَل
OTP البريد فورًا.
`POST /compliance/public/dsar/verify-email` مع `claim_id` والرمز
`code` المكوّن من 6 أرقام. يعيد الحالة `email_verified` والخطوة
التالية `phone_send`. تنتهي صلاحية الرموز بعد 10 دقائق؛ حد أقصى 3
محاولات. `POST …/resend-email` (مع `claim_id` + `email`) يصدر
رمزًا جديدًا، خاضعًا لتأخير 60 ثانية.
`POST /compliance/public/dsar/send-phone` مع `claim_id` و`phone`
الذي يُطابق المُعطى عند البدء. يرسل OTP عبر SMS
(`expires_in: 600`). ينطبق تأخير 60 ثانية بين الإرسالات؛ المحاولة
المبكرة تعيد `429` مع `Retry-After`.
`POST /compliance/public/dsar/verify-phone` مع `claim_id` والرمز
`code` المكوّن من 6 أرقام. يعيد الحالة `phone_verified` والخطوة
التالية `submit`.
`POST /compliance/public/dsar/submit` مع `claim_id`. يستمرّ بصفّ
تدقيق و — فقط إذا تُطابَقت البريد والهاتف المُتحقَّق بجهة اتصال
في مستأجرك — يُضيف DSAR حقيقيًا إلى قائمة الانتظار (مُسبَقًا
`verification_status: verified`، لأن OTP أثبت الهوية بالفعل).
يعيد `reference_id` (مثل `dsar_pub_…`) وقيمة `queued` منطقية.
### تهيئة مرسِلي إثبات الهوية
يُرسَل الرمزان OTP من مرسِلَين على مستوى المنصّة تهيّئهما مرة واحدة في
بيئة API لديك. اضبطهما قبل نشر البوابة — مرسِل SMS غير مضبوط بدون
بديل يجعل خطوة الهاتف تفشل إغلاقًا (fail-closed).
| المتغيّر | يُستخدَم لـ | الافتراضي / البديل |
| ------------------------------- | --------------------------- | ------------------------------------------------------------------------- |
| `DEVOTEL_DSAR_PROOF_FROM_EMAIL` | عنوان From على OTP البريد. | `privacy@orbit.devotel.io`. يحتاج التسليم أيضًا `DEVOTEL_RESEND_API_KEY`. |
| `DEVOTEL_DSAR_PROOF_SMS_FROM` | مرسِل E.164 على OTP الـSMS. | يستبدل إلى `DEVOTEL_PLATFORM_DEFAULT_FROM`. |
إذا كان `DEVOTEL_DSAR_PROOF_SMS_FROM` **و**`DEVOTEL_PLATFORM_DEFAULT_FROM`
كلاهما غير مضبوط، فإن خطوة `send-phone` **تفشل إغلاقًا بـ `503`** —
تعود البوابة برسالة «غير متاحة مؤقتًا» ويُبثّ الفشل تحت مقياس
`dsar.proof.sms_send_failed` حتى يطفو في لوحاتك بدل تخطّي العامل
الثاني صامتًا. بالمثل، خطوة البريد تعود بـ `503` عندما تكون
`DEVOTEL_RESEND_API_KEY` غير مضبوطة. هيّئ كلا المرسِلَين قبل أن تربط
البوابة علنًا.
### دفاعات إساءة الاستخدام
| التحكّم | الحدّ |
| --------------------- | -------------------------------------------------------- |
| Cloudflare Turnstile | مطلوب على `begin` في الإنتاج (fail-closed). |
| `begin` لكل IP | 3 لكل ساعة. |
| تأخير لكل بريد | 1 لكل 60 ثانية. |
| تأخير SMS لكل هاتف | 1 لكل 60 ثانية. |
| بوّابة Fastify لكل IP | 30 طلبًا/دقيقة لكل IP، مطبّقة باستقلالية لكل نقطة نهاية. |
| TTL / محاولات OTP | 10 دقائق، حد أقصى 3 محاولات لكل رمز. |
| TTL المطالِبة | 30 دقيقة من الطرف إلى الطرف. |
شكل الرد مطابق سواء تُطابَقت المُعرِّفات جهة اتصال حقيقية أم لا —
البوابة لا تؤكّد ولا تنفي أبدًا أن شخصًا ما في قاعدة بياناتك. عندما
يكون Redis غير متاح، تتفشّى بوّابات الحدّ من المعدّل **فتحًا
(fail-open)** للحفاظ على التوافر.
### تمكين حماية Turnstile
بوّابة Turnstile تُهيَّأ بمتغيّرين بيئيّين.
| المتغيّر | متى | الوصف |
| ---------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `DEVOTEL_TURNSTILE_SECRET_KEY` | API (الخادم) | سرّ Cloudflare Turnstile. نقطة نهاية `begin` تتحقّق من `turnstile_token` المقدَّم مقابل Cloudflare عندما يُضبَط هذا. |
| `NEXT_PUBLIC_DEVOTEL_TURNSTILE_SITE_KEY` | Web (العميل) | مفتاح موقع Turnstile العام الذي تُقسِد البوابة الودجت به. |
البوّابة **فاشلة فتحًا (fail-open)** عندما تكون
`DEVOTEL_TURNSTILE_SECRET_KEY` غير مضبوطة: `begin` يقبل الطلبات
بدون رمز ويُسجّل تحذيرًا واحدًا. اضبط السرّ في الإنتاج، وإلا تصبح
البوابة غير محمية بـ Turnstile حتى مع بقاء كل دفاع إساءة آخر أعلاه
مطبّقًا. ولّد كلا المفتاحين في لوحة تحكم Cloudflare (Turnstile →
Add site) واضبطهما على نشر API وWeb على التوالي.
***
## إيواء رابط البوابة
انشر البوابة العامة تحت سياسة خصوصيتك كرابط «تقديم طلب خصوصية».
لأن المسار يتحقّق ذاتيًا عبر OTP، فإن الطلبات التي تصل عبره قد
أُثبِتت هويتها بالفعل — تهبط في قائمة انتظار المشغّل جاهزة للتنفيذ،
وتظهر في `GET /compliance/dsar` بجانب الطلبات المقدَّمة من المشغّل.
***
## مراجع ذات صلة
* [تجميع وضعية GDPR كاملة](/compliance/gdpr-posture-guide) — موضع
استقبال DSAR في المسار الكامل.
* [إدارة الموافقة](/compliance/consent-management) — سجّل وابحث عن
حالة الموافقة التي قد يطلب منك DSAR احترامها.
* [قوائم إلغاء الاشتراك والكبح](/compliance/opt-out-suppression) —
كيف تسري نتائج `delete` / `opt_out` إلى الكبح.
* [موافقة تسجيل المكالمات](/compliance/recording-consent) — معالجة
التسجيلات التي يشير إليها طلب الوصول.
* [مرجع API → الامتثال](/api-reference/endpoints/compliance) — مخططات
الطلب/الرد الكاملة (مُعاد إنشاؤها من API الحيّ).