ابدأ

OneEntry Platform SDK هو SDK يوفر وسيلة سهلة للتفاعل مع واجهة برمجة تطبيقات OneEntry Platform.

---

🚀 بدء سريع

ابدأ العمل مع OneEntry في 3 خطوات بسيطة:

1️⃣ تثبيت الحزمة

  npm install oneentry

2️⃣ تهيئة SDK

  import { defineOneEntry } from 'oneentry';

  const api = defineOneEntry('your-project-url', {
    token: 'your-api-token'
  });

3️⃣ ابدأ باستخدام واجهة البرمجة

  // جلب المنتجات 
  const products = await api.Products.getProducts({ limit: 10 });

  // الحصول على ملف تعريف المستخدم
  const user = await api.Users.getUser();

  // إرسال نموذج
  const formData = await api.FormData.postFormsData('contact-form', {
    name: 'جون دو',
    email: 'john@example.com'
  });

🎉 هذا كل شيء! أنت جاهز لبناء تطبيقات مذهلة مع OneEntry.

---

✨ الميزات الرئيسية

🔐

مصادقة آمنة

إدارة رموز مدمجة ودعم OAuth

🌍

متعدد اللغات

دعم i18n مع اكتشاف اللغة تلقائيًا

📝

TypeScript

تعريفات نوع كاملة لتحسين تجربة المطور

⚡

خفيف الوزن

حجم حزمة محسّن للإنتاج

🔌

معمارية معيارية

24 وحدة متخصصة لجميع احتياجاتك

🛡️

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

معالجات أخطاء مخصصة ووضع shell

🌐 الموارد

🌍

الموقع الرسمي

تعرف على المزيد حول OneEntry Platform

🚀

سجل الآن

أنشئ حسابك المجاني

💻

Npmjs

تحميل SDK

🧪

JS SDK Sandbox

جرب طرق SDK مباشرة في متصفحك - لا حاجة للإعداد

📖 الاستخدام التفصيلي

جميع الوحدات المتاحة

استورد وفكك جميع الوحدات التي تحتاجها:

import { defineOneEntry } from 'oneentry'
const config = { 
  token: 'your-app-token', 
} 
const { 
  Admins, 
  AttributesSets, 
  AuthProvider, 
  Blocks, 
  Events, 
  FileUploading, 
  Forms, 
  FormData, 
  GeneralTypes, 
  ImmutableSettings, 
  IntegrationCollections, 
  Locales, 
  Menus, 
  Orders, 
  Pages, 
  Payments, 
  ProductStatuses, 
  Products, 
  Settings, 
  Sitemap, 
  System, 
  Templates, 
  TemplatePreviews, 
  Users, 
  WS 
} = defineOneEntry('your-url', config); 

أو

const config = {
  token: 'your-app-token',
};

const api = defineOneEntry('your-url', config);

---

التكوين

المعلمة الثانية من المُنشئ تأخذ 'config'. تحتوي على القيم التالية:

• 'token' - قم بتعيين مفتاح الرمز إذا كان مشروعك مؤمنًا بـ "رمز واجهة برمجة التطبيقات الأمنية". إذا كنت تستخدم حماية الشهادة، فلا تمرر هذه المتغير. يمكنك قراءة المزيد عن أمان مشروعك هنا.
• 'langCode' - قم بتعيين "langCode" لتعيين اللغة الافتراضية. من خلال تحديد هذه المعلمة مرة واحدة، لن تحتاج إلى تمرير langCode إلى طرق واجهة برمجة التطبيقات ONEENTRY. إذا لم تقم بتمرير اللغة الافتراضية، فسيتم تعيينها إلى "en_US".
• 'traficLimit' - تستخدم بعض الطرق أكثر من طلب واحد إلى OneEntry بحيث تكون البيانات التي تتلقاها كاملة وسهلة العمل معها. مرر القيمة "true" لهذه المعلمة لتوفير حركة المرور وقرر بنفسك ما هي البيانات التي تحتاجها. القيمة الافتراضية "false".
• 'rawData' - عند تعيينها إلى false (افتراضي)، يقوم SDK تلقائيًا بتحويل مصفوفة additionalFields إلى كائن مفاتيحه marker لسهولة الوصول. قم بتعيينها إلى true لتلقي additionalFields كمصفوفة أصلية من واجهة برمجة التطبيقات.
• 'auth' - كائن بإعدادات التفويض. بشكل افتراضي، يتم تكوين SDK للعمل مع الرموز داخل جلسة المستخدم ولا يتطلب أي عمل إضافي منك. في نفس الوقت، لا يخزن SDK حالة الجلسة بين الجلسات. إذا كنت راضيًا عن هذه الإعدادات، فلا تمرر المتغير 'auth' على الإطلاق.

