توصيل الخدمات: البريد، الدفع، الذكاء الاصطناعي

التطبيق الذي يكلّم العالم

نجاح تطبيق توم يتجاوز صفه: زميلة في اللغة الفرنسية تستخدمه مع تلاميذها، وأستاذ رياضيات من مدرسة أخرى كتب له ليعرف «كيف يثبّته لمؤسسته — وكم يكلف». تبرز ثلاث رغبات: إرسال ملخص أسبوعي بالبريد للتلاميذ، إضافة رسالة تشجيع يولّدها الذكاء الاصطناعي عندما ينهي تلميذ يومه، واقتراح نسخة «صف» مدفوعة لأساتذة المدارس الأخرى. ثلاث ميزات، آلية واحدة: جعل تطبيقه يتحاور مع خدمات خارجية.

هذا الحوار يمر عبر API (واجهات برمجية). المبدأ: خدمة ما — Resend للبريد، Stripe للدفع، Claude للذكاء الاصطناعي — تعرض شبّاكًا على الإنترنت. يتقدم تطبيقك إليه بطلب مهيكل («أرسل هذا البريد إلى هذا العنوان») ومفتاح API يثبت هويته، فتنفّذ الخدمة ثم تجيب. لست بحاجة إلى فهم كيف يوصل Resend بريدًا، تمامًا كما لا تحتاج إلى فهم محطة كهرباء لتوصيل قابس: الـAPI هي القابس.

القاعدة الذهبية: المفاتيح تبقى جهة الخادم

قبل أي توصيل، قاعدة مطلقة. مفتاح API الخاص بك بطاقة مصرفية: من يملكه يستهلك الخدمة باسمك وعلى نفقتك. والحال أن كل كود يعمل في متصفح مقروء لأي كان — تكفي F12 بسيطة. الخلاصة القاطعة: المفتاح السري يجب ألا يوجد أبدًا في كود جهة المتصفح. يعيش جهة الخادم، حيث لا يستطيع أحد قراءته.

«لكن ليس لدي خادم!» بلى، تقريبًا: Vercel (ومنافسوه) يقدم وظائف خادم — مقاطع كود صغيرة مستضافة لديهم، تُنفَّذ عند الطلب. المخطط هو نفسه دائمًا: المتصفح يستدعي وظيفة الخادم (بلا مفتاح)، الوظيفة تستدعي الخدمة الخارجية (بالمفتاح، المخزن في متغير بيئة)، وتعيد إلى المتصفح النتيجة فقط. الذكاء الاصطناعي يجيد إنشاء هذه الوظائف تمامًا — وعملك أنت اشتراط هذه البنية في موجّهاتك.

flowchart LR
  N["متصفح التلميذ"] -->|"طلب بلا أي مفتاح"| F["وظيفة خادم على Vercel"]
  F -->|"استدعاء بالمفتاح السري"| S["خدمة خارجية: Resend أو Stripe أو Claude"]
  S -->|"رد"| F
  F -->|"نتيجة نظيفة"| N

إرسال البريد: الملخص الأسبوعي

أول توصيل: البريد الإلكتروني. لا نرسل رسائل آلية من صندوق Gmail الشخصي — المزودون يحجبونها سريعًا والأمر هش. نمر عبر خدمة بريد معاملاتي مثل Resend أو Postmark أو Brevo: مصممة للتطبيقات، موثوقة، ومجانية على نطاق صغير (Resend يقدم 100 بريد يوميًا، أبعد بكثير من حاجات توم). موجّه توم، كاملًا:

أضِف إرسال بريد ملخص إلى تطبيقي لتتبع العادات.
السياق: تطبيق HTML/JS على Vercel، البيانات في Supabase، مصادقة بالرابط السحري.
ما أريده:
1. زر «استلام ملخص أسبوعي» على الصفحة الرئيسية
2. عند النقر، وظيفة خادم Vercel تحسب سلاسل وإشارات أسبوع المستخدم المتصل، وترسل له بريدًا نظيفًا ومقروءًا عبر Resend
3. مفتاح API الخاص بـResend يبقى جهة الخادم، في متغير بيئة Vercel — أبدًا في كود المتصفح
4. حد صارم: إرسال واحد لكل مستخدم يوميًا كحد أقصى، مع رسالة واضحة عند بلوغ الحد
أرشدني أولًا لإنشاء حساب Resend وضبط متغير البيئة على Vercel، ثم برمج الوظيفة.
مرحلة واحدة في كل مرة، أنتظر الاختبار قبل التالية.

توقف عند السطر 4: «إرسال واحد لكل مستخدم يوميًا». لماذا نحدّ ميزة مجانية؟ لأن كل زر يطلق خدمة خارجية يمكن طرقه بلا توقف — من تلميذ مازح أو روبوت — وكل إرسال يستهلك حصتك. وضع حد منذ التصميم انعكاس مهندس معماري: تحمي خدمتك قبل أن تحتاج إلى الحماية. سنعمم هذا الانعكاس في الفصل 9.

قبض دفعة دون برمجة: Stripe Payment Links

