توثيق واجهة البرمجة

Edu4 Whatsapp Business API واجهة REST للشركات والمطورين لإرسال قوالب WhatsApp Business وإدارة حالة الحملات.

هذه الصفحة عامة ولا تتطلب تسجيل دخول. لا تضع أسرارًا في الأمثلة، واستخدم مفتاحًا حقيقيًا فقط من بيئتك الخاصة.

كيف تبدأ

1. اطلب من مسؤول المنصة إنشاء عميل واجهة وإصدار API Key.
2. ضع المفتاح في رأس Authorization فقط.
3. استدعِ GET /whatsapp/templates لمعرفة القوالب المسموحة لحسابك.
4. أرسل أول حملة عبر POST /whatsapp/bulk-send مع Idempotency-Key.
5. تابع الحالة عبر GET /whatsapp/bulk-status.
6. عالج الأخطاء وحدود الاستخدام، واستقبل Webhooks إن لزم.

المصادقة

تتم المصادقة حصريًا عبر رأس HTTP:

Authorization: Bearer {API_KEY}

مثال:

Authorization: Bearer edu4_live_xxxxxxxxx

• ضع المفتاح في رأس Authorization فقط.
• لا تضعه في عنوان URL أو في Query.
• لا تضعه في جسم الطلب (Request Body).
• لا تشاركه في البريد أو المستودعات أو لقطات الشاشة.
• المفتاح الكامل يظهر مرة واحدة عند إنشائه أو تدويره من لوحة التحكم حسب سياسة المنصة. بعد ذلك لا يمكن استرجاع القيمة الكاملة.
• بادئة المفاتيح الحية: edu4_live_

إرسال حملة رسائل

POST /api/v1/whatsapp/bulk-send

ينشئ حملة من نوع المصدر api ويضع الرسائل في الطابور ثم يعيد 202. لا يُستدعى Meta داخل نفس طلب HTTP.

المصادقة

مطلوبة: Authorization: Bearer.

الرؤوس

• Content-Type: application/json (إلزامي)
• Authorization: Bearer {API_KEY} (إلزامي)
• Idempotency-Key (موصى به بشدة)
• X-Request-Id (اختياري)

جسم الطلب

• template_name: اسم القالب.
• language: لغة القالب مثل ar_EG.
• messages: قائمة مستلمين. كل عنصر يحتوي phone وparameters لـ BODY.
• اختياري لكل رسالة: header وbuttons إذا كان تعريف القالب يتطلبهما.

الحد الأقصى للرسائل في الطلب الواحد حاليًا: 1000 (قابل للتخصيص لكل عميل، وبحد إعدادات المنصة).

الحد الأقصى لحجم JSON: 2 MiB.

مثال طلب

{
  "template_name": "student_absence_today",
  "language": "ar_EG",
  "messages": [
    {
      "phone": "201001234567",
      "parameters": [
        "محمد علي",
        "2026-08-17"
      ]
    }
  ]
}

مثال استجابة 202

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

bulk_id هو المعرّف العام للحملة ويبدأ بـ cmp_ ثم 32 محرفًا سداسيًا. لا يُستخدم الرقم الداخلي لقاعدة البيانات.

رموز الحالة الشائعة

202 نجاح الطابور. 400 JSON أو نوع المحتوى. 401 مصادقة. 403 قالب غير مسموح. 409 تعارض المفتاح. 413 حجم كبير. 422 تحقق. 429 حد المعدل. 503 المزوّد غير جاهز.

حالة الحملة

GET /api/v1/whatsapp/bulk-status?bulk_id={bulk_id}

bulk_id هو المعرّف الذي أُرجع عند الإرسال. الحملة يجب أن تخص نفس العميل المصادق. خلاف ذلك تكون الاستجابة 404 CAMPAIGN_NOT_FOUND.

الحقول المعادة:

• bulk_id
• status حالة الحملة
• total_messages عدد الرسائل
• queued / processing / sent / delivered / read / failed
• created_at / started_at / completed_at

هذا المسار لا يعيد أرقام الهواتف.

مثال استجابة

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "processing",
        "total_messages": 3,
        "queued": 1,
        "processing": 0,
        "sent": 1,
        "delivered": 1,
        "read": 0,
        "failed": 0,
        "created_at": "2026-08-17 08:00:00",
        "started_at": "2026-08-17 08:00:02",
        "completed_at": null
    }
}

حالات الحملة

عدادات الرسائل

قائمة القوالب

GET /api/v1/whatsapp/templates

يعيد القوالب المعيَّنة للعميل المصادق فقط. لا يعيد قوالب عملاء آخرين، ولا معرّفات داخلية، ولا أسرار المزوّد، ولا JSON المكوّنات الكامل.

الحقول: name، language، status، category، parameter_counts لـ body/header/buttons.

لمعرفة القوالب المسموح لك استخدامها: استدعِ هذا المسار. إن لم يظهر القالب في القائمة فستحصل عند الإرسال على TEMPLATE_NOT_ALLOWED.

