الـ API طريقة يطلب بها تطبيقك شيئاً من خدمة أخرى، مثل إنشاء عملية دفع أو بوليصة شحن، والويب هوك (Webhook) طريقة تخبر بها الخدمة الأخرى تطبيقك أن شيئاً حدث، مثل نجاح الدفع أو تسليم الشحنة. لربط تطبيقك: احصل على مفاتيح الخدمة من حسابك، وابدأ ببيئة الاختبار، واحفظ المفاتيح على الخادم فقط، وتحقق من توقيع كل ويب هوك، وسجّل كل طلب واستجابة لتعرف ما حدث عند الخطأ.
- ربط التطبيق ب api
- ايش يعني webhook
- كيف اربط متجري بشركة الشحن
- الفرق بين api و webhook
- how to connect my app to other services with api
- what is a webhook and how does it work
كيف تربط تطبيقك بخدمات أخرى عبر API والويب هوك؟
ربط تطبيقك بخدمات أخرى عبر API والويب هوك يعني أن تجعل تطبيقك يتحدث مع أنظمة خارجية: بوابة الدفع، شركة الشحن، واتساب، برنامج المحاسبة، أو خدمة الرسائل. الـ API هي «النافذة» التي يطلب منها تطبيقك شيئاً، والـ Webhook هو «الجرس» الذي تقرعه الخدمة الأخرى عندما يحدث شيء يهمك.
مثال يومي: عميل يدفع في متجرك. تطبيقك يستخدم API بوابة الدفع لإنشاء العملية وفتح صفحة الدفع. بعد أن يدخل العميل بطاقة مدى ويؤكد، ترسل البوابة ويب هوك إلى تطبيقك: «الدفع نجح». عندها يغير التطبيق حالة الطلب، ويرسل إشعاراً، ويطلب عبر API شركة الشحن إنشاء بوليصة. سلسلة كاملة بلا تدخل بشري.
الـ API أن تسأل، والويب هوك أن يُخبرك أحد دون أن تسأل.
ما الفرق بين API والويب هوك؟
- تطبيقك يبدأ الطلب
- مثال: أنشئ عملية دفع، احسب الشحن، أرسل رسالة
- تحصل على الرد فوراً في نفس الطلب
- تحتاج مفتاحاً سرياً يثبت هويتك
- الخدمة الأخرى تبدأ الطلب إلى رابط في تطبيقك
- مثال: الدفع نجح، الشحنة سُلمت، العميل رد
- يصل عندما يحدث الحدث، ولو بعد ساعات
- تحتاج التحقق من توقيعه حتى لا يزوّره أحد
لماذا لا يكفي الـ API وحده؟ لأنك لا تعرف متى ستُسلم الشحنة. يمكن لتطبيقك أن يسأل شركة الشحن كل خمس دقائق «هل سُلمت؟»، لكن هذا مزعج ومكلف. الأفضل أن تخبرك هي عبر ويب هوك لحظة التسليم.
أشهر التكاملات التي يحتاجها تطبيق خليجي
| الفئة | أمثلة من السوق | API يُستخدم لـ | الويب هوك يخبرك بـ |
|---|---|---|---|
| الدفع | Moyasar وHyperPay وTap في السعودية، Network International وTelr في الإمارات | إنشاء عملية، استرداد | نجاح أو فشل الدفع، الاسترداد |
| الدفع الآجل | Tabby وTamara | إنشاء طلب تقسيط | الموافقة أو الرفض أو الإلغاء |
| الشحن | SMSA وAramex وSPL وJ&T | إنشاء بوليصة، حساب السعر، التتبع | تغير حالة الشحنة |
| الرسائل | WhatsApp Business Platform، مزودو الرسائل النصية | إرسال تأكيد أو رمز تحقق | التسليم والقراءة والردود |
| المحاسبة والفوترة | برامج المحاسبة ومزودو حلول الفوترة الإلكترونية | إرسال الفاتورة | حالة اعتماد الفاتورة |
| الخرائط | خدمات الخرائط والعناوين | البحث عن عنوان، حساب المسافة | نادراً |
| أدوات العمل | Google Sheets، أنظمة CRM | إضافة صف أو عميل | تحديث من الطرف الآخر |
للدفع تحديداً، اقرأ كيف تضيف الدفع لتطبيقك، ولواتساب اقرأ إرسال إشعارات واتساب من تطبيقك. وفنّان يأتي بتكاملات جاهزة لكثير من وسائل الدفع المحلية والخدمات الشائعة عبر صفحة التكاملات.
خطوات ربط أي خدمة بتطبيقك
- 1حدد الحدث والنتيجة
اكتب بجملة: «عندما يدفع العميل، أنشئ بوليصة شحن تلقائياً وأرسل رقم التتبع للعميل». هذه الجملة هي مواصفات التكامل.
- 2افتح حساباً عند الخدمة
سجّل نشاطك، وأكمل التوثيق المطلوب، واحصل على مفاتيح بيئة الاختبار أولاً.
- 3ابنِ على بيئة الاختبار
اربط التطبيق بمفاتيح Sandbox، وجرّب الحالات الناجحة والفاشلة، بما فيها البطاقة المرفوضة والعنوان الخاطئ.
- 4سجّل رابط الويب هوك
أضف رابط تطبيقك الذي يستقبل الأحداث في لوحة الخدمة، وانسخ سر التوقيع إلى إعدادات الخادم.
- 5اختبر على نسخة تجريبية
جرّب السلسلة كاملة على بيئة الاختبار قبل أن تلمس النسخة المباشرة.
- 6انتقل للمفاتيح الحقيقية
استبدل المفاتيح، ونفّذ عملية حقيقية صغيرة واستردها، ثم راقب السجلات في الأيام الأولى.
الأمان: المفاتيح والتوقيع
كل تكامل يفتح باباً بين تطبيقك والعالم. هذه القواعد تبقي الباب مقفلاً لغير أصحابه:
- المفاتيح السرية على الخادم فقط، في إعدادات البيئة وليس في الكود ولا في تطبيق الجوال. تفاصيل أكثر في مفاتيح API وحماية الأسرار.
- تحقق من توقيع كل ويب هوك. معظم الخدمات ترسل توقيعاً يثبت أن الرسالة منها. بدون تحقق، يستطيع أي شخص إرسال «الدفع نجح» لتطبيقك.
- لا تصدّق الويب هوك وحده في المبالغ. عند إشعار الدفع، اسأل البوابة عبر API عن حالة العملية ومبلغها قبل تأكيد الطلب.
- أقل صلاحية للمفتاح. إذا سمحت الخدمة بمفاتيح محدودة (قراءة فقط مثلاً) فاستخدمها.
- دوّر المفاتيح عند مغادرة موظف تقني أو الشك في تسربها.
عندما يفشل شيء: إعادة المحاولة والسجلات
الأنظمة الخارجية تتعطل أحياناً، والشبكات تنقطع، والويب هوك قد يصل مرتين. التكامل الجيد يتوقع ذلك:
| المشكلة | ماذا يحدث | الحل |
|---|---|---|
| الخدمة لا ترد | الطلب ينتهي بلا نتيجة | إعادة محاولة بفواصل متزايدة، ثم تنبيه للفريق |
| ويب هوك مكرر | قد يُشحن الطلب مرتين | احفظ معرف كل حدث وتجاهل المكرر |
| ويب هوك متأخر | يصل «الدفع نجح» بعد ساعة | لا تلغِ الطلب تلقائياً قبل التحقق عبر API |
| تجاوز حد الطلبات | الخدمة ترفض مؤقتاً | خفف التكرار واستخدم التخزين المؤقت |
| تغيير في الخدمة | حقل جديد أو قديم أُلغي | تابع إعلانات الخدمة واختبر بعد كل تحديث |
واحتفظ بسجل تكاملات في لوحة التحكم: كل طلب أرسله تطبيقك وكل ويب هوك استقبله، مع الوقت والحالة ورسالة الخطأ. عندما يتصل عميل ويقول «دفعت ولم يتأكد طلبي»، تفتح السجل وتعرف الجواب خلال دقيقة بدل التخمين.
التكاملات في فنّان، وأين يدخل MCP
في فنّان لا تحتاج لكتابة كود التكامل. تصف ما تريد بالعربي، فيقرأ وكيل فنّان توثيق الخدمة، ويبني طلبات API ونقاط استقبال الويب هوك، ويحفظ المفاتيح في إعدادات الخادم، ويضيف سجل التكاملات، ثم يختبر السلسلة على بيئة الاختبار. وتبقى ملكية الكود لك بالكامل.
وقد تسمع عن MCP، وهو بروتوكول يتيح لنماذج الذكاء الاصطناعي استخدام أدوات وخدمات خارجية بطريقة موحدة. هو مفيد عندما تريد لمساعد ذكي داخل تطبيقك أن يستخدم أدوات، بينما الربط التقليدي بين تطبيقك وبوابة الدفع أو الشحن يبقى عبر API والويب هوك. الشرح الكامل في ما هو MCP؟.
اربط متجري بشركة الشحن التي أستخدمها عبر API الخاص بها، وابدأ ببيئة الاختبار. عندما يصل ويب هوك من بوابة الدفع بنجاح الدفع: تحقق من توقيعه، ثم اسأل البوابة عبر API عن حالة العملية ومبلغها، وإذا تطابقت أنشئ بوليصة شحن تلقائياً بعنوان العميل (مع العنوان الوطني إن وجد)، واحفظ رقم التتبع في الطلب، وأرسل للعميل إشعار واتساب برقم التتبع. استقبل ويب هوك تحديث حالة الشحنة وحدّث حالة الطلب وأرسل إشعاراً عند التسليم. احفظ معرف كل حدث وتجاهل المكرر، وأعد المحاولة عند فشل الطلب 3 مرات بفواصل متزايدة ثم نبّه مدير المتجر. احفظ كل المفاتيح في إعدادات الخادم فقط. أضف في لوحة التحكم صفحة «سجل التكاملات» تعرض كل طلب وويب هوك مع الوقت والحالة والخطأ.
جرّبه في فنّانالخطوة التالية: اكتب قائمة بالخدمات التي يستخدمها نشاطك اليوم يدوياً (الدفع، الشحن، الرسائل، المحاسبة)، وبجانب كل منها جملة «عندما يحدث كذا، افعل كذا». هذه القائمة هي خطة التكاملات لتطبيقك.
الخلاصة
- API تعني أن تطبيقك يسأل، والويب هوك يعني أن الخدمة الأخرى تخبره؛ معظم التكاملات تحتاج الاثنين.
- ابدأ دائماً ببيئة الاختبار (Sandbox) ولا تنتقل للمفاتيح الحقيقية قبل تجربة كل الحالات.
- المفاتيح السرية على الخادم فقط، وكل ويب هوك يُتحقق من توقيعه قبل تصديقه.
- صمم لحالات الفشل: إعادة المحاولة، عدم تكرار العملية، وسجل يوضح ما حدث.
- في فنّان تصف التكامل بالعربي، فيقرأ الوكيل التوثيق ويبني الربط ويختبره.
أسئلة شائعة
ايش يعني webhook بالعربي؟
ايش الفرق بين api و webhook؟
كيف اربط متجري بشركة الشحن؟
هل احتاج مبرمج عشان اربط api؟
وش يصير اذا الخدمة الخارجية تعطلت؟
اسأل مساعدك الذكي عن هذا الموضوع
انسخ هذا الطلب والصقه في مساعد الذكاء الاصطناعي الذي تستخدمه، ثم أضف تفاصيل حالتك.
أقرأ هذا الدليل: «اربط تطبيقك بخدمات أخرى عبر API والويب هوك: دليل عملي» https://fanann.com/ar/blog/api-integrations-ai-app/ سؤالي: ربط التطبيق ب api اعتمد على هذه الصفحة كمصدر واشرح لي الإجابة خطوة بخطوة بما يناسب حالتي، واذكر ما يجب أن أتحقق منه قبل أن أبدأ، واذكر رابط الصفحة كمرجع.