مركز المساعدة
تسجيل تسجيل الدخول
Developer Documentation

ادمج جيدوم بمتجرك
خلال دقائق

منظومة API بسيطة و قوية تتيح لك تقديم خاصية التقسيط بدون فوائد لعملائك مباشرة في صفحة الدفع. 5 endpoints فقط — توثيق واضح، أمثلة جاهزة، و دعم تقني مباشر.

كل ما يحتاجه التاجر لإضافة "ادفع لاحقاً"

نظام API مصمم للتجار العراقيين — سهل التركيب، آمن بالكامل، و متوافق مع كل منصات التجارة الإلكترونية.

تركيب سريع

5 endpoints فقط — تقدر تربط متجرك خلال يوم عمل واحد. توثيق واضح بالعربية مع أمثلة جاهزة.

أمان كامل

JWT tokens، HTTPS إلزامي، OTP لتأكيد كل عملية. كل المعاملات مشفّرة و موثّقة على عدة طبقات.

دفع فوري للتاجر

تستلم قيمة الطلب كاملةً من جيدوم فور إتمام الدفع. العميل يقسّط لجيدوم — التاجر يقبض كاش.

حماية التاجر والمشتري

منظومة حماية متكاملة ضد الاحتيال و حالات السرقة و التلف. تعويض عادل و معالجة سريعة للنزاعات.

REST API قياسي

JSON بسيط، HTTP methods متعارف عليها. تشتغل مع أي لغة برمجة أو إطار عمل — Node.js، PHP، Python، Java.

دعم تقني متخصص

فريق مطورين جاهز للرد بكل الاستفسارات. مساعدة بربط متجرك، تجربة sandbox، و حل أي مشكلة بسرعة.

منظومة الربط بـ 5 خطوات

من لحظة طلب التقسيط لإكمال الدفع — كل خطوة بـ endpoint واحد فقط. الـ flow بسيط ومتسلسل.

1
تسجيل الدخول POST
/api/jedoom/token

المتجر يطلب JWT Token باستخدام بيانات الاعتماد الخاصة بشركته. الـ Token صالح 24 ساعة و يُستخدم في الطلبات التالية.

2
التحقق من العميل POST
/api/jedoom/verify

العميل يُدخل Jedoom ID الخاص فيه، و النظام يتحقق من وجوده و يُرجع اسمه و رقم هاتفه (مُخفّى جزئياً) للعرض.

3
إرسال OTP POST
/api/jedoom/send-otp

يُرسل رمز تأكيد لرقم هاتف العميل المسجل في جيدوم. صلاحية الرمز 5 دقائق — لتأكيد موافقة العميل على العملية.

4
إنشاء قسط جديد POST
/api/merchant/create-installment

التاجر يُرسل OTP الذي أدخله العميل + بيانات الطلب. جيدوم تتحقق من صحة OTP تلقائياً، و إذا كان صحيح تُنشئ القسط مباشرة و تحسب القسط الشهري.

5
إنشاء جلسة الدفع POST
/api/payment/session

تُنشأ جلسة دفع و يُرجع رابط مباشر تُحوّل إليه العميل لإتمام الدفعة الأولى. بعد الإكمال يعود لمتجرك تلقائياً.

الـ Endpoints الخمسة

كل endpoint بطريقة الـ request، الـ response، و الأمثلة العملية.

1

تسجيل الدخول و الحصول على Token

POST /api/jedoom/token

احصل على JWT Token عبر بيانات اعتماد شركتك. الـ Token يُستخدم في كل الطلبات التالية و صلاحيته 24 ساعة.

الحقلالنوعإلزامي
companyIdUUID
companyAccessTokenstring
REQUEST Body
{
  "companyId": "YOUR_COMPANY_ID",
  "companyAccessToken": "YOUR_ACCESS_TOKEN"
}
RESPONSE 200 OK
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400,
    "company": "اسم الشركة"
  }
}
200 — Success 400 — Missing fields 401 — Invalid credentials 403 — Account not active
نصيحة: احفظ الـ Token في cache server-side و جدّده فقط عند انتهائه. لا تُرسله أبداً للـ frontend.
2

التحقق من هوية العميل

POST /api/jedoom/verify