يحتوي 'auth' على الإعدادات التالية:

• 'refreshToken' - رمز التحديث الخاص بالمستخدم. قم بنقله هنا من المستودع لاستعادة جلسة المستخدم أثناء التهيئة.
• 'saveFunction' - دالة تعمل مع تحديث رمز التحديث. إذا كنت ترغب في تخزين الرمز بين الجلسات، على سبيل المثال في التخزين المحلي، مرر دالة هنا تقوم بذلك. يجب أن تقبل الدالة معلمة سيتم تمرير السلسلة التي تحتوي على الرمز إليها.
• 'customAuth' - إذا كنت ترغب في تكوين التفويض والعمل مع الرموز بنفسك، قم بتعيين هذه العلامة إلى true. إذا كنت ترغب في استخدام إعدادات sdk، قم بتعيينها إلى false أو لا تمررها على الإطلاق.
• 'providerMarker' - العلامة لمزود التفويض. الافتراضي: 'email'. مثال على تكوين مع حماية الرمز والمصادقة التلقائية التي تخزن الحالة بين الجلسات

const tokenFunction = (token) => {
  localStorage.setItem('refreshToken', token);
};

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  langCode: 'en_US',
  auth: {
    refreshToken: localStorage.getItem('refreshToken'),
    saveFunction: tokenFunction,
    providerMarker: 'email'
  },
});

مثال على تكوين محمي بشهادة يسمح لك بتكوين نظام التفويض بنفسك ويحفظ البيانات على الطلبات.

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  langCode: 'en_US',
  traficLimit: true,
  auth: {
    customAuth: true,
    refreshToken: localStorage.getItem('refreshToken'),
    providerMarker: 'email'
  },
});

إذا اخترت تكوين الرموز بنفسك، يمكنك تمرير الرمز إلى الطريقة كما يلي. تسمح لك الطريقة الوسيطة بتمرير رمز الوصول إلى الطلب. ثم استدعِ الطريقة المطلوبة. يجب ألا يتم استدعاء هذه الطريقة (setAccessToken) إذا كانت الطريقة لا تتطلب مصادقة المستخدم.

const user = api.Users.setAccessToken('my.access.token').getUser();

إذا اخترت حماية الرمز لضمان أمان الاتصال، فقط مرر رمزك إلى الدالة كمعلمة اختيارية.

يمكنك الحصول على رمز كما يلي

1. قم بتسجيل الدخول إلى حسابك الشخصي
2. انتقل إلى علامة التبويب "المشاريع" واختر مشروعًا
3. انتقل إلى علامة التبويب "الوصول"
4. قم بتعيين المفتاح إلى "رمز واجهة برمجة التطبيقات الأمنية"
5. قم بتسجيل الدخول إلى المشروع، وانتقل إلى قسم الإعدادات وافتح علامة التبويب الخاصة بالرمز
6. احصل على رمز مشروعك وانسخه

يمكنك أيضًا توصيل شهادة tls لحماية مشروعك. في هذه الحالة، لا تمرر "token" على الإطلاق. عند استخدام الشهادة، قم بإعداد وكيل في مشروعك. مرر سلسلة فارغة كمعلمة url. تعرف على المزيد حول شهادة mtls

const saveTokenFromLocalStorage = (token) => {
  localStorage.setItem('refreshToken', token);
};

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  auth: {
    customAuth: false,
    userToken: 'rerfesh.token',
    saveFunction: saveTokenFromLocalStorage,
    providerMarker: 'email'
  },
});

التحقق من استجابة واجهة البرمجة

يتضمن OneEntry SDK التحقق الاختياري من استجابات واجهة البرمجة باستخدام Zod، مكتبة التحقق من المخططات التي تركز على TypeScript. تساعد هذه الميزة في ضمان سلامة البيانات وأمان النوع عند العمل مع استجابات واجهة البرمجة.

الميزات

• اختياري: التحقق معطل بشكل افتراضي ويمكن تمكينه حسب التكوين
• آمن من حيث النوع: يستخدم مخططات Zod التي تتماشى مع واجهات TypeScript
• وضعان: وضع ناعم (يسجل الأخطاء) ووضع صارم (يعيد الأخطاء)
• عدم وجود عبء وقت التشغيل عند تعطيله: لا يؤثر على الأداء إذا تم إيقاف التحقق

