ربط API بين الأنظمة يعني أن يتبادل موقعك أو تطبيقك البيانات تلقائيًا مع أنظمة أخرى، مثل بوابة الدفع وشركة الشحن والبرنامج المحاسبي ومتجرك على سلة، بدل أن ينقلها موظف يدويًا من شاشة إلى أخرى. والربط الجيد ليس مجرد "كود يعمل في يوم التسليم"، بل تصميم يشمل المصادقة والإشعارات وإعادة المحاولة والسجلات والتوثيق. أما بعض الروابط الحكومية مثل نفاذ فلا تتم إلا بعد موافقة عبر القنوات الرسمية، ولا يملك أي مطور أن يعدك بها مسبقًا.
ماهو ربط API؟ شرح مبسط لصاحب العمل
الـ API هو "نافذة خدمة" يفتحها نظام ما لأنظمة أخرى. بوابة الدفع مثلًا تفتح نافذة تقول: أرسل لي المبلغ ورقم الطلب، وسأعيد لك رابط الدفع ثم أخبرك بالنتيجة. شركة الشحن تفتح نافذة لإنشاء بوليصة وتتبع الشحنة. والبرنامج المحاسبي يفتح نافذة لاستقبال الفواتير.
عندما نقول إن موقعك "مربوط" بنظام آخر، فنحن نقصد أن الكود لديك يتحدث مع هذه النافذة وفق قواعد يحددها المزود في توثيقه: كيف تعرّف نفسك، وما شكل البيانات، وما الذي يحدث عند الخطأ.
مثال تقريبي من السوق السعودي
تخيّل متجر عطور في جدة يبيع عبر موقعه الخاص. بدون ربط، يدخل الموظف كل طلب في نظام الشحن يدويًا، ثم يرسل رقم التتبع للعميل عبر الجوال، ثم يسجل الفاتورة في البرنامج المحاسبي آخر اليوم. مع الربط، يحدث ذلك كله عند تأكيد الدفع، ويتفرغ الموظف لخدمة العملاء بدل النسخ واللصق.
أشهر عمليات ربط API التي تحتاجها الشركات في السعودية
لا تحتاج كل شركة كل أنواع الربط. ابدأ بما يوفر وقتًا أو يمنع خطأً متكررًا. الجدول التالي يلخص أكثر الروابط شيوعًا وما يجب أن تجهزه قبل أن يبدأ المطور:
| نوع الربط | أمثلة شائعة في السعودية والخليج | ما تجهزه أنت قبل البدء |
|---|---|---|
| الدفع الإلكتروني | مدى وApple Pay عبر مزودين مثل Moyasar وHyperPay وTap وPayTabs، والتقسيط عبر تابي وتمارا | حساب تاجر مفعّل، سجل تجاري، مفاتيح بيئة الاختبار والإنتاج |
| رسائل SMS ورموز التحقق | مزود رسائل محلي أو إقليمي | اسم مرسل مسجل لدى المزود وفق الأنظمة المعمول بها، ورصيد رسائل |
| واتساب للأعمال | منصة WhatsApp Business من Meta مباشرة أو عبر مزود معتمد | حساب أعمال موثق، رقم مخصص، قوالب رسائل معتمدة، موافقة العميل على التواصل |
| الشحن والتوصيل | شركات الشحن المحلية والدولية العاملة في المملكة | عقد مع الشركة وبيانات دخول API وقائمة المدن والخدمات |
| المحاسبة والفوترة | برنامجك المحاسبي الحالي، والربط مع منصة فاتورة عبر حل متوافق | تحديد مصدر الفاتورة الرسمي ومن يصدرها |
| منصات المتاجر | سلة وزد عبر واجهاتهما البرمجية | تطبيق في منصة المطورين لديهم وصلاحيات واضحة |
| الخرائط والعناوين | خرائط Google أو خدمات العنوان الوطني | مفتاح API وحدود الاستخدام وتكلفتها |
| الهوية الرقمية | نفاذ | موافقة رسمية وفق شروط الجهة المشغلة، وهي ليست قرارًا تقنيًا |
بخصوص الفوترة، إذا كانت منشأتك ضمن موجات المرحلة الثانية من هيئة الزكاة والضريبة والجمارك، فالربط مع منصة فاتورة إلزامي بحسب موعد موجتك. أعلنت الهيئة مثلًا الموجة 25 للمكلفين الذين تتجاوز إيراداتهم الخاضعة للضريبة 187,500 ريال في أيٍّ من الأعوام 2022 إلى 2025، وموعد الربط فيها 1 فبراير 2027 بحسب إعلان الهيئة كما نقلته EY. راجع موقع الهيئة للتأكد من الإشعار الخاص بمنشأتك.
ربط API نفاذ: ما الذي يجب أن تعرفه قبل أن تعد عملاءك به
يكثر البحث عن "ربط api نفاذ" لأن تسجيل الدخول بالهوية الوطنية يمنح الثقة ويختصر خطوات التحقق. لكن نفاذ ليس مكتبة برمجية تُثبَّت في يوم واحد. الوصول إليه للجهات غير الحكومية يمر بطلب رسمي واشتراطات تحددها الجهة المشغلة، وقد يتوقف القبول على نوع نشاطك وسبب حاجتك للتحقق من الهوية.
دور المطور هنا محدود وواضح: يجهز تدفق تسجيل الدخول في التطبيق، ويبني الجزء الخلفي الذي يستقبل النتيجة ويحفظها بأمان، ثم ينفذ الربط الفعلي بعد أن تحصل منشأتك على بيانات الاعتماد وبيئة الاختبار. لذلك لا تربط موعد إطلاق مشروعك بموافقة لا تملك توقيتها.
ماذا تفعل حتى تصل الموافقة؟
أطلق بتسجيل دخول برقم الجوال ورمز تحقق، وصمم شاشة الحساب بحيث يمكن إضافة نفاذ لاحقًا دون إعادة بناء. وتحقق من الشروط الحالية مباشرة من القنوات الرسمية لنفاذ، لأنها قد تتغير.
طريقة ربط API خطوة بخطوة كما ينبغي أن تُنفَّذ
1. ابدأ بالعملية التجارية لا بالتقنية
اكتب في سطرين ماذا يجب أن يحدث: "عند نجاح الدفع، تُنشأ شحنة ويصل العميلَ رقم التتبع عبر واتساب". هذا السطر يحدد نطاق العمل أكثر من أي مواصفة تقنية.
2. بيئة اختبار وتوثيق قبل أي سطر كود
معظم المزودين يقدمون بيئة اختبار (Sandbox). اطلبها مبكرًا، فالتأخير في الحصول على المفاتيح من أكثر أسباب تعطل الجداول الزمنية.
3. المصادقة وحفظ المفاتيح
مفاتيح الـ API تشبه مفاتيح الخزنة. يجب أن تُحفظ في إعدادات الخادم لا داخل التطبيق ولا في الكود المرفوع للمستودع، وأن يكون لكل بيئة مفاتيحها.
4. Webhooks بدل السؤال المتكرر
بدل أن يسأل نظامك بوابة الدفع كل دقيقة "هل دفع العميل؟"، تُرسل البوابة إشعارًا (Webhook) عند حدوث الدفع. يجب التحقق من توقيع هذا الإشعار حتى لا يتمكن أحد من تزويره.
5. إعادة المحاولة ومنع التكرار
الشبكات تنقطع والمزودون يتعطلون أحيانًا. الربط المحترف يعيد المحاولة تلقائيًا بفواصل زمنية متزايدة، ويمنع إنشاء الشحنة أو الفاتورة مرتين للطلب نفسه.
6. السجلات والمراقبة
كل طلب وكل رد يُسجَّل بشكل منظم دون تخزين بيانات حساسة كأرقام البطاقات. ويُضاف تنبيه يصل للفريق عند تكرار الفشل، فتعرف بالمشكلة قبل أن يتصل بك العميل.
7. التوثيق والتسليم
في نهاية المشروع يجب أن تستلم وثيقة تشرح كل ربط: ماذا يفعل، وأين مفاتيحه، وكيف تُجدَّد، ومن تتواصل معه لدى المزود.
أخطاء شائعة تكلّف أكثر من الربط نفسه
- الاعتماد على حساب المطور الشخصي لدى المزود. يجب أن تكون الحسابات باسم منشأتك.
- تجاهل حماية البيانات. نظام حماية البيانات الشخصية السعودي، الذي تشرف عليه سدايا، نافذ منذ سبتمبر 2024، ونقل بيانات العملاء إلى مزود خارج المملكة له اشتراطات. راجع ذلك مع مستشارك القانوني، فهذا ليس رأيًا قانونيًا.
- إرسال رسائل واتساب دون موافقة العميل أو بقوالب غير معتمدة، وهو ما قد يؤدي إلى تقييد الرقم.
- عدم اختبار سيناريوهات الفشل: دفع ناجح مع انقطاع الإشعار، أو شحنة رُفضت بسبب عنوان ناقص.
كيف نبني الربط في PIXELSAA
نبني الأنظمة الخلفية وواجهات REST API باستخدام Laravel، ثم نربطها بالمزودين الذين يختارهم العميل. في تطبيق زاود للحسابات والديون مثلًا، يتحدث تطبيق Flutter على أندرويد مع موقع ولوحة إدارة مبنيين بـ Laravel، ويتضمن مساعدًا ذكيًا يعمل عبر Gemini، إلى جانب كشوف PDF ومتابعة التحصيل بالاتصال أو واتساب.
إذا كان الربط جزءًا من نظام أكبر، فاطلع على خدمة تطوير الأنظمة المخصصة، وعلى مقالنا عن متى تحتاج شركتك نظامًا مخصصًا باستخدام Laravel. ولمن يبيع عبر سلة، شرحنا تفاصيل ربط API سلة، كما فصّلنا خيارات بوابة الدفع الإلكتروني في السعودية.
قائمة جاهزة: أسئلة تطرحها على المطور قبل عقد الربط
انسخ هذه الأسئلة وأرسلها مع طلب العرض:
- هل الحسابات والمفاتيح لدى المزودين ستكون باسم منشأتي؟
- كيف ستتعامل مع تعطل المزود أو انقطاع الإشعار؟ وهل يوجد منع للتكرار؟
- أين ستُحفظ المفاتيح؟ وكيف تُجدَّد دون توقف الخدمة؟
- ما البيانات التي ستُسجَّل؟ وكيف تُستبعد البيانات الحساسة من السجلات؟
- من سيتلقى تنبيه الفشل؟ وخلال كم من الوقت؟
- هل سأستلم توثيقًا مكتوبًا لكل ربط؟
- ما الذي يعتمد على موافقة جهة خارجية، وكيف يتأثر به الجدول الزمني؟
الأسئلة الشائعة
ماهو ربط API باختصار؟
هو جعل نظامين يتبادلان البيانات تلقائيًا عبر واجهة برمجية يوفرها أحدهما، مثل أن يرسل موقعك الطلب إلى بوابة الدفع ثم يستقبل نتيجة الدفع دون تدخل بشري. الفائدة المباشرة هي تقليل الإدخال اليدوي والأخطاء، وتسريع خدمة العميل. ويشمل الربط الجيد التحقق من الهوية، والتعامل مع الأخطاء، وتسجيل العمليات، وتوثيقًا تستلمه منشأتك.
هل يمكن ربط تطبيقي مع نفاذ مباشرة؟
لا يتم ذلك بقرار تقني فقط. الوصول إلى نفاذ للجهات الخاصة يمر بطلب رسمي واشتراطات تحددها الجهة المشغلة، وقد يتوقف القبول على نشاطك وحاجتك للتحقق من الهوية. يستطيع المطور تجهيز تدفق الدخول والنظام الخلفي، ثم إكمال الربط بعد حصولك على بيانات الاعتماد. تحقق من الشروط الحالية عبر القنوات الرسمية لنفاذ.
ما المدة التي يستغرقها ربط API؟
تختلف بحسب عدد الروابط وجودة توثيق المزود وسرعة حصولك على حسابات الاختبار والإنتاج. ربط بوابة دفع واحدة بمنطق بسيط أقصر بكثير من ربط محاسبي يتضمن مطابقة فواتير ومرتجعات. أكثر ما يؤخر الجداول عادة هو انتظار تفعيل حساب التاجر أو اعتماد قوالب واتساب، لذلك ابدأ بهذه الإجراءات قبل التطوير.
هل أحتاج نظامًا خلفيًا لربط واتساب أو بوابة الدفع؟
في الغالب نعم. مفاتيح الـ API يجب ألا توضع داخل تطبيق الجوال لأنها قابلة للاستخراج، والإشعارات من بوابة الدفع أو واتساب تحتاج خادمًا يستقبلها ويتحقق من توقيعها. لذلك تُبنى عادة طبقة خلفية، مثل REST API بلغة Laravel، تتولى الحديث مع المزودين وتعرض لتطبيقك واجهة آمنة وبسيطة.
ابدأ بخريطة الروابط التي تحتاجها
إذا كنت تخطط لربط موقعك أو تطبيقك ببوابات الدفع أو واتساب أو الشحن أو المحاسبة في السعودية أو الخليج، أرسل لنا قائمة الأنظمة التي تستخدمها وسنعود إليك بخريطة ربط مقترحة ونطاق عمل ومراحل تنفيذ واضحة قبل أي التزام.
