Portal SDK (TypeScript)

SDK JavaScript/TypeScript خفيف الوزن لدمج بوابة الدفع إيصالات في تطبيق الويب الخاص بك.

البداية

قم بتثبيت إيصالات Portal SDK باستخدام npm أو yarn. تم تصميم هذا SDK لتطبيقات الويب الأمامية.

Installation

npm install @Esaalat/portal-sdk

بداية سريعة

افتح بوابة الدفع باستدعاء دالة بسيط:

import { openCheckoutPortal } from '@Esaalat/portal-sdk';

const controller = openCheckoutPortal({
  onSuccess: () => {
    console.log('Checkout successful!');
  },
  onComplete: () => {
    console.log('Payment completed!');
  },
  onClose: () => {
    console.log('Portal closed');
  }
});

💡 ملاحظة: تفتح البوابة في نافذة منبثقة. تأكد من عدم حظر النوافذ المنبثقة بواسطة المتصفح.

الاستخدام الأساسي

تفتح الدالة openCheckoutPortal بوابة الدفع وتعيد وحدة تحكم لإدارتها.

مثال بسيط

import { openCheckoutPortal } from '@Esaalat/portal-sdk';

// Basic usage
const controller = openCheckoutPortal({
  onComplete: () => {
    alert('Payment completed successfully!');
  }
});

مع عنوان URL أساسي مخصص

قم بتخصيص عنوان URL للبوابة إذا لزم الأمر:

const controller = openCheckoutPortal({
  events: {
    onComplete: handleComplete,
    onClose: handleClose
  },
  baseUrl: 'https://custom-checkout.esaalat.com' // api.sandbox.esaalat.com for sandbox
});

طرق وحدة التحكم

توفر وحدة التحكم المعادة طرقًا لإدارة البوابة:

// Close the portal programmatically
controller.close();

// Clean up event listeners
controller.cleanup();

ردود نداء الأحداث

تعامل مع أحداث البوابة المختلفة باستخدام دوال رد النداء:

import { openCheckoutPortal } from '@Esaalat/portal-sdk';

const controller = openCheckoutPortal({
  onSuccess: () => {
    // Called when checkout succeeds
    console.log('Checkout successful!');
  },
  onComplete: () => {
    // Called when payment completes
    console.log('Payment completed!');
    // Update UI, redirect user, etc.
  },
  onClose: () => {
    // Called when portal is closed
    console.log('Portal closed');
    // Clean up, show message, etc.
  }
});

الأحداث المتاحة

onSuccess

يتم استدعاؤه عند نجاح الدفع

onComplete

يتم استدعاؤه عند اكتمال الدفع

onClose

يتم استدعاؤه عند إغلاق البوابة

onCreateOrder

يتم استدعاؤه عندما تطلب البوابة إنشاء طلب (يجب أن يعيد Promise<string>)

معلمات الاستعلام

مرر بيانات إضافية إلى البوابة باستخدام معلمات الاستعلام:

With Query Parameters

const controller = openCheckoutPortal(
  {
    onSuccess: handleSuccess,
    onClose: handleClose
  },
  {
    product_id: '123',
    amount: '99.99',
    currency: 'USD',
    customer_email: 'user@example.com'
  }
);

صيغة بديلة

يمكنك أيضًا استخدام صيغة كائن الخيارات:

const controller = openCheckoutPortal({
  events: {
    onSuccess: handleSuccess,
    onClose: handleClose
  },
  queryParams: {
    product_id: '123',
    amount: '99.99',
    currency: 'USD'
  }
});

إنشاء الطلب

اسمح للبوابة بطلب إنشاء الطلب ديناميكيًا باستخدام رد النداء onCreateOrder:

Dynamic Order Creation

const controller = openCheckoutPortal({
  onCreateOrder: async () => {
    // Call your backend API to create an order
    const response = await fetch('/api/orders', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [
          {
            name: 'Product',
            description: 'Description',
            price: 99.99,
            quantity: 1
          }
        ],
        currency: 'USD'
      })
    });
    
    const data = await response.json();
    
    // Return the order ID
    return data.orderId;
  },
  onSuccess: () => {
    console.log('Order created and paid!');
  }
});

⚠️ هام: يجب أن يعيد رد النداء onCreateOrder وعدًا (Promise) يحل إلى سلسلة نصية (معرف الطلب).

الاستخدام المتقدم

التحقق من الأصل

قم بتمكين التحقق من الأصل لتعزيز الأمان:

const controller = openCheckoutPortal({
  events: {
    onComplete: handleComplete
  },
  validateOrigin: true,
  allowedOrigins: [
    'https://yourdomain.com',
    'https://portal.yourdomain.com'
  ]
});

التحكم البرمجي

تحكم في البوابة برمجياً:

const controller = openCheckoutPortal({
  onSuccess: () => {
    // Close portal after success
    controller.close();
  }
});

// Close after timeout
setTimeout(() => {
  controller.close();
}, 60000);

// Clean up when component unmounts (React example)
useEffect(() => {
  return () => {
    controller.cleanup();
  };
}, []);

تكامل React

مثال على دمج SDK في مكون React:

import { useState, useEffect } from 'react';
import { openCheckoutPortal } from '@Esaalat/portal-sdk';

function CheckoutButton() {
  const [controller, setController] = useState(null);

  const handleCheckout = () => {
    const ctrl = openCheckoutPortal({
      onComplete: () => {
        alert('Payment completed!');
        ctrl.close();
      },
      onClose: () => {
        console.log('Portal closed');
      }
    });
    
    setController(ctrl);
  };

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (controller) {
        controller.cleanup();
      }
    };
  }, [controller]);

  return (
    <button onClick={handleCheckout}>
      Checkout
    </button>
  );
}

معالجة الأخطاء

تعامل مع الأخطاء الشائعة بسلاسة:

try {
  const controller = openCheckoutPortal({
    onCreateOrder: async () => {
      const response = await fetch('/api/orders', {
        method: 'POST',
        body: JSON.stringify({ items: cartItems })
      });
      
      if (!response.ok) {
        throw new Error('Failed to create order');
      }
      
      const data = await response.json();
      return data.orderId;
    },
    onComplete: () => {
      console.log('Payment completed!');
    }
  });
} catch (error) {
  console.error('Portal error:', error.message);
  alert('Failed to open checkout. Please try again.');
}

مشاكل شائعة

تم حظر النافذة المنبثقة

حظر المتصفح النافذة المنبثقة. تأكد من استدعاء الدالة استجابة لإجراء المستخدم (مثل النقر على زر).

معرف طلب غير صالح

أعاد رد النداء onCreateOrder قيمة غير صالحة. تأكد من أنه يعيد وعدًا يحل إلى سلسلة نصية.

أصل غير مصرح به

تم استلام رسالة من أصل غير مسموح به. تحقق من تكوين allowedOrigins الخاص بك.