تحقّق من وجود العميل في جيدوم بإدخال Jedoom ID الخاص فيه. يعود لك بالاسم و الهاتف المُخفّى جزئياً للعرض.

الحقلالنوعالوصف
jedoom_idstringمعرّف العميل (UUID أو JDM-XXXX-XXXX)
REQUEST Headers + Body
// Headers
Authorization: Bearer <JWT_TOKEN>

// Body
{
  "jedoom_id": "JDM-XXXX-XXXX"
}
RESPONSE 200 OK
{
  "success": true,
  "data": {
    "name": "اسم العميل",
    "phone_masked": "*******1234",
    "email": "customer@example.com"
  }
}
200 — Success 400 — Invalid format 401 — Expired token 404 — Not found
3

إرسال رمز التأكيد OTP

POST /api/jedoom/send-otp

يُرسل رمز OTP لرقم هاتف العميل المسجل في جيدوم. صالح 5 دقائق — لتأكيد موافقة العميل على إنشاء القسط.

REQUEST Body
{
  "jedoom_id": "JDM-XXXX-XXXX"
}
RESPONSE 200 OK
{
  "success": true,
  "data": {
    "sent": true,
    "phone_masked": "*******1234",
    "expires_in": 300
  }
}
200 — OTP sent 404 — User not found
⏱ تنبيه: لا يمكن إعادة الإرسال قبل مرور 60 ثانية. اعرض countdown timer للعميل في واجهتك.
4

إنشاء قسط جديد

POST /api/merchant/create-installment

أرسل بيانات الطلب مع رمز OTP الذي أدخله العميل — جيدوم تتحقق من صحته تلقائياً ثم تُنشئ القسط. القسط الشهري يُحسب تلقائياً.

الحقلالنوعالوصف
userIdUUID أو JDMمعرّف العميل (UUID أو JDM-XXXX-XXXX)
otpstringرمز OTP الذي أدخله العميل (6 أرقام)
amountnumberالمبلغ الإجمالي بالدينار العراقي
durationnumberعدد أشهر التقسيط (من 1 إلى 36)
notesstringملاحظات اختيارية (رقم الطلب مثلاً)
REQUEST Body
{
  "userId": "customer-uuid",
  "otp": "123456",
  "amount": 150000,
  "duration": 6,
  "notes": "Order #12345"
}
RESPONSE 201 Created
{
  "success": true,
  "data": {
    "id": "installment-uuid",
    "customer": "اسم العميل",
    "totalAmount": 150000,
    "monthlyAmount": 25000,
    "totalInstallments": 6,
    "status": "active",
    "startDate": "2026-06-05T00:00:00.000Z",
    "endDate": "2026-12-05T00:00:00.000Z"
  }
}
201 — Created 400 — Invalid OTP / data 404 — Customer not found
✓ OTP يُتحقق منه تلقائياً: ما تحتاج تتحقق من صحة OTP في نظامك — جيدوم تتحقق منه قبل إنشاء القسط. إذا كان غير صحيح أو منتهي الصلاحية، تُرجع خطأ 400 وما يُنشأ القسط.
5

إنشاء جلسة الدفع

POST /api/payment/session

أنشئ جلسة دفع و احصل على رابط مباشر تُحوّل إليه العميل لإكمال الدفعة الأولى. بعد الإكمال يعود لمتجرك.

الحقلالوصف
userIdمعرّف العميل
installmentIdمعرّف القسط (من الـ endpoint السابق)
successUrlرابط التحويل عند نجاح الدفع
failureUrlرابط التحويل عند فشل الدفع
RESPONSE 201 Created
{
  "success": true,
  "data": {
    "sessionId": "session-uuid",
    "paymentUrl": "https://jedoom.ai/payment?session=...",
    "expiresAt": "2026-06-05T13:00:00.000Z"
  }
}
201 — Session created 400 — Already paid
الخطوة الأخيرة: حوّل العميل لـ paymentUrl و انتظر رجوعه عبر successUrl أو failureUrl.

مثال كامل بـ JavaScript

كود جاهز للنسخ — يُظهر الـ flow الكامل من التحقق لإنشاء جلسة الدفع.

