# الطلبات والاستجابات

القواعد التي تنطبق على كل النقاط، لتبقى كل صفحة في المرجع مختصرة.

## الطلبات {#requests}

- الرابط الأساسي: `https://api.saei.automize.sa/v1`، عبر HTTPS فقط.
- الأجسام بصيغة JSON مع `Content-Type: application/json`. الجسم غير الصالح يُرفض بـ `invalid_json` ولا يُقرأ كأنه فارغ. الاستثناء الوحيد رفع الملفات ([`POST /media`](/docs/reference/media#uploadMedia)) ويُرسل بصيغة `multipart/form-data`.
- تعود أرقام الهواتف بصيغة E.164 مثل `+966501234567`، ويمكنك إرسالها أيضًا بصيغة `00966…` أو `966…` أو الصيغة المحلية `05…` (انظر [العربية والسوق السعودي](/docs/saudi#phones)). النصوص العربية والرموز التعبيرية تُرسل كما هي (UTF-8).
- عوامل تصفية القوائم معاملات في الرابط، والقيم المنطقية `true` أو `false`.

## المعرّفات {#ids}

لكل عنصر معرّف يبدأ بنوعه، فيدل سطر السجل على ما يشير إليه، ويُرد على المعرّف من نوع خاطئ بخطأ 404 واضح:

| البادئة | العنصر | البادئة | العنصر |
|---|---|---|---|
| `msg_` | رسالة أرسلتها | `ct_` | جهة اتصال |
| `imsg_` | رسالة واتساب من عميل | `tag_` | وسم |
| `cmsg_` | رسالة مستلم في حملة | `fld_` | حقل مخصص |
| `msg_test_` | رسالة وضع الاختبار | `conv_` | محادثة |
| `num_` | رقم واتساب | `usr_` | عضو في الفريق |
| `tpl_` | قالب | `cmp_` | حملة |
| `med_` | ملف مرفوع | `flow_` و`run_` | تدفق وتشغيل تدفق |
| `fres_` | رد على نموذج واتساب | `we_` و`del_` | نقطة استقبال وعملية إرسال |
| `evt_` | حدث | `req_` | طلب |

عامل المعرّفات **كنصوص معتمة** حتى 64 حرفًا: لا تحللها ولا تفترض أنها أرقام.

## الأخطاء {#errors}

لكل خطأ الشكل نفسه، ورمز HTTP يوافق قيمة `type`:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "window_closed",
    "message": "The 24-hour customer service window is closed. Send an approved template instead.",
    "param": "type",
    "doc_url": "https://app.saei.automize.sa/docs/errors#window_closed",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

اعتمد في منطقك على `code` لا على `message` (قد تتغير صياغة الرسائل). وعندما يكون الخطأ في أكثر من حقل يسرد `details` كل واحد منها. كل الرموز وطريقة إصلاحها في صفحة [الأخطاء](/docs/errors).

الرسائل بالإنجليزية. أرسل الترويسة `Accept-Language: ar` لتصلك رسائل التحقق من الحقول (`parameter_missing` و`parameter_invalid`) بالعربية، ويبقى `code` كما هو في الحالتين.

## معرّف الطلب {#request-id}

كل استجابة تحمل ترويسة `Request-Id` (وتكرره الأخطاء في `request_id`). سجّله: يستطيع الدعم الوصول إلى الطلب نفسه من خلاله، ويمكنك البحث عنه بنفسك في **المطورون ← السجلات**.

## تقسيم الصفحات {#pagination}

القوائم مرتبة من الأحدث وتُقسم بمؤشر:

```json
{ "object": "list", "data": [ ... ], "has_more": true, "next_cursor": "eyJpZCI6..." }
```

اطلب الصفحة التالية بـ `?cursor=<next_cursor>`، وحدد حجم الصفحة بـ `?limit=` (من 1 إلى 100، والافتراضي 25). المؤشر لا يتخطى عناصر ولا يكررها عند وصول عناصر جديدة.

## حدود الطلبات {#rate-limits}

لكل مفتاح عدد محدد من الطلبات في الدقيقة، وكل استجابة توضح موقعك:

| الترويسة | المعنى |
|---|---|
| `RateLimit-Limit` | عدد الطلبات المسموح في الفترة |
| `RateLimit-Remaining` | المتبقي في هذه الفترة |
| `RateLimit-Reset` | الثواني المتبقية حتى تبدأ فترة جديدة |

عند تجاوز الحد تصلك `429 rate_limited` مع `Retry-After` بالثواني. نظّم طلباتك بالاعتماد على الترويسات بدل إعادة المحاولة المتلاحقة.

## إعادة المحاولة والتكرار الآمن {#idempotency}

انتهاء المهلة يتركك لا تعرف إن كان طلب POST قد نُفذ. أرسل ترويسة `Idempotency-Key` (يُفضّل UUID) وستكون إعادة المحاولة آمنة دائمًا:

```bash
curl -X POST https://api.saei.automize.sa/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 4f6c1c1e-2d0a-4b53-9d4f-58a1c6e7b1aa" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966501234567", "type": "template", "template": { "name": "order_update", "language": "ar", "variables": { "body": ["سارة", "#10482"] } } }'
```

- نفس المفتاح ونفس الجسم: تصلك الاستجابة الأولى مرة أخرى مع `Idempotent-Replayed: true`، ولا يُرسل شيء مرتين.
- نفس المفتاح بجسم مختلف: `idempotency_key_reused`.
- تُحفظ المفاتيح 24 ساعة. الأخطاء من جهتنا (5xx و429) لا تُحفظ، فإعادة المحاولة تنفّذ الطلب من جديد.

أعد محاولة `429` و`5xx` مع زيادة الانتظار تدريجيًا، ولا تُعد محاولة بقية أخطاء `4xx` دون تعديل الطلب.