# الحملات

أرسل قالبًا معتمدًا إلى جمهور وتابع النتائج.

ترسل الحملة قالبًا معتمدًا واحدًا إلى جهات اتصال كثيرة، بوتيرة تحمي رقمك، وتجمع لك نتائجها. استخدمها للإعلانات والعروض، أما الرسالة الواحدة التي يطلقها نظامك (تحديث طلب مثلًا) فأرسلها مباشرة عبر [`POST /messages`](/docs/reference/messages#sendMessage).

## 1. أنشئ مسودة {#create}

يبني [`POST /campaigns`](/docs/reference/campaigns#createCampaign) قائمة المستلمين ويسعّرها، ولا يُرسل شيء بعد.

```json
{
  "name": "عرض نهاية الأسبوع",
  "template": { "name": "weekend_offer", "language": "ar" },
  "audience": { "tags": ["عملاء VIP"] },
  "variables": { "body": ["{{first_name}}", "20٪"] },
  "scheduled_at": "2026-10-02T16:00:00",
  "timezone": "Asia/Riyadh"
}
```

- **الجمهور.** `contacts` (معرّفات)، أو `tags` (معرّفات أو أسماء)، أو `"all_contacts": true`.
- **القيم الشخصية.** في `variables` تُعبَّأ `{{first_name}}` و`{{last_name}}` و`{{phone_number}}` أو أي مفتاح حقل مخصص لكل مستلم.
- **الجدولة.** `scheduled_at` وقت محلي يُقرأ حسب `timezone`. اتركه لتُرسل فور البدء.
- **الأرقام.** إن كان لديك أكثر من رقم واتساب فحدد رقم الإرسال بـ `number_id`، ويجب أن يعود القالب لحساب هذا الرقم.

## 2. أجب عن سؤال الموافقة {#consent}

إن كان بعض المستلمين قد ألغوا اشتراكهم في رسائل الأعمال فالرد هو [`recipient_not_consented`](/docs/errors#recipient_not_consented) مع الأعداد:

```json
{ "error": { "code": "recipient_not_consented", "unconsented": 12, "recipients": 348, "param": "consent_confirmed", "...": "..." } }
```

أعد الطلب مع `"consent_confirmed": false` لاستبعادهم، أو `true` فقط إن وافقوا من جديد. تُسجَّل إجابتك في سجل التدقيق.

## 3. راجع التكلفة ثم ابدأ {#start}

تحمل المسودة `estimated_cost`: ما سيحتسبه واتساب بالريال بأسعار اليوم، مع عدد المستلمين المسعّرين والمجانيين وغير المسعّرين. حين تبدو مناسبة استدعِ [`POST /campaigns/{id}/start`](/docs/reference/campaigns#startCampaign).

يُجري البدء الفحوص نفسها التي تجريها المنصة: يجب أن يستطيع الرقم البث (الرقم الذي قيّده Meta لا يستطيع)، وألا يوقف Meta التسليم لسبب يتعلق بالفوترة، وأن يغطي رصيد الباقة الشهري من الحملات والرسائل التسويقية الإرسال (وإلا فالخطأ [`quota_exceeded`](/docs/errors#quota_exceeded)).

## 4. تابع النتائج {#results}

- يعطي [`GET /campaigns/{id}`](/docs/reference/campaigns#getCampaign) الإحصاءات `stats` لحظيًا: المرسلة والمسلّمة والمقروءة والفاشلة والتي رُدّ عليها والنسب.
- يعرض [`GET /campaigns/{id}/messages`](/docs/reference/campaigns#listCampaignMessages) رسالة كل مستلم مع حالتها، وسبب واتساب عند الفشل.
- الأحداث: `campaign.started` و`campaign.completed`، و`message.*` لكل مستلم (تبدأ المعرّفات بـ `cmsg_`).

## الإيقاف المؤقت والاستئناف والإلغاء {#control}

يتم الإرسال بوتيرة محسوبة. إن اصطدم الرقم بحد وضعه Meta تُوقف الحملة مؤقتًا (`status: paused`، ويوضح `hold_reason` السبب) ويصلك `campaign.paused`. أصلح السبب ثم استدعِ [`POST /campaigns/{id}/resume`](/docs/reference/campaigns#resumeCampaign): لا تُستأنف الحملة المتوقفة من تلقاء نفسها، لأن الرقم العائد من قيد يجب ألا يبدأ البث دون متابعة.

يوقف [`POST /campaigns/{id}/cancel`](/docs/reference/campaigns#cancelCampaign) حملة مجدولة أو قيد الإرسال، وتبقى الرسائل المرسلة كما هي.

## عرض الحملات

```
GET https://api.saei.automize.sa/v1/campaigns
```



- الصلاحية: campaigns:read
- لمفاتيح التشغيل فقط

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `status` (query): 

### الاستجابة 200

صفحة من الحملات.

```json
{
  "object": "list",
  "data": [
    {
      "id": "cmp_64",
      "object": "campaign",
      "name": "string",
      "description": "string",
      "status": "draft",
      "hold_reason": "string",
      "template": {
        "id": "string",
        "name": "string",
        "language": "string"
      },
      "number_id": "string",
      "scheduled_at": "2026-10-01T09:30:00Z",
      "timezone": "string",
      "stats": {
        "recipients": 0,
        "pending": 0,
        "sent": 0,
        "delivered": 0,
        "read": 0,
        "failed": 0,
        "replied": 0,
        "delivery_rate": 0,
        "read_rate": 0,
        "reply_rate": 0
      },
      "estimated_cost": {
        "currency": "string",
        "total": 0,
        "total_usd": 0,
        "recipients_priced": 0,
        "recipients_free": 0,
        "recipients_unpriced": 0
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`parameter_invalid`, `test_mode_unsupported`, `rate_limited`

## إنشاء حملة

```
POST https://api.saei.automize.sa/v1/campaigns
```

ينشئ **مسودة**: لا يُرسل شيء حتى تستدعي `POST /v1/campaigns/{id}/start`. يحمل الرد `estimated_cost`، أي التكلفة التي سيحتسبها واتساب بأسعار اليوم، لتؤكد قبل الإرسال.

- **الجمهور**: `contacts` (معرّفات)، أو `tags` (معرّفات أو أسماء)، أو `all_contacts: true`.
- **المتغيرات**: قيم القالب، حيث تُعبَّأ `{{first_name}}` و`{{last_name}}` و`{{phone_number}}` أو أي مفتاح حقل مخصص لكل مستلم، مثل `"body": ["{{first_name}}", "20%"]`.
- **الموافقة**: إن كان بعض المستلمين قد ألغوا اشتراكهم في رسائل الأعمال فالرد هو `recipient_not_consented` مع الأعداد. أرسل `consent_confirmed: false` لتخطيهم، أو `true` فقط إن وافقوا من جديد (يُسجَّل تأكيدك في سجل التدقيق).

كل فحوص منشئ الحملات تنطبق هنا أيضًا: الرقم الذي قيّده Meta لا يستطيع البث، ويجب أن يعود القالب لرقم الإرسال، وتُطبق حدود الباقة الشهرية للحملات والرسائل التسويقية عند البدء.


- الصلاحية: campaigns:write
- لمفاتيح التشغيل فقط
- يقبل Idempotency-Key

### المعاملات

- `Idempotency-Key` (header): أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

### الطلب

```json
{
  "name": "عرض نهاية الأسبوع",
  "template": {
    "name": "weekend_offer",
    "language": "ar"
  },
  "number_id": "num_3",
  "audience": {
    "tags": [
      "عملاء VIP"
    ]
  },
  "variables": {
    "body": [
      "20٪"
    ]
  },
  "scheduled_at": "2026-10-02T16:00:00",
  "timezone": "Asia/Riyadh"
}
```

### الاستجابة 201

المسودة مع تقدير تكلفتها.

```json
{
  "id": "cmp_64",
  "object": "campaign",
  "name": "عرض نهاية الأسبوع",
  "description": null,
  "status": "draft",
  "hold_reason": null,
  "template": {
    "id": "tpl_31",
    "name": "weekend_offer",
    "language": "ar"
  },
  "number_id": "num_3",
  "scheduled_at": "2026-10-02T13:00:00Z",
  "timezone": "Asia/Riyadh",
  "stats": {
    "recipients": 348,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0
  },
  "estimated_cost": {
    "currency": "SAR",
    "total": 61.25,
    "total_usd": 16.33,
    "recipients_priced": 348,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T10:00:00Z",
  "updated_at": "2026-10-01T10:00:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

بعض المستلمين لم يوافقوا، فأجب بـ `consent_confirmed`.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`parameter_missing`, `parameter_invalid`, `resource_missing`, `template_not_found`, `template_not_approved`, `template_variables_mismatch`, `recipient_not_consented`, `sender_not_sendable`, `test_mode_unsupported`, `rate_limited`

## جلب حملة

```
GET https://api.saei.automize.sa/v1/campaigns/{id}
```

الحملة مع نتائجها لحظيًا (أُرسلت، سُلّمت، قُرئت، فشلت، رُدّ عليها، والنسب).

- الصلاحية: campaigns:read
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

الحملة.

```json
{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `test_mode_unsupported`, `rate_limited`

## إلغاء حملة

```
POST https://api.saei.automize.sa/v1/campaigns/{id}/cancel
```

يوقف حملة مجدولة أو قيد الإرسال. تبقى الرسائل المرسلة كما هي، وتُلغى البقية.

- الصلاحية: campaigns:write
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

أُلغيت.

```json
{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

الحملة ليست مجدولة ولا قيد الإرسال.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `state_conflict`, `test_mode_unsupported`, `rate_limited`

## عرض مستلمي حملة

```
GET https://api.saei.automize.sa/v1/campaigns/{id}/messages
```

رسالة `message` لكل مستلم (`cmsg_…`) مع حالة التسليم، وسبب واتساب عند الفشل. تصلك تغيّرات حالتها أيضًا كأحداث `message.*`.

- الصلاحية: campaigns:read
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.
- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `status` (query): 

### الاستجابة 200

صفحة من رسائل المستلمين.

```json
{
  "object": "list",
  "data": [
    {
      "id": "msg_48213",
      "object": "message",
      "livemode": false,
      "direction": "outbound",
      "channel": "whatsapp",
      "from": "+966112345678",
      "to": "+966501234567",
      "type": "text",
      "text": {
        "body": "string"
      },
      "template": {
        "name": "string",
        "language": "string",
        "variables": {},
        "body": "string"
      },
      "image": {},
      "video": {},
      "audio": {},
      "document": {},
      "sticker": {},
      "location": {},
      "contacts": [],
      "interactive": {},
      "reaction": {},
      "status": "accepted",
      "error": {
        "code": "string",
        "title": "string",
        "message": "string"
      },
      "reference": "string",
      "conversation_id": "string",
      "provider_message_id": "string",
      "contact": {
        "name": "string"
      },
      "context": {
        "provider_message_id": "string"
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `parameter_invalid`, `test_mode_unsupported`, `rate_limited`

## استئناف حملة متوقفة

```
POST https://api.saei.automize.sa/v1/campaigns/{id}/resume
```

يعيد حملة متوقفة إلى الإرسال بعد إصلاح السبب. لا يحدث إلا بطلب صريح وليس تلقائيًا (إلا بعد إيقاف شامل للمنصة)، لأن الرقم العائد من قيد يجب ألا يبدأ البث دون متابعة. يُرفض ما دام الرقم لا يستطيع البث.

- الصلاحية: campaigns:write
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

عادت للإرسال.

```json
{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

الحملة ليست متوقفة.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `state_conflict`, `sender_not_sendable`, `test_mode_unsupported`, `rate_limited`

## بدء حملة

```
POST https://api.saei.automize.sa/v1/campaigns/{id}/start
```

يرسل المسودة الآن، أو في موعد `scheduled_at`. يتم الإرسال بوتيرة تحمي تقييم جودة الرقم، وتابع التقدم بأحداث `campaign.*` و`GET /v1/campaigns/{id}`.

- الصلاحية: campaigns:write
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

بدأت (`in_progress`) أو جُدولت (`scheduled`).

```json
{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 402

استُهلك رصيد الباقة الشهري من الحملات أو الرسائل التسويقية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

بدأت بالفعل.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `state_conflict`, `sender_not_sendable`, `sender_not_configured`, `quota_exceeded`, `channel_error`, `test_mode_unsupported`, `rate_limited`