CODE Node.js Integration
// 1. الحصول على Token
const tokenRes = await fetch('https://jedoom.ai/api/jedoom/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    companyId: process.env.JEDOOM_COMPANY_ID,
    companyAccessToken: process.env.JEDOOM_ACCESS_TOKEN
  })
});
const { data: { token } } = await tokenRes.json();

// 2. التحقق من العميل
const verifyRes = await fetch('https://jedoom.ai/api/jedoom/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ jedoom_id: customerJedoomId })
});

// 3. إرسال OTP لهاتف العميل
await fetch('https://jedoom.ai/api/jedoom/send-otp', { /* ... */ });

// 4. إنشاء القسط — جيدوم تتحقق من OTP تلقائياً
const instRes = await fetch(
  'https://jedoom.ai/api/merchant/create-installment',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      companyId, companyAccessToken,
      userId: customerUuid,
      otp: customerOtpInput,  // الرمز اللي أدخله العميل
      amount: 150000,
      duration: 6,
      notes: 'Order #12345'
    })
  }
);
const { data: installment } = await instRes.json();

// 5. إنشاء جلسة الدفع و توجيه العميل
const sessionRes = await fetch('https://jedoom.ai/api/payment/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    companyId, companyAccessToken,
    userId: customerUuid,
    installmentId: installment.id,
    successUrl: 'https://yourstore.com/success',
    failureUrl: 'https://yourstore.com/failure'
  })
});
const { data: { paymentUrl } } = await sessionRes.json();

// ✅ حوّل العميل لإكمال الدفع
res.redirect(paymentUrl);

أفضل الممارسات

قواعد بسيطة تضمن لك ربط آمن و مستقر بالـ API.

افعل

استخدم HTTPS لكل الطلبات بدون استثناء
احفظ بيانات الاعتماد في environment variables
استخدم Token cache server-side لتقليل الطلبات
أرسل OTP الذي أدخله العميل مباشرة لجيدوم — لا تتحقق منه بنفسك
سجّل كل العمليات (logs) للمراجعة و التتبع
استخدم retry logic للأخطاء المؤقتة

لا تفعل

لا تكشف بيانات الاعتماد في الـ frontend
لا تحفظ JWT في localStorage أو cookies غير آمنة
لا تستخدم credentials في الـ URL query strings
لا تثق ببيانات الـ amount/duration من العميل
لا تحفظ OTP في قاعدة بياناتك — أرسله لجيدوم مباشرة
لا تُرسل العميل لـ payment.html بدون session

الأسئلة الشائعة

إجابات سريعة على أكثر الأسئلة شيوعاً عن الربط.

عادةً يوم عمل واحد للمطور لتركيب الـ 5 endpoints واختبارها. إذا تستخدم منصة جاهزة (Shopify, WooCommerce, ZID)، تتوفر إضافات جاهزة تقلل الوقت لساعات.
بعد التسجيل كتاجر و اعتماد حسابك من فريق جيدوم، تستلم بيانات الاعتماد عبر البريد الرسمي. يمكنك التسجيل عبر صفحة "انضم كتاجر" أو التواصل المباشر مع فريق الشراكات.
نعم — نوفّر بيانات اعتماد للاختبار في بيئة sandbox منفصلة، تتيح لك تجربة الـ flow الكامل بدون معاملات حقيقية. اطلبها مع بيانات الاعتماد الأساسية.
بعد إكمال العميل للدفعة الأولى و تسليم المنتج بنجاح، يتم تحويل قيمة الطلب الكاملة لحساب التاجر حسب جدول التسوية المتفق عليه (يومياً أو أسبوعياً).
جيدوم تُحوّل العميل تلقائياً لـ successUrl الذي حدّدته عند إنشاء الجلسة. كذلك، تتوفر لوحة تحكم للتاجر تعرض حالة كل الطلبات و الأقساط.
إذا تستخدم منصة جاهزة (Shopify, WooCommerce, Magento, ZID...) فعادة لا تحتاج — الإضافة جاهزة. للمتاجر المخصصة، تحتاج مطور بسيط لربط الـ 5 endpoints. فريقنا يساعد بكل الخطوات.

جاهز تبدأ؟

انضم لـ مئات التجار اللي حسّنوا مبيعاتهم مع جيدوم. سجّل اليوم و استلم بيانات الاعتماد و دعم تقني مباشر.