مثال استجابة

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "templates": [
            {
                "name": "student_absence_today",
                "language": "ar_EG",
                "status": "APPROVED",
                "category": "UTILITY",
                "parameter_counts": {
                    "body": 2,
                    "header": 0,
                    "buttons": 0
                }
            }
        ]
    }
}

القوالب بالتفصيل

التعريفات التالية مأخوذة من النسخة المخزّنة في النظام للغة ar_EG. عدد القوالب الموثّقة من التعريف الكامل: 13 من 13.

• student_payment_received
• student_absence_today
• parent_student_payment_received
• parent_student_payment_due
• parent_student_exam_result
• parent_student_absence_two
• parent_student_absence_multiple
• employee_tasks
• employee_salary_details
• employee_salary_deduction
• employee_bonus
• employee_absence_one_day
• employee_absence_multiple_days

مرحبًا {{1}}، تم تأكيد سداد مصروفات الشهر {{2}} بنجاح. نتمنى لك التوفيق في دراستك.

{
    "template_name": "student_payment_received",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "يناير"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

مرحبًا {{1}}، لاحظنا غيابك عن حصة اليوم بتاريخ {{2}}. نرجو متابعة الدروس بانتظام.

{
    "template_name": "student_absence_today",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "2026-08-17"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة ولي الأمر، تم استلام مصروفات الشهر {{1}} الخاصة بالطالب {{2}} بنجاح. شكرًا لتعاونكم.

{
    "template_name": "parent_student_payment_received",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "يناير",
                "محمد علي"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة ولي الأمر، نذكركم أن مصروفات الشهر {{1}} الخاصة بالطالب {{2}} لم يتم سدادها حتى الآن. يرجى السداد في أقرب وقت.

{
    "template_name": "parent_student_payment_due",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "يناير",
                "محمد علي"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة ولي الأمر، نود إبلاغكم بأن الطالب {{1}} حصل على درجة {{2}} في اختبار {{3}} بتاريخ {{4}} شكراً لكم

{
    "template_name": "parent_student_exam_result",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "18/20",
                "الرياضيات",
                "2026-08-17"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة ولي الأمر، نود إعلامكم أن الطالب {{1}} قد تغيب بتاريخ {{2}} عن حصتين متتاليتين برجاء المتابعة.

{
    "template_name": "parent_student_absence_two",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "2026-08-17"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة ولي الأمر، الطالب {{1}} قد تغيب عن {{2}} حصص حتى تاريخ {{3}}. نرجو التعاون لتفادي تكرار الغياب.

{
    "template_name": "parent_student_absence_multiple",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "3",
                "2026-08-17"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة {{1}}، هذه هي مهام عملكم ليوم {{2}} هي {{3}} شكرا لكم علي مجهودكم

{
    "template_name": "employee_tasks",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "2026-08-17",
                "مراجعة ملفات اليوم"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة {{1}}، تفاصيل راتبكم لشهر {{2}} كالتالي:
*الراتب*: {{3}}
*الحوافز*: {{4}}
*التأمينيات*: {{5}}
*إجمالي خصم الغياب*:  {{6}}
*جزاءات*: {{7}}
*تأخيرات*: {{8}}
*سلف*: {{9}}
*إضافات*: {{10}}
*الراتب النهائي: {{11}}*
شكرا لكم علي مجهودكم و نتمني لكم دوام التفوق.

{
    "template_name": "employee_salary_details",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "يناير",
                "5000",
                "200",
                "100",
                "50",
                "0",
                "25",
                "100",
                "150",
                "5175"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة {{1}}، تم تطبيق خصم قدره {{2}} على راتب شهر {{3}} بسبب {{4}} إذا كنت تعتقد بأنه هناك مشكله تواصل مع الإدارة.

{
    "template_name": "employee_salary_deduction",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "1500",
                "يناير",
                "1500"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة {{1}}، تمت إضافة مكافأة قدرها {{2}} إلى راتب شهر {{3}} تقديرًا لجهودكم.

{
    "template_name": "employee_bonus",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "1500",
                "يناير"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة {{1}}، تم تسجيل غيابكم عن العمل بتاريخ {{2}}. برجاء التواصل مع الإدارة إذا كان هناك عذر رسمي.

{
    "template_name": "employee_absence_one_day",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "2026-08-17"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

السيد/السيدة {{1}}، تم تسجيل غيابكم لعدد {{2}} أيام متتالية حتى تاريخ {{3}}. يرجى التواصل مع الإدارة بشكل عاجل.

{
    "template_name": "employee_absence_multiple_days",
    "language": "ar_EG",
    "messages": [
        {
            "phone": "201001234567",
            "parameters": [
                "محمد علي",
                "3",
                "2026-08-17"
            ]
        }
    ]
}

{
    "success": true,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "data": {
        "bulk_id": "cmp_0123456789abcdef0123456789abcdef",
        "status": "queued",
        "total_messages": 1
    }
}

حدود الاستخدام

القيم التالية هي الإعدادات الحالية للمنصة. يمكن تخصيص حدود العميل من لوحة التحكم، وتُطبَّق الحدود الفعلية للعميل المصادق عند كل طلب.

عند التجاوز: 429 RATE_LIMIT_EXCEEDED.

• Retry-After: ثوانٍ حتى نهاية الساعة الحالية.
• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset: ختم Unix لنهاية النافذة.

Idempotency

الرأس: Idempotency-Key

• يمنع إنشاء حملتين لنفس الطلب عند إعادة الإرسال بسبب انقطاع الشبكة أو مهلة العميل.
• نفس العميل + نفس المفتاح + نفس جسم الطلب يعيد الاستجابة الأصلية للحملة، مع رأس Idempotent-Replay: true عند إعادة التشغيل.
• نفس المفتاح مع جسم مختلف يعيد 409 IDEMPOTENCY_CONFLICT.
• طول المفتاح حتى 191 محرفًا. المفتاح الفارغ أو الأطول غير صالح.
• مدة صلاحية المفتاح الحالية: 24 ساعة (قابلة للإعداد في المنصة، بحد أقصى 168 ساعة).

معرّف الطلب

كل استجابة JSON تتضمن request_id، ويُعاد أيضًا في رأس X-Request-Id.

• يمكنك إرسال X-Request-Id من طرفك إن طابق النمط المسموح؛ وإلا تُنشئ المنصة معرّفًا يبدأ بـ req_.
• استخدمه لتتبع الطلب عند التواصل مع الدعم الفني.
• لا يحتوي على أسرار.

Webhooks

تدعم المنصة إرسال أحداث إلى خادم شركتك عند تغيّر حالة الرسائل والحملات.

إعداد العنوان

عنوان الاستقبال والسر يُضبطان من لوحة التحكم بواسطة المسؤول في الإصدار الحالي. يمكنك قراءة الإعداد (دون السر) عبر:

GET /api/v1/whatsapp/webhook

التوقيع

الطلبات تُوقَّع بـ HMAC-SHA256:

signed_payload = timestamp + "." + raw_body
X-Webhook-Signature: sha256={hex}

• X-Webhook-Timestamp: وقت Unix للتوقيع. ارفض الطلب خارج نافذة إعادة التشغيل الحالية (300 ثانية افتراضيًا).
• X-Webhook-Event-Id: معرّف الحدث. عالج كل id مرة واحدة.
• السر لا يُعاد عبر الواجهة.

إعادة المحاولة

عدد المحاولات الافتراضي 5. مهلة الطلب 8 ثوانٍ. التراجع بالثواني: 1,1,1,1,1. استجب بـ 2xx بسرعة. الترتيب غير مضمون.

الأحداث

• message.sent — قَبِل المزوّد الرسالة
• message.delivered — تم التسليم
• message.read — تمّت القراءة
• message.failed — فشلَت الرسالة
• campaign.queued — أُنشئت حملة عبر الواجهة
• campaign.processing — بدأت معالجة الحملة
• campaign.completed — اكتملت الحملة بنجاح
• campaign.partially_completed — اكتملت الحملة جزئيًا
• campaign.failed — فشلَت الحملة
• campaign.cancelled — أُلغيت الحملة
• webhook.test — حدث اختبار يرسله المسؤول فقط

تفاصيل التشغيل للمسؤول موجودة في توثيق المنصة الداخلي للويب هوك، وهذه الصفحة تغطي ما يحتاجه المطوّر الخارجي للتحقق والمعالجة.

أخطاء API

شكل الخطأ الموحّد:

{
    "success": false,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "error": {
        "code": "INVALID_PHONE",
        "message": "One or more phone numbers are invalid.",
        "details": [
            {
                "index": 0,
                "phone": "invalid"
            }
        ]
    }
}

رموز HTTP

أمثلة cURL

استبدل المفتاح الوهمي بمفتاحك. لا تضع مفتاحًا حقيقيًا في التوثيق أو المستودعات.

إرسال حملة

curl -sS -X POST 'https://whatsapp.alnwabgh.com/api/v1/whatsapp/bulk-send' \
  -H 'Authorization: Bearer edu4_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: bulk-send-example-001' \
  -d '{
    "template_name": "student_absence_today",
    "language": "ar_EG",
    "messages": [
      {"phone": "201001234567", "parameters": ["محمد علي", "2026-08-17"]}
    ]
  }'

حالة الحملة

curl -sS 'https://whatsapp.alnwabgh.com/api/v1/whatsapp/bulk-status?bulk_id=cmp_0123456789abcdef0123456789abcdef' \
  -H 'Authorization: Bearer edu4_live_xxxxxxxxx'

القوالب

curl -sS 'https://whatsapp.alnwabgh.com/api/v1/whatsapp/templates' \
  -H 'Authorization: Bearer edu4_live_xxxxxxxxx'