التكوين

قم بتمكين التحقق عن طريق إضافة خاصية validation إلى تكوين SDK الخاص بك:

import { defineOneEntry } from 'oneentry'

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,        // تمكين التحقق (افتراضي: false)
    strictMode: false,    // وضع صارم (افتراضي: false)
    logErrors: true,      // سجل أخطاء التحقق (افتراضي: true)
  }
})

خيارات التكوين

الخيار	النوع	الافتراضي	الوصف
enabled	boolean	false	تمكين/تعطيل التحقق من الاستجابة
strictMode	boolean	false	عند true، يعيد IError عند فشل التحقق. عند false، يسجل الأخطاء ويعيد البيانات الأصلية
logErrors	boolean	true	سجل أخطاء التحقق في وحدة التحكم (مفيد للتصحيح)

أوضاع التحقق

الوضع الناعم (افتراضي)

عندما يكون strictMode هو false، يتم تسجيل أخطاء التحقق في وحدة التحكم، ولكن يتم إرجاع استجابة واجهة البرمجة الأصلية دون تغيير. هذا مفيد أثناء التطوير لتحديد عدم التناسق المحتمل في البيانات دون كسر تطبيقك.

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,
    strictMode: false,  // وضع ناعم
    logErrors: true,
  }
})

// حتى إذا فشل التحقق، ستحصل على استجابة واجهة البرمجة
const user = await api.Users.getUser()
// ستظهر وحدة التحكم أخطاء التحقق إذا كانت موجودة

الوضع الصارم

عندما يكون strictMode هو true، تعيد حالات فشل التحقق كائن IError بدلاً من البيانات. يضمن ذلك أن تطبيقك يعالج فقط البيانات التي تم التحقق منها.

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  validation: {
    enabled: true,
    strictMode: true,   // وضع صارم
    logErrors: true,
  }
})

const user = await api.Users.getUser()

// تحقق مما إذا كانت الاستجابة خطأ
if ('statusCode' in user) {
  console.error('فشل التحقق:', user.message)
} else {
  // آمن من حيث النوع: المستخدم هو IUserEntity
  console.log('المستخدم:', user.email)
}

---

تنسيق الحقول الإضافية

بشكل افتراضي، يقوم SDK بتحويل خاصية additionalFields من مصفوفة (كما تم إرجاعها بواسطة واجهة البرمجة) إلى كائن مفاتيحه marker. يجعل هذا من السهل الوصول إلى حقول معينة دون معرفة فهرسها.

السلوك الافتراضي (rawData: false)

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  // rawData هو false بشكل افتراضي - لا حاجة لتمريره بشكل صريح
})

// additionalFields هو كائن مفاتيحه marker:
const field = attribute.additionalFields['my_field']
console.log(field.value)  // وصول مباشر، لا حاجة للبحث في المصفوفة

الوضع الخام (rawData: true)

إذا كنت بحاجة إلى تنسيق استجابة واجهة البرمجة الأصلية (على سبيل المثال، للتوافق مع الإصدارات السابقة)، قم بتعيين rawData: true:

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  rawData: true,
})

// additionalFields هي المصفوفة الأصلية من واجهة البرمجة:
const field = attribute.additionalFields.find(f => f.marker === 'my_field')
console.log(field.value)

خيار التكوين

الخيار	النوع	الافتراضي	الوصف
rawData	boolean	false	عندما يكون false، يتم تحويل additionalFields إلى كائن مفاتيحه marker. عندما يكون true، يتم إرجاع المصفوفة الأصلية من واجهة البرمجة.

---

الأخطاء

إذا كنت ترغب في الهروب من الأخطاء داخل sc، اترك خاصية "errors" بشكل افتراضي. في هذه الحالة، ستحصل على بيانات الكيان أو كائن الخطأ. تحتاج إلى إجراء تحقق من النوع. على سبيل المثال، من خلال التحقق من خاصية statusCode باستخدام ".hasOwnProperty"

ومع ذلك، إذا كنت ترغب في استخدام البناء "try catch(e) ", قم بتعيين خاصية "isShell" إلى القيمة "false". في هذه الحالة، تحتاج إلى معالجة الخطأ باستخدام "try catch(e) ".

