واجهة برمجة تطبيقات محو البيانات

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

عنوان URL الأساسي

https://rpc-api.svc-nue.pushwoosh.com

يتم تقديم جميع نقاط النهاية عبر HTTPS. تستخدم الطلبات والاستجابات application/json، باستثناء Upload، الذي يأخذ multipart/form-data.

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز Server API token الخاص بك:

Authorization: Api YOUR_API_TOKEN

يجب أن يمتلك الرمز صلاحية التعديل على كل تطبيق مذكور في application_codes. وهي نفس الصلاحية التي يحتاجها الرمز لكتابة بيانات الأجهزة على تلك التطبيقات.

الاصطلاحات

تسمية الحقول: تقبل أجسام الطلبات lowerCamelCase (على سبيل المثال، applicationCodes، identifierType). يتم ترتيب الاستجابات باستخدام أسماء حقول proto، في snake_case (task_id، identifier_hash، وما إلى ذلك). تستخدم الأمثلة ومراجع الكائنات أدناه تلك الحالة.
المعرفات: يتم تحديد الشخص عبر identifier_type (SUBJECT_IDENTIFIER_USER_ID أو SUBJECT_IDENTIFIER_HWID أو SUBJECT_IDENTIFIER_EMAIL) بالإضافة إلى قائمة identifiers من ذلك النوع الواحد. تتم مطابقة معرف البريد الإلكتروني بغض النظر عن حالة الأحرف.
تشغيل تجريبي أولاً، ثم الاستشهاد به: يقوم Create مع dry_run: true بعدّ ما سيتم محوه فقط دون كتابة أي شيء. الاستشهاد بـ task_id الخاص بذلك التشغيل التجريبي كـ confirmation_dry_run_task_id في الاستدعاء الفعلي أمر اختياري، لكن إذا استشهدت بواحد، فيجب أن يطابق تطبيقات ومعرفات ذلك التشغيل التجريبي تمامًا، وأن يُستدعى خلال 15 دقيقة من انتهائه. وإلا يُرفض الاستدعاء.
لا تحمل التقارير المعرف أبدًا بنص واضح. يُبلّغ كل من GetTaskReport وGetJournalReport عن كل معرف كتجزئة sha256 خاصة به (identifier_hash)، ويكون نص التقرير بترميز CSV مُشفّرًا بـ base64 داخل استجابة JSON.

استجابات الخطأ

رمز حالة HTTP	المعنى
`400 Bad Request`	وسيطة غير صالحة، مثل `identifier_type` أو `identifiers` أو `application_codes` فارغة، أو أكثر من 10,000 معرف، أو أكثر من 50 تطبيقًا، أو ناتج معرفات × تطبيقات يتجاوز 50,000، أو سلسلة معرف فارغة، أو (في Upload فقط) ملف CSV مفقود أو غير قابل للقراءة. تُعاد أيضًا كـ `FailedPrecondition` على السلك عندما لا يطابق `confirmation_dry_run_task_id` المُستشهد به التشغيل التجريبي المنتهي الذي يسمّيه، أو يكون قديمًا جدًا (أكثر من 15 دقيقة)، أو لا يكون تشغيلاً تجريبيًا منتهيًا على الإطلاق.
`401 Unauthorized`	ترويسة `Authorization` مفقودة أو غير صالحة.
`403 Forbidden`	لا يمتلك الرمز صلاحية التعديل/بيانات الجهاز على أحد التطبيقات المطلوبة، أو لا يجوز للمتصل قراءة المهمة/التقرير المطلوب.
`404 Not Found`	لم يتم العثور على المهمة، أو أنها لا تنتمي إلى حساب المتصل.
`413 Payload Too Large`	(في Upload فقط) حجم الملف المرفوع يتجاوز 5 MB.
`429 Too Many Requests`	بدأ الحساب بالفعل 20 مهمة محو بيانات (بما في ذلك التشغيلات التجريبية) خلال آخر 24 ساعة.

نقاط النهاية

الطريقة	المسار	الوصف
`POST`	`/api/data_erasure/tasks`	إنشاء مهمة محو (أو تشغيل تجريبي)
`POST`	`/api/data_erasure/upload`	إنشاء مهمة محو من ملف CSV مرفوع للمعرفات
`GET`	`/api/data_erasure/tasks`	سرد مهام المحو الخاصة بالحساب
`GET`	`/api/data_erasure/tasks/{task_id}`	الحصول على مهمة محو واحدة
`GET`	`/api/data_erasure/tasks/{task_id}/rows`	سرد نتائج مهمة واحدة لكل معرف
`GET`	`/api/data_erasure/tasks/{task_id}/report`	تنزيل تقرير مهمة واحدة كملف CSV
`GET`	`/api/data_erasure/report`	تنزيل كل مهام فترة زمنية كملف CSV واحد

Create

يبدأ محو البيانات الشخصية للأشخاص المدرجين في التطبيقات المدرجة. مع dry_run: true، تقوم المهمة بعدّ ما سيتم محوه فقط.

POST /api/data_erasure/tasks

نص الطلب

