تكامل API سمة: طلب التقارير الائتمانية لفنتك السعودية

كل منتج إقراضي تطوره في المملكة العربية السعودية يمر بـسمة — الشركة السعودية للمعلومات الائتمانية. لا توجد طريقة للتحايل: تشترط أنظمة ساما الاستعلام عن المعلومات الائتمانية من جهة مرخصة قبل منح أي تمويل، وسمة هي الجهة الوحيدة المرخصة في المملكة. ما لا تقدمه الأنظمة هو دليل المطور. هذا هو ذلك الدليل.

ما هي سمة فعلاً؟

سمة (الشركة السعودية للمعلومات الائتمانية) هي شركة المعلومات الائتمانية الوحيدة المرخصة في المملكة، تأسست عام 2002 بمشاركة تسعة بنوك سعودية، وتعمل تحت إشراف البنك المركزي السعودي (ساما). تجمع شبكة FINDATA بيانات من نحو 330 مصدراً — بنوك، شركات اتصالات، مزودو خدمات، وجهات حكومية — لإنتاج التقارير الائتمانية التي يلتزم كل مُقرض بالاطلاع عليها قبل منح أي تمويل.

من منظور المطور، هذه هي المصادر الرئيسية التي ستستهلكها:

• تاريخ الائتمان — التسهيلات النشطة والمُسددة، سلوك السداد عبر جميع البنوك السعودية
• تقييم سمة — نموذج التقييم الاحتكاري للمؤسسات المُقرضة
• درجة ملم — الدرجة الائتمانية المتاحة للأفراد عبر تطبيق ملم
• الأرصدة القائمة — المدخل الأساسي لحساب نسبة الدين للدخل (DBR) الإلزامية

بوابة الوصول: عضوية مؤسسية لا API مفتوح

على عكس إطار الخدمات المصرفية المفتوحة لساما الذي يعتمد OAuth 2.0، وصول سمة محصور على الأعضاء المؤسسيين:

النقطة الجوهرية: لا يمكنك الاستعلام من سمة مباشرةً حتى تحصل شركتك على ترخيص إقراض أو خدمات مصرفية مفتوحة من ساما. الشركات الناشئة في مراحلها المبكرة تلجأ إلى وسيط مرخص يملك عضوية سمة المؤسسية.

منتجات سمة التي ستستخدمها

التقرير الائتماني الفردي

يحتوي التقرير الكامل على:

• جميع التسهيلات الائتمانية النشطة (قروض، بطاقات ائتمان، خطوط BNPL)
• التسهيلات المُسددة خلال العشر سنوات الماضية
• سجلات التعثر والتأخر في السداد مع تفاصيل التقادم
• الأحكام القضائية المتعلقة بالالتزامات الائتمانية
• سجل الاستعلامات (الاستعلامات المتكررة تُخفض درجة التقييم)

تقييم سمة

نموذج تسجيل احتكاري ذو ثلاثة أرقام. نطاق الدرجات وتفسيرها لا يُفصح عنه علنياً — يُوضح فقط في اتفاقية العضوية مع المؤسسات المُقرضة.

تقارير قطاع الأعمال (SIMAT)

للإقراض بين المؤسسات والائتمان التجاري:

• حالة السجل التجاري وهيكل الملكية
• التسهيلات الائتمانية للكيان التجاري
• سلوك السداد مع البنوك وكبار الموردين

حساب نسبة الدين للدخل: لماذا كل تكامل يبدأ هنا؟

تُلزم لائحة التمويل الشخصي الصادرة عن ساما بألا تتجاوز نسبة الدين للدخل (DBR) 33% من صافي الراتب الشهري لمعظم منتجات الائتمان الاستهلاكي (50% للرهن العقاري). هذا التزام تنظيمي صارم لا إرشادياً. تقرير سمة يعطيك البيانات الخام لحسابه:

interface DBRInput {
  monthlyNetIncome: number;           // من WPS أو قوى للتحقق من الدخل
  existingMonthlyObligations: number; // من التسهيلات النشطة في سمة
  proposedInstalment: number;         // من آلة حساب التمويل لديك
}
 
function calculateDBR(input: DBRInput): {
  dbr: number;
  approved: boolean;
  remainingCapacity: number;
} {
  const total = input.existingMonthlyObligations + input.proposedInstalment;
  const dbr = total / input.monthlyNetIncome;
  const maxObligations = input.monthlyNetIncome * 0.33;
  return {
    dbr,
    approved: dbr <= 0.33,
    remainingCapacity: maxObligations - input.existingMonthlyObligations,
  };
}

سمة تمنحك existingMonthlyObligations من بيانات التسهيلات النشطة. أما monthlyNetIncome فيأتي من استعلام منفصل — عادةً من نظام حماية الأجور (راجع تسوية بيانات الرواتب عبر WPS) أو من بيانات توظيف قوى.

التسلسل المُثبت في الإنتاج: التحقق من الهوية بنفاذ ← التحقق من التوظيف والدخل بقوى ← التقرير الائتماني من سمة ← حساب نسبة DBR ← نموذج الائتمان الداخلي ← القرار والعرض.

بنية التكامل للمُقرضين المرخصين من ساما

بعد الحصول على بيانات اعتماد العضوية في سمة، يتبع التكامل نمط REST المعتاد:

interface SimahCreditRequest {
  nationalId: string;      // الهوية الوطنية السعودية أو الإقامة
  memberCode: string;      // رمز مؤسستك كعضو في سمة
  requestType: "INDIVIDUAL" | "BUSINESS";
  consentToken: string;    // مرجع موافقة العميل (إلزامي بموجب ساما)
}
 
