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

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

الطلبات#

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

المعرّفات#

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

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

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

الأخطاء#

لكل خطأ الشكل نفسه، ورمز 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 كل واحد منها. كل الرموز وطريقة إصلاحها في صفحة الأخطاء.

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

معرّف الطلب#

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

تقسيم الصفحات#

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

JSON

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

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

حدود الطلبات#

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

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

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

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

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

Shell

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 دون تعديل الطلب.