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

# قائمة حظر العملاء

> احظر عميلاً لإيقاف عمليات الدفع المستقبلية، وإلغاء اشتراكاته النشطة، وجعل Customer Portal للقراءة فقط. أدر قائمة الحظر من الإعدادات أو عبر API.

<Info>
  تمنع قائمة حظر العملاء عميلاً معروفاً بسلوكه الضار من الشراء منك مرة أخرى. لا يستطيع العميل المحظور الدفع، ويفقد اشتراكاته النشطة، ويمكنه عرض أي شيء في [Customer Portal](/features/customer-portal) دون تغييره. أدر القائمة من **الإعدادات ← قائمة الحظر** أو عبر Blocklist API.
</Info>

<Frame caption="The Blocklist tab under Settings">
  <img src="https://mintcdn.com/dodopayments/c1t35qHSH45TR4GO/images/blocklist/blocklist-settings.png?fit=max&auto=format&n=c1t35qHSH45TR4GO&q=85&s=771eb4a5654fbd22e6a5110cfb1a2e9d" alt="صفحة إعدادات قائمة الحظر التي تعرض العدد الإجمالي للعملاء المحظورين، وجدولاً بالإدخالات المحظورة يتضمن أعمدة المعرّف، والمحظور بواسطة، والمحظور في، وزر الإضافة إلى قائمة الحظر" style={{ maxHeight: '500px', width: 'auto' }} width="2358" height="1554" data-path="images/blocklist/blocklist-settings.png" />
</Frame>

## ماذا يحدث عند حظر عميل

| المنطقة                        | التأثير                                                                                                                                                                                                               |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **إتمام الدفع**                | يُرفض كلٌّ من محاولات الدفع من البريد الإلكتروني المحظور: payment links وcheckout sessions وعمليات الدفع أو الاشتراكات المنشأة عبر API.                                                                               |
| **الاشتراكات النشطة**          | تُلغى الاشتراكات ذات الحالات `pending` أو `active` أو `on_hold` أو `paused` بسبب `cancelled_by_merchant`. ويُطلَق webhook المعتاد `subscription.cancelled` لكل اشتراك منها.                                           |
| **التجديدات وإعادة المحاولات** | تتخطى التجديدات التلقائية و[إعادة محاولات الدفع](/features/recovery/payment-retries) العميل المحظور، لذلك لا يتم تحصيل أي مبلغ إضافي حتى إذا كان الإلغاء لا يزال قيد الانتظار.                                        |
| **إعادة المحاولة اليدوية**     | تُرفض [إعادة المحاولة اليدوية](/features/recovery/manual-retry) لدفعة العميل المحظور.                                                                                                                                 |
| **Customer Portal**            | لا يزال بإمكان العميل تسجيل الدخول وعرض الفواتير والاشتراكات ومفاتيح الترخيص، لكنه لا يستطيع إلغاء الاشتراك أو إيقافه مؤقتاً أو استئنافه، أو تغيير الخطط، أو تحديث طريقة الدفع. يظل حذف طريقة الدفع المحفوظة مسموحاً. |

<Note>
  لا يؤدي الحظر إلى رد المدفوعات السابقة، ولا يؤثر في النزاعات المفتوحة. أجرِ أي عملية رد أموال بشكل منفصل من صفحة [Refunds](/features/transactions/refunds).
</Note>

## كيف تطابق قائمة الحظر العملاء

يمكنك الحظر باستخدام **معرّف العميل** أو **البريد الإلكتروني**. وفي كلتا الحالتين، يعتمد الحظر على البريد الإلكتروني للعميل، وليس على سجل العميل:

* **يشمل كل سجل يحمل ذلك البريد الإلكتروني.** يمكن أن ينشئ إتمام الدفع سجل عميل جديداً لبريد إلكتروني عائد، لذلك يمكن تجاوز الحظر على معرّف عميل واحد، لكن لا يمكن تجاوز الحظر على البريد الإلكتروني.
* **يشمل العناوين البديلة.** تُقارَن عناوين البريد الإلكتروني بأحرف صغيرة بعد إزالة `+alias`، لذلك يُعد `buyer+promo@example.com` و`Buyer@example.com` العميل نفسه. وتبقى النقاط في العنوان كما هي.
* **يقتصر على نشاطك التجاري.** ينطبق الحظر على نشاطك التجاري فقط. ولا يزال بإمكان البريد الإلكتروني نفسه الشراء من أنشطة تجارية أخرى على Dodo Payments.
* **يجب أن يكون البريد الإلكتروني مرتبطاً بعميل موجود.** لا يمكنك حظر بريد إلكتروني لم يُتم عملية دفع معك من قبل، كما لا يمكن حظر سجل عميل بلا بريد إلكتروني.

