كيف تدمج مدفوعات تمارا (BNPL) بشكل صحيح — والأداة مفتوحة المصدر التي تنفّذ ذلك بالذكاء الاصطناعي

لو سبق وطلبت من مساعد برمجة بالذكاء الاصطناعي أن يربط لك بوابة دفع، فقد رأيته يخترع بثقة نقطة نهاية (endpoint) غير موجودة. مع معظم الـ APIs يكون هذا خطأً مزعجاً تكتشفه أثناء الاختبار. أمّا مع تمارا فالأمر أخطر: الـ API لديه قواعد توقيت صارمة وآلة حالات دقيقة لحالة الطلب، لذا قد يترك التخمين الواثق طلبات حقيقية دون تسوية — يشحن التاجر البضاعة ولا يستلم المال أبداً.

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

ما هي تمارا؟

تمارا (Tamara) هي المنصة الرائدة للتسوّق والشراء الآن والدفع لاحقاً (BNPL) في الخليج — السعودية والإمارات والبحرين والكويت وعُمان. يقسّم المتسوّق المشترى إلى أقساط بدون فوائد ("قسّمها على 3"، "قسّمها على 4"، "ادفع الشهر القادم") بينما يُدفع للتاجر مقدّماً. وهي من أعلى خيارات الدفع تحويلاً للمبيعات في المنطقة، ولهذا تقدّمها تقريباً كل المتاجر الجادّة في الخليج.

اختر مسار التكامل أولاً

قبل كتابة أي سطر كود، حدّد كيف ستضيف تمارا — فالوثائق تختلف لكل مسار:

• الـ API المباشر — كود مخصّص على خادمك؛ أكبر قدر من التحكّم.
• إضافة متجر — تثبيت بدون كود على متجر مستضاف: WooCommerce، Shopify، سلة، Magento، OpenCart، PrestaShop، زد، Salesforce Commerce Cloud، ExpandCart، وغيرها.
• شريك قناة — أضف تمارا عبر بوابة تستخدمها أصلاً (Checkout.com، PayTabs، Amazon Payment Services، CCAvenue…).
• داخل المتجر / نقاط البيع — المتاجر الفعلية، عبر رابط دفع بالـ SMS أو رمز QR للدفع بالمسح.
• SDK للموبايل — داخل تطبيق (Android، iOS، Flutter، React Native).

إن كنت على WooCommerce أو سلة، ثبّت الإضافة الرسمية وتكون قد أنجزت 90% من العمل. وبقية المقال عن الـ API المباشر، لأنه حيث تقع الأخطاء الدقيقة والمكلفة.

"المسار الذهبي" لـ API تمارا

كل تكامل مباشر له الشكل نفسه. احفظه:

1. أنشئ جلسة دفع — POST /checkout. خزّن الـ order_id العائد ووجّه العميل إلى الـ checkout_url. تبدأ الحالة عند new.
2. يدفع العميل على صفحة تمارا المستضافة → تصبح الحالة approved.
3. يصل webhook الـ order_approved من خادم إلى خادم — هذا هو محفّزك الموثوق، لا إعادة توجيه المتصفح.
4. Authorise (التفويض) — POST /orders/{order_id}/authorise → الحالة authorised (عاملها كمدفوعة). هذه الخطوة إلزامية ما لم يكن التفويض التلقائي مفعّلاً.
5. Capture (التحصيل) عند الشحن/التنفيذ — POST /payments/capture (كلي أو جزئي) → fully_captured / partially_captured. التحصيل هو ما ينقل المال فعلاً إلى تسويتك.
6. استرداد أو إلغاء — استرد المبالغ المحصّلة (/payments/refund)؛ وألغِ أو خفّض الطلبات التي ما زالت authorised (/orders/{order_id}/cancel).

البيئات والمصادقة: التجريبية https://api-sandbox.tamara.co، والإنتاج https://api.tamara.co. صادِق كل طلب بـ Authorization: Bearer {API_TOKEN}. اختبر كل شيء على البيئة التجريبية قبل أن تطلب بيانات الإنتاج.

الأخطاء التي تكسر التسوية بصمت

هذه هي التي تكلّف مالاً حقيقياً — وبالضبط ما يخطئ فيه مساعد الذكاء الاصطناعي حين يخمّن:

• تخطّي الـ Authorise. الطلب الذي يبقى عند approved لا يُحصَّل ولا يُسوَّى أبداً. شحنت ولم تُدفع لك. شغّل التفويض من webhook الـ order_approved.
• الاعتماد على إعادة توجيه المتصفح. قد تُفقد إعادة التوجيه (إغلاق التبويب، شبكة ضعيفة). الـ webhook هو مصدر الحقيقة — تحقّق منه واعمل عليه.
• عدد خانات عشرية خاطئ. يستخدم SAR و AED خانتين، لكن BHD و KWD و OMR تستخدم 3. أرسل دقّة خاطئة فيرفض الـ API الطلب بخطأ دولة/عملة.
• عدم التحقّق من الـ webhook. يحمل كل webhook رمز tamaraToken من نوع JWT (HS256). تحقّق منه بـ Notification token قبل التنفيذ، واجعل المعالجات idempotent — فقد تعيد تمارا إرسال الأحداث.
• تفويت نوافذ التوقيت. الدفع خلال 30 دقيقة، التفويض خلال 72 ساعة، التحصيل/الإلغاء خلال 90 يوماً. تجاوز النافذة وينتهي الطلب (expired).

أداة Claude مجانية ومفتوحة المصدر لتمارا

بدل أن آمل أن يتذكّر النموذج كل ذلك، أعطيته الوثائق الحقيقية. والنتيجة أداة تمارا للمدفوعات على GitHub مفتوحة المصدر — نسخة كاملة بدون إنترنت من docs.tamara.co: 139 صفحة (114 دليلاً + الـ OpenAPI الكامل لكل الـ 25 endpoint)، مع ورقة مرجعية سريعة للـ base URLs والمصادقة وخريطة النقاط وتدفّق حالات الطلب والتحقّق من الـ webhooks.

ضعها في مجلّد أدوات Claude Code فتُفعَّل تلقائياً كلّما ذُكرت تمارا في مهمّة:

git clone https://github.com/karem505/tamara-payments-skill.git ~/.claude/skills/tamara-payments

والآن حين تسأل "ادمج checkout تمارا في متجر WooCommerce" أو "لماذا علق طلب تمارا عند approved؟"، يقرأ الوكيل وثائق تمارا الفعلية قبل كتابة الكود — بدل اختراع نقطة نهاية. تغطّي الأداة الـ API المباشر، وكل إضافات المتاجر، وشركاء القنوات، ونقاط البيع، وSDKs الموبايل، وودجت الترويج، عبر أسواق الخليج الخمسة.

أسئلة شائعة

كيف أدمج مدفوعات تمارا؟ اختر المسار أولاً (API مباشر، إضافة، شريك قناة، نقاط بيع، أو SDK موبايل). لمسار الـ API: أنشئ checkout ← يدفع العميل ← webhook الـ order_approved ← Authorise ← Capture عند التنفيذ ← استرداد/إلغاء حسب الحاجة.

ما هو الـ base URL لـ API تمارا؟ التجريبي https://api-sandbox.tamara.co والإنتاج https://api.tamara.co. صادِق كل طلب بـ Authorization: Bearer {API_TOKEN}، واختبر على التجريبي أولاً.

لماذا علق طلب تمارا عند approved؟ لأنه لم يُستدعَ الـ Authorise. بعد webhook الـ order_approved يجب POST /orders/{order_id}/authorise؛ وإلا لا يُحصَّل الطلب ولا يُسوَّى أبداً.

هل تدعم تمارا WooCommerce و Shopify و سلة؟ نعم — تقدّم تمارا إضافات رسمية لـ Magento و WooCommerce و Shopify و سلة و OpenCart و PrestaShop و زد و Salesforce Commerce Cloud و ExpandCart وغيرها.

ما الدول والعملات التي تدعمها تمارا؟ السعودية (SAR)، الإمارات (AED)، البحرين (BHD)، الكويت (KWD)، وعُمان (OMR). وتستخدم BHD و KWD و OMR ثلاث خانات عشرية.

تحتاج تكامل تمارا منفّذاً بشكل صحيح؟

أبني وأصحّح تكاملات تمارا — API مباشر، وإضافات، وتدفّقات checkout مخصّصة — لمتاجر في مصر والخليج. تواصل معي إن أردت تنفيذه بشكل صحيح من أول مرة، أو انسخ الأداة مفتوحة المصدر ونفّذها بنفسك.