# إلغاء

`POST` `https://api.pushwoosh.com/messaging/v2/cancel`

إلغاء رسالة تم إنشاؤها مسبقًا، يتم تحديدها بواسطة `message_code` الخاص بها. الإلغاء متاح فقط عندما تكون الرسالة في إحدى هذه الحالات:

- **pending:** تم إنشاؤها ولكن لم يتم التقاطها بعد للإرسال.
- **waiting:** مجدولة لوقت إرسال مستقبلي.
- **processing:** يتم حاليًا إعدادها للتسليم.

<Aside type="caution" title="هام">

- إذا كانت الرسالة في حالة `processing`، فإن الإلغاء يوقف فقط عمليات التسليم التي لم تخرج بعد. أي شخص استلم الرسالة بالفعل قد لا يزال يمتلكها.

- إذا تم إلغاء الرسالة بالفعل أو انتهى إرسالها، فإن واجهة برمجة التطبيقات (API) تُرجع `400`. هذا الاستدعاء ليس متساوي الفعالية. تحقق من حالة الرسالة قبل إعادة المحاولة.
</Aside>

للتحقق مما إذا كانت الرسالة لا تزال في حالة قابلة للإلغاء، راجع [التحقق من حالة الرسالة](#checking-message-status).


## الطلب

المصادقة باستخدام [رمز Server API token](/ar/developer/api-reference/api-access-token/#server-api-token) الخاص بك في ترويسة `Authorization: Token <API_TOKEN>`.

| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
| `message_code` | string | نعم | [رمز الرسالة (Message code)](/ar/developer/api-reference/api-identifiers/#message-code) للرسالة المراد إلغاؤها، كما تم إرجاعه بواسطة [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/) في `result.message_code`. |

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

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/cancel \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX"
  }'
```

## الاستجابة

عند النجاح، تُرجع HTTP 200 مع نص JSON فارغ.

```json
{}
```

## الأخطاء

تستخدم الأخطاء مغلف الخطأ القياسي لـ gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`.

| حالة HTTP | الشرط |
|---|---|
| `400` | `message_code` مفقود. |
| `400` | الرسالة ليست في حالة قابلة للإلغاء (لم تعد `pending` أو `waiting` أو `processing`). |
| `403` | الرسالة تنتمي إلى حساب آخر. |
| `404` | لا توجد رسالة لـ `message_code` المحدد. |
| `500` | حدث خطأ داخلي أثناء تحميل الرسالة أو نشر الإلغاء. أعد محاولة الطلب. |


**مثال**

إلغاء رسالة لم تعد موجودة يُرجع HTTP `404`:

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## التحقق من حالة الرسالة

قبل الإلغاء، يمكنك التحقق مما إذا كانت الرسالة لا تزال في حالة قابلة للإلغاء. بالإضافة إلى قراءة عمود **الحالة (Status)** في جدول الرسائل في لوحة التحكم ([**الحملات ← الرسائل لمرة واحدة**](/ar/product/statistics-and-analytics/message-history/))، يمكنك الاستعلام عن الحالة برمجيًا باستخدام [`messages:list`](/ar/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- مرر `message_code` في مصفوفة `filters.messages_codes` (إلى جانب `filters.application` المطلوب).
- اقرأ حقل `status` للإدخال المطابق في `items[]`.

<Aside type="note">
`messages:list` هو جزء من واجهة برمجة تطبيقات الإحصائيات (Statistics API) ويستخدم ترويسة مصادقة مختلفة عن نقطة النهاية هذه: `Authorization: Api <Server Key>`.
</Aside>

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

<CardGrid>
  <LinkCard title="إعلام" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="تحديث" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="إحصائيات الرسائل" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="نظرة عامة على Messaging API v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="الترحيل من v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>