للنسخة «صف» المدفوعة، يخشى توم الأسوأ: الدفع الإلكتروني أمر جاد، منظَّم، مقلق. مفاجأة سارة: Stripe، خدمة الدفع الأكثر استخدامًا لدى المطورين، تقدم الـPayment Links — صفحات دفع تستضيفها Stripe، تُنشأ ببضع نقرات في لوحة تحكمهم، دون سطر كود واحد. تنشئ منتجًا («نسخة الصف — 29 يورو/سنة»)، تولّد Stripe رابط URL، وما على تطبيقك إلا عرض زر يشير إلى هذا الرابط. Stripe تدير البطاقة المصرفية، والأمان، والفوترة، والاستردادات.

• أنشئ حسابًا على stripe.com وابقَ في وضع الاختبار حاليًا.
• في لوحة التحكم: Produits ← أضِف «نسخة الصف» بسعرها.
• ولّد الـPayment Link للمنتج وانسخ الرابط.
• اطلب من الذكاء الاصطناعي إضافة صفحة «نسخة الصف» بالفوائد وزر نحو هذا الرابط.
• اختبر المسار الكامل في وضع الاختبار، ثم فعّل الوضع الحقيقي بعد المصادقة على كل شيء.

للـPayment Links حدود — لا فتح تلقائيًا للميزات في التطبيق بعد الدفع مثلًا. لنسخة توم الأولى، هذا مثالي: الأستاذ يدفع عبر الرابط، يتلقى توم إشعار Stripe ويفعّل الصف يدويًا. خمسة عملاء شهريًا أمر يُدار يدويًا؛ ويوم يصبحون خمسين، سيوصّل الأتمتة (الـ«webhooks») — مشكلة أغنياء، لوقت لاحق. أتمتة ما لا يحدث إلا خمس مرات شهريًا صفقة خاسرة.

إضافة لمسة ذكاء اصطناعي في تطبيقك

آخر توصيل، وألذّها: استخدام الذكاء الاصطناعي داخل تطبيقك — لا لبنائه فحسب. فكرة توم: عندما يؤشّر تلميذ آخر عادة في يومه، تظهر رسالة تشجيع قصيرة مخصصة، تولّدها API الخاصة بـClaude. البنية نفسها كالبريد: وظيفة خادم، مفتاح في متغير بيئة، حد استخدام. مع احتياطين جديدين خاصين بالذكاء الاصطناعي:

أضِف وظيفة «تشجيع اليوم» إلى تطبيقي لتتبع العادات.
عندما يؤشّر المستخدم آخر عادة في يومه، استدعِ API الخاصة بـClaude من وظيفة خادم Vercel لتوليد رسالة تشجيع قصيرة مخصصة:
- نبرة دافئة لكن غير ساذجة، مناسبة لتلاميذ إعدادية
- اذكر السلسلة الحالية والعادة الأكثر انتظامًا في الأسبوع
- جملتان كحد أقصى، بالعربية
القيود التقنية:
1. مفتاح API يبقى في متغير بيئة، جهة الخادم فقط
2. الحد: استدعاء واحد لكل مستخدم يوميًا
3. جهّز رسالة افتراضية لطيفة إن فشل الاستدعاء أو تجاوز 5 ثوانٍ — يجب ألا ينكسر التطبيق أبدًا بسبب هذه الوظيفة
أرني النص الحرفي للموجّه الذي سترسله الوظيفة إلى Claude، لأستطيع ضبطه.

سطران يستحقان انتباهك. «جهّز رسالة افتراضية إن فشل الاستدعاء»: إنه التدهور الأنيق — ميزة إضافية يجب ألا تستطيع أبدًا كسر التطبيق الذي يحملها. و«أرني النص الحرفي للموجّه»: نعم، تطبيقك يحتوي الآن هو نفسه موجّهًا، يمكنك صقله كما تعلمت صقل موجّهاتك. تكتب موجّهات تولّد كودًا يرسل موجّهات — الحلقة لذيذة، وأنت تتقن كل طابق فيها.

عندما تتعطل خدمة خارجية

آخر درس في هذا الفصل: تطبيقك يعتمد الآن على خدمات لا تتحكم بها. Resend أو Stripe أو API الخاصة بـClaude قد تتعطل، أو تبطئ، أو تغيّر قواعدها. ثلاث عادات بالتناسب: فحص صفحة حالة الخدمة قبل البحث عن الخلل عندك («Resend status» في محرك بحث)، تجهيز سلوك تراجع لكل توصيل (رسالة افتراضية، زر معطَّل مع شرح)، وعدم جعل الوظيفة الجوهرية لتطبيقك تعتمد أبدًا على خدمة خارجية. عادات توم تُؤشَّر حتى لو تعطلت الذكاء الاصطناعي والبريد والدفع ثلاثتها — هذه هي البنية السليمة.

تطبيقك يعرف الآن الكتابة والقبض والتفكير. لكن كل توصيل وسّع أيضًا سطح تعرضه: مفاتيح تُحمى، مدخلات تُتحقق، حدود تُفرض. قبل المضي أبعد، حان وقت تأمين المجموعة بجدية — هذا برنامج الفصل 9.