المعلمة	النوع	مطلوب	الوصف
`identifierType`	string	نعم	`SUBJECT_IDENTIFIER_USER_ID` أو `SUBJECT_IDENTIFIER_HWID` أو `SUBJECT_IDENTIFIER_EMAIL`.
`identifiers`	array of strings	نعم	معرفات الأشخاص من ذلك النوع الواحد، حتى 10,000 لكل مهمة، دون قيم فارغة.
`applicationCodes`	array of strings	نعم	رموز التطبيقات المراد المحو منها، حتى 50 تطبيقًا. لا توجد طريقة للمحو من كل تطبيقات الحساب في استدعاء واحد، لذا سمِّ كل تطبيق صراحةً. يجب ألا يتجاوز `identifiers.length × applicationCodes.length` قيمة 50,000، لأن التقرير يحتوي على صف واحد لكل معرف لكل تطبيق.
`dryRun`	boolean	لا	يعدّ ما سيتم محوه دون كتابة أي شيء. القيمة الافتراضية `false`.
`confirmationDryRunTaskId`	integer	لا	`task_id` الخاص بتشغيل تجريبي منتهٍ قاس عملية المحو هذه بالضبط. راجع الاصطلاحات.

مثال على الطلب

{
  "identifierType": "SUBJECT_IDENTIFIER_EMAIL",
  "identifiers": ["subject@example.com"],
  "applicationCodes": ["XXXXX-XXXXX"],
  "dryRun": true
}

الاستجابة

الحقل	النوع	الوصف
`task_id`	integer	معرف المهمة التي تم إنشاؤها. استخدمه مع كل نقطة نهاية أخرى في هذه الصفحة.

Upload

تُنشئ نفس نوع المهمة التي ينشئها Create، لكن المعرفات تأتي من ملف CSV مرفوع بدلاً من مصفوفة JSON. استخدم هذا لقائمة أشخاص كبيرة.

POST /api/data_erasure/upload

الطلب (multipart/form-data)

الحقل	مطلوب	الوصف
`file`	نعم	ملف CSV، حتى 5 MB، معرف واحد لكل صف، في عمود واحد. يمكن أن يُسمّي الصف الأول العمود (`user_id` أو `userid` أو `user id` أو `hwid` أو `email` أو `identifier` أو `subject`، بغض النظر عن حالة الأحرف) بدلاً من احتوائه على معرف. يُتخطى ذلك الصف حينها كترويسة، ولا يُحتسب. تُتخطى الصفوف الفارغة وتُحتسب بشكل منفصل. تُدمج المعرفات المكررة (بغض النظر عن حالة الأحرف، بالنسبة للبريد الإلكتروني) في واحد وتُحتسب بشكل منفصل.
`identifier_type`	نعم	`user_id` أو `hwid` أو `email`، بأحرف صغيرة، وهي حالة أحرف مختلفة عن قيم تعداد `identifierType` في JSON المستخدمة في مواضع أخرى من هذه الصفحة. ينطبق نوع واحد على الملف بأكمله.
`application_codes`	نعم	رموز تطبيقات مفصولة بفواصل.
`dry_run`	لا	`true`/`false`.
`confirmation_dry_run_task_id`	لا	نفس المعلمة في `Create`.

الاستجابة

{
  "task_id": 123,
  "identifier_count": 480,
  "duplicate_count": 3,
  "skipped_rows": 1
}

ListTasks

يسرد عمليات المحو الخاصة بالحساب، الأحدث أولاً: سجل تدقيق لمن محا ماذا ومتى. تُستبعد التشغيلات التجريبية ما لم يتم تعيين includeDryRuns.

GET /api/data_erasure/tasks

معلمات الاستعلام

المعلمة	النوع	الوصف
`limit` / `offset`	integer	التصفح عبر الصفحات.
`includeDryRuns`	boolean	تضمين مهام التشغيل التجريبي (القياس فقط).
`from` / `to`	string (RFC 3339)	الاحتفاظ بالمهام التي بدأت ضمن `[from, to)`.
`applicationCode`	string	الاحتفاظ بالمهام التي تغطي هذا التطبيق.
`initiatorUserId`	integer	الاحتفاظ بالمهام التي بدأها مستخدم لوحة التحكم هذا. `0` (الافتراضي) يحتفظ بكل المُبادِرين.
`initiatorTokenId`	integer	الاحتفاظ بالمهام التي بدأها رمز API هذا. `0` (الافتراضي) يحتفظ بكل المُبادِرين.
`initiatorEmail`	string	الاحتفاظ بالمهام التي بدأها مستخدم لوحة التحكم هذا، مطابقًا بالبريد الإلكتروني، بغض النظر عن حالة الأحرف.

الاستجابة

الحقل	النوع	الوصف
`tasks`	array of كائنات مهمة محو البيانات	المهام المطابقة.

GetTask

يُرجع مهمة محو واحدة مع حالتها وعداداتها. استخدمه لمتابعة مهمة بدأها Create أو Upload.

GET /api/data_erasure/tasks/{task_id}

الاستجابة

الحقل	النوع	الوصف
`task`	كائن مهمة محو البيانات	المهمة المطلوبة.