## حظر عميل

<Tabs>
  <Tab title="From Settings">
    <Steps>
      <Step title="Open the Blocklist">
        انتقل إلى **الإعدادات ← قائمة الحظر** في لوحة التحكم.
      </Step>

      <Step title="Add to Blocklist">
        انقر على **الإضافة إلى قائمة الحظر**، ثم أدخل البريد الإلكتروني للعميل أو معرّف العميل. أضف سبباً حتى يتمكن فريقك لاحقاً من معرفة سبب إضافة الحظر.
      </Step>

      <Step title="Confirm">
        أكّد الحظر. تُلغى اشتراكات العميل النشطة فوراً، ويظهر الإدخال في جدول **الإدخالات المحظورة**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="From the customer's page">
    <Steps>
      <Step title="Open the customer">
        انتقل إلى **المبيعات ← العملاء** وافتح العميل الذي تريد حظره.
      </Step>

      <Step title="Block the customer">
        انقر على **حظر العميل**. بعد تفعيل الحظر، تعرض الصفحة شارة **محظور** بجوار اسم العميل.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## إدارة العملاء المحظورين

تعرض صفحة **قائمة الحظر** كل حظر نشط:

* **إجمالي العملاء المحظورين**: عدد العملاء المحظورين حالياً.
* **الإدخالات المحظورة**: صف واحد لكل حظر، يتضمن **المعرّف** الذي أدخلته (البريد الإلكتروني أو معرّف العميل)، و**المحظور بواسطة** (عضو الفريق الذي أضاف الحظر)، و**تاريخ الحظر**.
* **البحث في المعرّف** و**عوامل التصفية**: اعثر على إدخال باستخدام البريد الإلكتروني أو معرّف العميل، أو صفِّ النتائج حسب الشخص الذي أضاف الحظر ووقت إضافته.
* **الإجراء**: أدر الإدخال، بما في ذلك إلغاء حظر العميل.

### صفحة العميل المحظور

<Frame caption="A blocked customer's details page">
  <img src="https://mintcdn.com/dodopayments/c1t35qHSH45TR4GO/images/blocklist/blocked-customer-details.png?fit=max&auto=format&n=c1t35qHSH45TR4GO&q=85&s=83e1225a8e71c003d2bf660f0eea9c08" alt="صفحة معلومات العميل لعميل محظور تعرض شارة محظور، وزر إلغاء حظر العميل، وسجل نشاط يتضمن ملاحظة وحدث الإضافة إلى قائمة الحظر، ولوحة معرّفات مرجعية تتضمن معرّف العميل" style={{ maxHeight: '500px', width: 'auto' }} width="2366" height="1554" data-path="images/blocklist/blocked-customer-details.png" />
</Frame>

افتح عميلاً محظوراً من **المبيعات ← العملاء** أو من صفحة قائمة الحظر لعرض ما يلي:

* شارة **محظور** بجوار اسم العميل، وزر **إلغاء حظر العميل**.
* **سجل النشاط**: وقت إضافة العميل إلى قائمة الحظر، والسبب، وأي ملاحظات أضافها فريقك منذ ذلك الحين. انقر على **إضافة ملاحظة** لتسجيل سياق جديد، مثل نتيجة عملية رد المدفوعات. ويمكن تعديل الملاحظات لاحقاً.
* **المعرّفات المرجعية**: معرّف العميل المرتبط بهذا الحظر، جاهز للنسخ.

## إلغاء حظر عميل

انقر على **إلغاء حظر العميل** في صفحة العميل، أو استخدم قائمة الإجراءات في صفحة قائمة الحظر.

* تُستعاد تغييرات إتمام الدفع وCustomer Portal فوراً.
* **لا تُعاد تفعيل الاشتراكات الملغاة.** يجب على العميل الشراء مرة أخرى.
* يُحتفظ بالإدخال كسجل تدقيق مع ملاحظاته، لكنه لا يظهر بعد ذلك في القائمة النشطة.
* يمكنك حظر العميل نفسه مرة أخرى لاحقاً، وينشئ ذلك إدخالاً جديداً.

## ما يراه العميل

لا يتم إبلاغ العميل المحظور مطلقاً بأنه محظور.

