دليل المطورين: التكامل مع Daffaa API و Webhooks لتأكيد المدفوعات تلقائياً
14 أغسطس 2026 · 1 دقيقة قراءة · 154 مشاهدات
مقدمة: ليه تربط متجرك بـ Daffaa برمجياً؟
لو عندك متجر أونلاين أو بتبيع خدمات SMM وبتستقبل فلوس على فودافون كاش أو InstaPay، أكيد واجهت المشكلة الأكبر: العميل يبعت الفلوس، وانت لازم تفتح رسايل الموبايل بإيدك وتأكد الدفعة وتشحن المحفظة أو الرصيد على البانل. ده بياكل وقت، بيغلط، وبيخلي العميل يستنى. Daffaa API بيحل الموضوع ده نهائياً: بمجرد ما رسالة الدفع توصل، Daffaa يقرأها ويتحقق منها ويبعتلك Webhook فوري تشحن بيه العميل تلقائياً — بدون أي تدخل يدوي.
المقال ده دليل عملي للمطورين (سواء انت اللي بتبرمج أو عندك مبرمج) عشان تعمل التكامل صح من أول مرة. هنتكلم عن الـ API، والـ Webhooks، وأمثلة كود جاهزة بـ PHP/Laravel و Node و Python.
الخطوة الأولى: تجهيز الحساب ومفتاح الـ API
قبل أي كود، لازم يكون عندك حساب مفعّل. تقدر تسجّل مجاناً من هنا وتربط رقم فودافون كاش أو InstaPay بتاعك. بعد التفعيل هتلاقي في لوحة التحكم قسم Developers / API فيه:
- API Key — المفتاح السري بتاعك، متبعتوش لأي حد ولا تحطه في كود الفرونت إند.
- Store ID — معرّف المتجر اللي بتستقبل عليه الدفعات.
- Webhook Secret — مفتاح توقيع بتتأكد بيه إن الطلب جاي من Daffaa فعلاً مش من حد بيقلّد.
أساسيات نداء الـ API
كل الطلبات بتروح على https://daffaa.net/api/v1 عن طريق HTTPS، وبتحط المفتاح في الهيدر:
- Authorization: Bearer YOUR_API_KEY
- Content-Type: application/json
مثال بسيط لجلب حالة عملية دفع:
GET /api/v1/payments/{reference} — بيرجّعلك JSON فيه status (pending / confirmed / failed)، وamount، وmethod (vodafone_cash أو instapay)، ورقم العميل.
الخطوة الثانية: استقبال الـ Webhook (القلب النابض للتكامل)
ده أهم جزء. بدل ما تفضل تسأل الـ API كل شوية "الدفعة وصلت ولا لأ؟"، Daffaa هو اللي بيكلّمك. أول ما رسالة الدفع تتقري وتتأكد، بنبعتلك POST request على الـ Webhook URL اللي انت مسجّله في اللوحة، وفيه جسم زي كده:
- event: payment.confirmed
- reference: رقم مرجعي فريد للعملية
- amount: المبلغ بالجنيه
- customer_phone / customer_username: بيانات العميل عشان تشحنه
- signature: توقيع HMAC للتحقق
قاعدة أمان مهمة: تحقق من التوقيع دايماً
Daffaa بيوقّع كل Webhook بـ HMAC-SHA256 باستخدام الـ Webhook Secret. لازم تتأكد من التوقيع قبل ما تصدّق الطلب، عشان محدش يبعتلك دفعات وهمية. الفكرة: تحسب HMAC للجسم الخام بنفس السر وتقارنه بالهيدر X-Daffaa-Signature.
مثال PHP / Laravel
اعمل route جديد واستقبل الـ Webhook فيه:
- هات الـ payload الخام بـ $request->getContent().
- احسب hash_hmac('sha256', $payload, $secret) وقارنه بالهيدر باستخدام hash_equals() (مقارنة آمنة ضد timing attacks).
- لو التوقيع صح والـ event هو payment.confirmed — اشحن العميل وارجّع 200 OK بسرعة.
خلي البال إنك ترجّع 200 على طول ولو الشحن محتاج وقت، اعمله في Queue / Job عشان Daffaa ما يعملش retry من غير داعي.
مثال Node.js (Express)
استخدم express.raw() عشان توصلك بايتات الجسم زي ما هي، بعدين crypto.createHmac('sha256', secret) وقارن بـ crypto.timingSafeEqual. بعد التحقق، حدّث الأوردر أو نادِ API البانل بتاعك لشحن الرصيد.
مثال Python (Flask / Django)
في Python استخدم مكتبة hmac وhashlib: hmac.new(secret, body, hashlib.sha256).hexdigest() ثم hmac.compare_digest للمقارنة الآمنة. لو شغال FastAPI اقرأ الجسم بـ await request.body() قبل أي parsing.
الخطوة الثالثة: التعامل مع الأخطاء وإعادة المحاولة
عشان التكامل يبقى محترف:
- Idempotency: خزّن الـ reference وتأكد إنك ما تشحنش نفس العملية مرتين لو وصلك نفس الـ Webhook تاني.
- Retries: لو سيرفرك رجّع خطأ، Daffaa بيعيد المحاولة كذا مرة بفواصل زمنية متزايدة — فتعامل مع التكرار بأمان.
- Logging: سجّل كل Webhook داخل قاعدة بياناتك عشان تراجع أي مشكلة بعدين.
- Fallback polling: ممكن كل شوية تنادي GET /payments كخطة بديلة لو حصل خلل في الشبكة.
ربط الشحن التلقائي على بانل SMM
لو انت ريسيلر SMM، أقوى استخدام هو إنك توصل الـ Webhook بـ API البانل بتاعك مباشرة: بمجرد payment.confirmed، تنادي endpoint الـ add funds على البانل باسم مستخدم العميل، فيتشحن رصيده في ثواني وهو نايم. كده بتبيع 24 ساعة من غير ما تقعد على الموبايل. تقدر تشوف تفاصيل الإعداد الكامل في دليل الاستخدام.
خلاصة وابدأ دلوقتي
التكامل مع Daffaa API مش معقّد: مفتاح API، Webhook URL، تحقق من التوقيع، وشحن تلقائي. النتيجة إنك بتحوّل عملية دفع كانت بتاخد دقايق ومجهود يدوي لعملية بتخلص في ثواني بدون أي تدخل. لو حابب تقرا مقالات تقنية وتسويقية تانية زوروا المدونة.
جاهز تبدأ؟ سجّل حسابك على Daffaa مجاناً واطلع مفتاح الـ API بتاعك وابدأ أول تكامل النهارده.