ListTaskRows

يُرجع نتيجة مهمة واحدة لكل معرف: ما تم حذفه، أو لم يُعثر عليه، أو تم تخطيه، أو فشل. تُبلَّغ المعرفات كتجزئة sha256 الخاصة بها.

GET /api/data_erasure/tasks/{task_id}/rows

معلمات الاستعلام

المعلمة	النوع	الوصف
`limit` / `offset`	integer	التصفح عبر الصفحات.

الاستجابة

الحقل	النوع	الوصف
`rows`	array of كائنات صف مهمة محو البيانات	صفحة النتائج هذه.

GetTaskReport

يُرجع التقرير الكامل لمهمة واحدة كملف CSV: صف واحد لكل معرف لكل تطبيق، مع نتيجته. يعرض ListTaskRows الصفوف نفسها صفحة بصفحة بدلاً من ذلك.

GET /api/data_erasure/tasks/{task_id}/report

الاستجابة

الحقل	النوع	الوصف
`filename`	string	اسم الملف المقترح، على سبيل المثال `data-erasure-task-42.csv`.
`content_type`	string	`text/csv`.
`content`	string (base64)	ملف CSV. الأعمدة: `task_id`، `created`، `identifier_type`، `identifier_hash`، `application_code`، `result`، `detail`.

GetJournalReport

يُرجع كل عمليات المحو في فترة زمنية كملف CSV واحد: صف لكل معرف لكل تطبيق، مع المهمة ومُبادِرها في كل صف. هذا ما يقدّمه الحساب لمدقق الحسابات.

GET /api/data_erasure/report

معلمات الاستعلام

المعلمة	النوع	مطلوب	الوصف
`from`	string (RFC 3339)	نعم	بداية الفترة الزمنية.
`to`	string (RFC 3339)	لا	نهاية الفترة الزمنية. الافتراضي هو الآن.
`includeDryRuns`	boolean	لا	تضمين مهام التشغيل التجريبي.

الاستجابة

الحقل	النوع	الوصف
`filename`	string	اسم الملف المقترح، على سبيل المثال `data-erasure-2026-01-01-2026-04-01.csv`.
`content_type`	string	`text/csv`.
`content`	string (base64)	ملف CSV. الأعمدة: `task_id`، `task_created`، `initiator_user_id`، `initiator_email`، `initiator_token_id`، `dry_run`، `identifier_type`، `identifier_hash`، `application_code`، `result`، `detail`، `row_created`.

كائن مهمة محو البيانات

الحقل	النوع	الوصف
`task_id`	integer	معرف المهمة.
`identifier_type`	string	`SUBJECT_IDENTIFIER_USER_ID` أو `SUBJECT_IDENTIFIER_HWID` أو `SUBJECT_IDENTIFIER_EMAIL`.
`application_codes`	array of strings	التطبيقات التي تغطيها المهمة.
`dry_run`	boolean	ما إذا كانت هذه المهمة قد قاست حجمًا فقط.
`status`	string	`ERASURE_TASK_STATUS_PENDING` أو `_IN_PROGRESS` أو `_DONE` أو `_FAILED`.
`total_count`	integer	حاصل ضرب المعرفات × التطبيقات التي تغطيها هذه المهمة.
`deleted_count`	integer	عدد ما تم محوه (أو، في حالة التشغيل التجريبي، ما سيُمحى).
`not_found_count`	integer	عدد ما لم يطابق أي شيء.
`failed_count`	integer	عدد ما فشل. راجع ListTaskRows أو التقرير لمعرفة السبب.
`fail_reason`	string	يُعيَّن عندما تكون `status` هي `ERASURE_TASK_STATUS_FAILED`.
`initiator_user_id`	integer	مستخدم لوحة التحكم الذي بدأ المهمة. `0` عندما يكون رمز API هو من بدأها.
`initiator_token_id`	integer	رمز API الذي بدأ المهمة. `0` عندما يكون مستخدم لوحة التحكم هو من بدأها.
`initiator_email`	string	عنوان بريد مستخدم لوحة التحكم الذي بدأ المهمة. فارغ في حالة رمز API.
`created`	string (RFC 3339)	وقت إنشاء المهمة.
`started_at`	string (RFC 3339)	وقت بدء عملية المحو.
`finished_at`	string (RFC 3339)	وقت وصول المهمة إلى حالة نهائية.

كائن صف مهمة محو البيانات

الحقل	النوع	الوصف
`identifier_hash`	string	تجزئة sha256 للمعرف. لا يخزّن التقرير المعرف نفسه أو يُرجعه أبدًا.
`application_code`	string	التطبيق الذي تنطبق عليه نتيجة هذا الصف.
`result`	string	`ERASURE_ROW_RESULT_DELETED` أو `_NOT_FOUND` أو `_SKIPPED` أو `_FAILED`.
`detail`	string	تفصيل تقني، يُعيَّن غالبًا عند الفشل.
`created`	string (RFC 3339)	وقت كتابة هذا الصف.

مواضيع ذات صلة

طلبات البيانات (دليل المنتج)

محو البيانات الشخصية من User Explorer