* **عند إتمام الدفع**، تفشل الدفعة مع رفض عام: "لا يمكن معالجة هذه الدفعة." تُرجع API القيمة HTTP `403` مع رمز الخطأ `PAYMENT_NOT_PERMITTED`، من دون ذكر السبب. ويُسجَّل السبب الحقيقي في سجلات Dodo Payments فقط.
* **في Customer Portal**، تظل كل العناصر مرئية، لكن تُعطَّل جميع الإجراءات. وتُرجع أي عملية كتابة محظورة `PORTAL_ACTION_NOT_PERMITTED` مع الرسالة "هذا الإجراء غير متاح." ويتضمن ملف تعريف البوابة `read_only: true` حتى يتمكن تكامل بوابة مخصص من تعطيل عناصر التحكم الخاصة به. ولا تعرض البوابة إدخال قائمة الحظر أو ملاحظاته مطلقاً.

<Warning>
  إذا كنت تعرض أخطاء إتمام الدفع أو البوابة في منتجك الخاص، فحافظ على هذا السلوك. اعرض رسالة عامة للقيمتين `PAYMENT_NOT_PERMITTED` و`PORTAL_ACTION_NOT_PERMITTED`. فكشف الحظر يخبر صاحب السلوك الضار بتجربة بريد إلكتروني مختلف.
</Warning>

## استخدام API

تتيح لك Blocklist API الحظر من أدواتك الخاصة، مثلاً عند وصول عملية رد مدفوعات. وتتطلب [مفتاح API](/api-reference/introduction) السري الخاص بك. ويمكن لأي مفتاح سرد الإدخالات وقراءة الملاحظات. أما المفتاح المفعّل له **وصول للكتابة** فيمكنه حظر العملاء وإلغاء حظرهم وإدارة الملاحظات. وتطبّق لوحة التحكم التقسيم نفسه على أدوار الفريق: يقرأ دور **المشاهد** القائمة، بينما يجري دور **المحرر** التغييرات.

| الطريقة  | نقطة النهاية                                      | الغرض                                                  |
| -------- | ------------------------------------------------- | ------------------------------------------------------ |
| `GET`    | `/blocklist/customers`                            | سرد العملاء المحظورين، مع عوامل التصفية وعدّاد `total` |
| `POST`   | `/blocklist/customers`                            | حظر عميل باستخدام معرّف العميل أو البريد الإلكتروني    |
| `GET`    | `/blocklist/customers/{entry_id}`                 | الحصول على إدخال مع ملاحظاته                           |
| `DELETE` | `/blocklist/customers/{entry_id}`                 | إلغاء حظر عميل                                         |
| `POST`   | `/blocklist/customers/{entry_id}/notes`           | إضافة ملاحظة                                           |
| `PATCH`  | `/blocklist/customers/{entry_id}/notes/{note_id}` | تحديث ملاحظة                                           |

### حظر عميل

أرسل `customer_id` أو `email` في المستوى الأعلى من body. ويُعد `reason` اختيارياً ويظهر في صفحة الإدخال.

<CodeGroup>
  ```typescript Node.js theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  });

  // Block by customer ID
  const entry = await client.blocklist.customers.create({
    customer_id: 'cus_0NmichXWP8JYBB9Dw1Unj',
    reason: 'Chargeback on pay_0NmichXuYoNoapmr',
  });

  // Or block by email
  const byEmail = await client.blocklist.customers.create({
    email: 'buyer@example.com',
    reason: 'Repeated refund abuse',
  });

  console.log(entry.id, entry.cancelled_subscription_ids);
  ```

  ```python Python theme={null}
  import os
  from dodopayments import DodoPayments

  client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

  # Block by customer ID
  entry = client.blocklist.customers.create(
      customer_id="cus_0NmichXWP8JYBB9Dw1Unj",
      reason="Chargeback on pay_0NmichXuYoNoapmr",
  )

  # Or block by email
  by_email = client.blocklist.customers.create(
      email="buyer@example.com",
      reason="Repeated refund abuse",
  )

  print(entry.id, entry.cancelled_subscription_ids)
  ```

  ```bash cURL theme={null}
  curl -X POST https://live.dodopayments.com/blocklist/customers \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
      "reason": "Chargeback on pay_0NmichXuYoNoapmr"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "bcu_7Hq2mV9kRt4LxYw3Pz",
  "customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
  "customer_name": "wow guy",
  "customer_email": "wowguy@example.com",
  "identifier": "cus_0NmichXWP8JYBB9Dw1Unj",
  "reason": "Chargeback on pay_0NmichXuYoNoapmr",
  "source": "api",
  "blocked_by_email": null,
  "created_at": "2026-09-02T12:09:41Z",
  "unblocked_at": null,
  "cancelled_subscription_ids": ["sub_3Fk8pW2nQs6MzXc1"],
  "subscriptions_swept": true
}
```