interface CreditFacility {
  facilityType: string;
  lenderName: string;
  outstandingBalance: number;
  monthlyInstalment: number;
  paymentStatus: "CURRENT" | "DELINQUENT" | "DEFAULTED";
  openedAt: string;
}
 
interface SimahCreditResponse {
  reportId: string;
  customerId: string;
  creditScore: number | null;
  activeFacilities: CreditFacility[];
  settledFacilities: CreditFacility[];
  totalOutstandingBalance: number;
  monthlyObligations: number;
  defaultRecords: DefaultRecord[];
  inquiries: Inquiry[];
  generatedAt: string;
}

المصادقة تعتمد على mTLS (بروتوكول TLS المتبادل بالشهادات الرقمية) لـ API سمة المباشر — تُصدر الشهادات خلال عملية الانضمام إلى سمة بعد اعتماد العضوية. مسارات الوسطاء تُضيف طبقة OAuth 2.0 فوق ذلك، متوافقةً مع إطار الخدمات المصرفية المفتوحة الذي دخل حيز التنفيذ الرسمي في مارس 2026.

أخطاء الإنتاج التي تفاجئ المطورين

العملاء غير المرئيين ائتمانياً

سمة تُعيد استجابة "لا يوجد سجل" للأفراد الذين لا يملكون تاريخاً ائتمانياً — شائع بين حديثي التخرج والسيدات الداخلات حديثاً لسوق العمل والمقيمين الجدد. هذه ليست خطأ — بل تعني أن العميل غير مرئي ائتمانياً.

async function querySimah(
  request: SimahCreditRequest
): Promise<SimahCreditResponse | null> {
  const response = await simahClient.getCreditReport(request);
 
  if (response.status === "NO_RECORD") {
    // غير مرئي ائتمانياً: توجيه لنموذج البيانات البديلة أو ملف التسجيل الرفيع
    return null;
  }
 
  if (response.status === "CONSENT_REQUIRED") {
    // الموافقة غير نشطة — إعادة تشغيل مسار الموافقة
    throw new ConsentRequiredError(request.nationalId);
  }
 
  return response.data;
}

سياسة الإقراض لديك يجب أن تُعالج ملفات التسجيل الرفيعة صراحةً. الرفض دون تفسير يُشكّل مخاطرة في الامتثال لمتطلبات ساما المتعلقة بالعدالة في الإقراض.

الموافقة إلزامية — ليست اختيارية

تشترط ساما الحصول على موافقة صريحة وموثقة من العميل قبل كل استعلام عن مكتب الائتمان. API سمة يُطبق هذا عبر رمز موافقة (consent token). المخالفة هنا مخالفة تنظيمية — ساما تملك صلاحية مراجعة سجلات الوصول وسحب ترخيص الوصول للبيانات.

التكرار والأحادية

توافر سمة في بيئة الإنتاج يتبع مستويات خدمة الجهات الحكومية، لا مستويات خدمة فنتك السحابية. ابنِ طبقة إعادة محاولة مع انتظار تصاعدي، واحتفظ بكل reportId حتى لا تستعلم مرة أخرى لقرار مكتمل. الاستعلامات الزائدة تُخفض درجة تقييم المتقدم.

مسار ما قبل الترخيص: الوسطاء

إذا كان ترخيص ساما لا يزال قيد الإجراءات، يمكنك تطوير واختبار نموذج الائتمان عبر وسطاء مرخصين:

• علم / وثق — شبكة وسطاء البيانات الحكومية؛ بعض منتجات سمة متاحة من خلال كتالوج خدماتهم إلى جانب بيانات السجل التجاري وبيانات العمل
• HES LoanBox / Lendsqr — منصات إنشاء القروض التي تدمج استعلامات سمة في SDK الإقراض الخاص بها
• مزودو AIS المرخصون من ساما (إطار 2026) — مزودو خدمات معلومات الحسابات المرخصون القادرون على الوصول إلى تدفقات البيانات الائتمانية

وصول الوسطاء يحمل تكلفة إضافية مقارنة بالوصول المباشر، لكنه يُتيح بناء واختبار نموذج ائتماني حقيقي — بما في ذلك حسابات DBR الفعلية — قبل اعتماد ترخيصك.

ما يجب قراءته قبل البناء

سمة لا تملك بوابة مطورين عامة. مخططات API وبيانات الاعتماد التجريبية ووثائق نموذج التقييم تُصدر فقط بعد توقيع اتفاقية العضوية. قبل ذلك، الوثائق الثلاث الضرورية:

1. نظام المعلومات الائتمانية (المرسوم الملكي م/37) — يُحدد ما يحق لأعضاء سمة الاستعلام عنه وتخزينه ومشاركته
2. لائحة التمويل الشخصي لساما — حدود نسبة DBR، متطلبات الموافقة، وإشعارات الرفض
3. إطار الخدمات المصرفية المفتوحة لساما (2026) — معايير OAuth 2.0 والموافقة وأمان API

ربط المنظومة التنظيمية الكاملة

سمة تقع في منتصف منظومة بيانات تنظيمية أشمل. التكامل الذي يعمل منفرداً نادراً ما يعمل في الإنتاج إذا لم تُوصَل به خطوات التحقق من الهوية والدخل:

• التحقق من الدخل ← تكامل قوى لبيانات التوظيف
• إثبات الراتب ← تسوية بيانات نظام حماية الأجور
• فاتورة الأعمال ← دليل تكامل فاتورة ZATCA

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