التوثيق التقني وواجهة برمجة التطبيقات
Production Base URL: https://connect-dashboard.ezycode.dev/connect/v1
المصادقة والمفاتيح البرمجية
تتم جميع طلبات Public API عبر بروتوكول HTTPS باستخدام ترويسة Authorization: Bearer sk_live_.... كل مفتاح برمجي يرتبط بمشروع محدد وتُحدد له صلاحيات دقيقة (إرسال الرسائل، القراءة، استعلام المستلمين).
إرسال رسائل التحقق (OTP)
يتم الإرسال عبر استدعاء POST /connect/v1/messages مع تحديد رقم المستلم بالصيغة الدولية (+20...). نوصي دائمًا بإرسال ترويسة Idempotency-Key لمنع تكرار خصم الرسالة عند حدوث انقطاع في الشبكة.
قواعد وحدود البيئة التجريبية (Sandbox)
تعمل بيئة الاختبار على WhatsApp Cloud API الرسمي التابع لـ Meta وتتسع لـ 5 مستلمين كحد أقصى يتم اعتمادهم عبر لوحة التحكم. الرسائل المسموحة تشمل قوالب التحقق المعتمدة والنصوص التجريبية.
متابعة وتتبع حالة الرسائل
يمكن الاستعلام عن حالة الرسالة في أي وقت عبر GET /connect/v1/messages/{id}. تتدرج الحالات من: queued → sent → delivered → read، أو failed في حال تعذر الوصول للمستلم.
استقبال إشعارات الـ Webhooks والتوقيع الرقمي
ترسل المنصة أحداث التسليم لحظيًا إلى رابط الـ Webhook الخاص بك مع توقيع HMAC-SHA256 داخل ترويسة X-EzyCode-Signature. يجب التحقق من التوقيع على نص الطلب الخام والرد برمز 200 خلال 10 ثوانٍ.
curl -X POST https://connect-dashboard.ezycode.dev/connect/v1/messages \
-H "Authorization: Bearer $EZYCODE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: auth-otp-9821" \
-d '{
"to": "+201000000000",
"type": "text",
"text": "رمز التحقق الخاص بك هو: 849201"
}'أكواد الاستجابة ومعالجة الأخطاء
| رمز الخطأ | السبب المحتمل | طريقة الحل |
|---|---|---|
| 401 Unauthorized | مفتاح الـ API مفقود أو غير صالح. | تأكد من تمرير Authorization: Bearer sk_live_... |
| 403 Forbidden | الرقم غير مسجل ضمن المستلمين المعتمدين في البيئة التجريبية. | أضف الرقم في لوحة التحكم وتأكد من توثيقه (حد أقصى 5 أرقام). |
| 422 Unprocessable | صيغة رقم الهاتف غير صحيحة أو البيانات ناقصة. | استخدم الصيغة الدولية E.164 (مثال: +201000000000). |
| 429 Rate Limited | تجاوزت الحد المسموح للطلبات بالدقيقة. | انتظر دقيقة أو استخدم طابور إرسال (Queue / Retry with Backoff). |
أدلة التكامل والشروحات المتخصصة
شروحات برمجية مفصلة خطوة بخطوة للربط مع أطر العمل المختلفة واستقبال الأحداث الفورية:
ربط Laravel وإرسال OTP
كلاس Service متكامل، إعدادات .env، واستقبال الـ Webhooks
ربط PHP المباشر (cURL & Guzzle)
أكواد خفيفة بدون أطر عمل مع معالجة الأخطاء والتحقق
ربط Flutter لتطبيقات الموبايل
شاشة إدخال OTP، اتصال HTTP، وأفضل الممارسات الأمنية
تكامل الويب هوك Webhooks
التحقق من توقيع HMAC-SHA256 وسياسات إعادة المحاولة
أمان المفاتيح: لا تُعاد مفاتيح API الخاصة بالمنصة في أي استجابة برمجية، وتُعرض لك مرة واحدة فقط عند الإنشاء في لوحة التحكم. احتفظ بها في بيئة آمنة ولا تشاركها في الأكواد العامة.