| الحقل                        | الوصف                                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `identifier`                 | معرّف العميل أو البريد الإلكتروني الذي أرسلته.                                                                               |
| `source`                     | مصدر الحظر: `blocklist_page` أو `customer_page` أو `payment_page` أو `dispute_page` أو `api`. ويسجّل مفتاح API دائماً `api`. |
| `blocked_by_email`           | مستخدم لوحة التحكم الذي أضاف الحظر. وتكون القيمة `null` لمفتاح API.                                                          |
| `cancelled_subscription_ids` | الاشتراكات التي ألغتها هذه المكالمة.                                                                                         |
| `remaining_subscription_ids` | الاشتراكات التي لا تزال نشطة، بسبب فشل الإلغاء أو بلوغ المكالمة حد 25 عملية إلغاء.                                           |
| `subscriptions_swept`        | القيمة `false` عند بقاء اشتراكات نشطة. كرر المكالمة حتى تصبح `true`. يكون الحظر نفسه سارياً بالفعل.                          |

<Note>
  يُرجع حظر عميل محظور بالفعل HTTP `409` مع `CUSTOMER_ALREADY_BLOCKED`، ما لم تكن هناك اشتراكات لا تزال بانتظار الإلغاء. في هذه الحالة، تتابع المكالمة الإلغاء بدلاً من ذلك.
</Note>

### التحقق مما إذا كان العميل محظوراً

تُرجع [Get Customer Detail](/api-reference/customers/get-customers-1) حقلين إضافيين: `blocked_at`، وهو وقت إضافة الحظر النشط (`null` عندما لا يكون العميل محظوراً)، و`blocklist_entry_id`، وهو الإدخال المرتبط به. وتترك نقطة النهاية [List Customers](/api-reference/customers/get-customers) كلا الحقلين فارغين.

### إلغاء حظر عميل

<CodeGroup>
  ```typescript Node.js theme={null}
  await client.blocklist.customers.delete('bcu_7Hq2mV9kRt4LxYw3Pz');
  ```

  ```python Python theme={null}
  client.blocklist.customers.delete("bcu_7Hq2mV9kRt4LxYw3Pz")
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://live.dodopayments.com/blocklist/customers/bcu_7Hq2mV9kRt4LxYw3Pz \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
  ```
</CodeGroup>

تُرجع نقطة النهاية HTTP `204` عند النجاح. يؤدي إلغاء الحظر إلى استعادة عمليات الكتابة في إتمام الدفع والبوابة، ولا يعيد تفعيل أي اشتراك.

## أفضل الممارسات

* **سجّل السبب.** يمنح السبب المختصر للحظر، إلى جانب الملاحظات المتعلقة بأي أحداث لاحقة، فريق الدعم لديك الصورة الكاملة دون مغادرة لوحة التحكم.
* **احظر بعد عملية رد المدفوعات.** افتح العميل من النزاع أو الدفعة واحظره من هناك، أو أتمت ذلك من webhook `dispute.opened` باستخدام `POST /blocklist/customers`. راجع [النزاعات](/features/transactions/disputes).
* **تحقق من `subscriptions_swept`.** عند الحظر عبر API، كرر المكالمة حتى تُبلغ الاستجابة عن `true`، حتى لا يبقى أي اشتراك نشط.
* **أجرِ رد الأموال بشكل منفصل.** يوقف الحظر عمليات الشراء المستقبلية فقط. إذا كنت مديناً للعميل بمبلغ، فردّ الدفعة كالمعتاد.
* **راجع القائمة.** ألغِ حظر العملاء الذين حُلّت مشكلتهم. إلغاء الحظر فوري ويحافظ على السجل.

## ذات صلة

<CardGroup cols={2}>
  <Card title="Customer Management" icon="user-group" href="/features/customers">
    ابحث عن عميل، وافتح صفحة تفاصيله، وأدر اشتراكاته.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    ما يستطيع العميل المحظور فعله وما لا يستطيع فعله في البوابة.
  </Card>

  <Card title="Disputes" icon="circle-exclamation" href="/features/transactions/disputes">
    استجب لعمليات رد المدفوعات وقرر متى يكون الحظر مبرراً.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    ما المقصود بالقيمتين `PAYMENT_NOT_PERMITTED` و`PORTAL_ACTION_NOT_PERMITTED`.
  </Card>
</CardGroup>