أيضًا، يمكنك تمرير دوال مخصصة سيتم استدعاؤها داخل sdk مع رمز الخطأ المناسب. تستقبل هذه الدوال كائن الخطأ كوسيط. يمكنك معالجته بنفسك.

const api = defineOneEntry('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  errors: {
    isShell: false,
    customErrors: {
      400: (error) => console.error('طلب غير صالح:', error.message),
      401: (error) => console.error('غير مصرح:', error.message),
      403: (error) => console.error('ممنوع:', error.message),
      404: (error) => console.error('غير موجود:', error.message),
      429: (error) => console.error('تجاوز حد المعدل:', error.message),
      500: (error) => console.error('خطأ في الخادم:', error.message),
      502: (error) => console.error('بوابة سيئة:', error.message),
      503: (error) => console.error('الخدمة غير متاحة:', error.message),
      504: (error) => console.error('انتهاء مهلة البوابة:', error.message),
    },
  },
})

عندما يتم تعيين خيار isShell: false في تكوين SDK، يكون له التأثير التالي:

عندما يحدث خطأ في طلبات واجهة البرمجة (مثل أخطاء HTTP 400، 401، 404، 500، إلخ، أو أخطاء الشبكة)، سيقوم SDK بإلقاء استثناء بدلاً من إرجاع كائن الخطأ كقيمة عادية.

هذا يسمح لك باستخدام بناء try/catch في كود تطبيقك لمعالجة الأخطاء:

try {
  const result = await api.someMethod();
  // معالجة نتيجة ناجحة
} catch (error) {
  // معالجة الخطأ
}

إذا كان isShell: true، يتم إرجاع الأخطاء كقيم، وستحتاج إلى التحقق صراحة من نوع النتيجة للتحقق:

const result = await api.someMethod();
if ('statusCode' in result) { // يفترض وجود خاصية statusCode في كائن الخطأ
  // معالجة الخطأ
} else {
  // معالجة نتيجة ناجحة
}

وبالتالي، يسمح isShell: false بنموذج معالجة الأخطاء الأكثر ألفة باستخدام try/catch، بينما يوفر isShell: true نموذجًا مسطحًا حيث يتم إرجاع الأخطاء والنجاح كقيم من نفس النوع.

عند استخدام SDK مع الإعداد الافتراضي (isShell مضبوط على true)، يتم إرجاع الأخطاء كقيم بدلاً من إلقائها كاستثناءات. هذا يعني أن التطبيق لن يتعطل بسبب الاستثناءات غير المعالجة، لأن الأخطاء تتم معالجتها كجزء من تدفق التنفيذ العادي. إليك كيفية معالجة الأخطاء على الواجهة الأمامية دون استخدام try/catch:

تحقق من نوع الإرجاع بعد استدعاء طريقة واجهة البرمجة:

const result = await api.someMethod();

// تحقق مما إذا كانت النتيجة خطأ
if ('statusCode' in result || 'message' in result) {
  // معالجة الخطأ
  console.error('خطأ:', result);
} else {
  // معالجة نتيجة ناجحة
  console.log('نجاح:', result);
}

يمكنك أيضًا إنشاء نوع استخدام utils "IError" للتحقق من الأخطاء:

import type { IError } from '../base/utils';

function isErrorResult(result: any): result is IError {
  return result && typeof result === 'object' && 
         (result.hasOwnProperty('statusCode') || 
          result.hasOwnProperty('message'));
}

// ثم استخدمه هكذا:
const result = await api.someMethod();

if (isErrorResult(result)) {
  // معالجة الخطأ
  console.error('حدث خطأ:', result);
} else {
  // معالجة نتيجة ناجحة
  console.log('نتيجة ناجحة:', result);
}

تسمح لك هذه الطريقة بتجنب استخدام بناء try/catch بينما لا تزال تعالج الأخطاء بشكل صحيح، مما يمنع التطبيق من التعطل.

---

📚 الخطوات التالية

استكشف أدلتنا الشاملة لمعرفة المزيد:

🛍️

التجارة الإلكترونية

بناء كتالوجات المنتجات مع التصفية والبحث

👤

إدارة المستخدمين

تنفيذ المصادقة وملفات تعريف المستخدمين

🛒

الطلبات والدفع

معالجة الطلبات والتعامل مع المدفوعات

📄

الصفحات والمحتوى

إدارة الصفحات الديناميكية وهياكل المحتوى

📝

النماذج

تعلم كيفية التعامل مع النماذج

📝

بيانات النماذج

تعلم كيفية التعامل مع بيانات النماذج

---