معروف + واثق: التحقق من السجل التجاري السعودي برمجياً عبر API

عندما تبني منصة سوق إلكتروني أو بوابة دفع أو منصة مشتريات B2B في المملكة العربية السعودية، تصطدم بمتطلب تنظيمي تتجاهله معظم الوثائق: يجب أن تتحقق من أن كل تاجر يمتلك سجلاً تجارياً نشطاً وأن نشاطه التجاري الإلكتروني موثّق على منصة الأعمال (التي كانت تُعرف سابقاً بمنصة معروف). شارة معروف تُشير لعملاء السعودية إلى أن المتجر مرخّص، وبوابات الدفع باتت تشترطها قبل إتمام تأهيل التجار.

المشكلة أن التحقق الرسمي في المملكة موزّع على نظامين:

1. السجل التجاري — تديره وزارة التجارة
2. منصة معروف ← منصة الأعمال — طبقة توثيق التجارة الإلكترونية (انتقلت إليها في مارس 2023)

لا يوفر النظامان واجهة REST مفتوحة للعموم. المسار البرمجي يمر عبر واثق — بوابة بيانات الأعمال السعودية الرسمية على developer.wathq.sa.

يوضح هذا الدليل كيفية التكامل مع واثق لبناء منظومة تحقق آني من التجار باستخدام TypeScript.

ما هي منصة معروف وماذا تغيّر في 2023؟

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

في مارس 2023، نقلت الوزارة توثيق المتاجر الإلكترونية إلى منصة الأعمال (business.sa)، التي تديرها هيئة الأعمال السعودية. شارة معروف لا تزال تظهر على المتاجر الموثّقة سابقاً، لكن التسجيلات الجديدة والتجديدات باتت تسير عبر business.sa. من زاوية المستخدم لم يتغيّر شيء. من زاوية المطوّر الذي يبني منظومة تحقق، المسار الصحيح الآن:

رقم السجل التجاري ← API واثق ← تأكيد الحالة النشطة + نشاط التجارة الإلكترونية

منصة واثق: بوابة بيانات الأعمال السعودية

تعمل واثق ضمن المنظومة الحكومية وتوفر نقطة وصول موحّدة وموثّقة لمصادر بيانات حكومية متعددة. API السجل التجاري — الإصدار 6.7.0 وقت كتابة هذا الدليل — هو الخدمة المطلوبة للتحقق من التجار.

خطوات الوصول:

1. أنشئ حساباً على developer.wathq.sa
2. اشترك في خدمة API السجل التجاري (بيئة الاختبار متاحة)
3. احصل على بيانات اعتماد Bearer token
4. انتقل إلى بيئة الإنتاج بعد اكتمال الاختبار

نقاط النهاية الأساسية:

يقبل المعامل id قيمتين:

• رقم السجل التجاري المؤلف من 10 أرقام (صيغة: 10xxxxxxxx)
• الرقم الوطني الموحّد المؤلف من 10 أرقام (صيغة: 700xxxxxxx) — مطلوب للسجلات النشطة والمعلّقة

التكامل بـ TypeScript

التحقق الأساسي من السجل التجاري

const WATHQ_BASE = process.env.WATHQ_BASE_URL!;
const WATHQ_TOKEN = process.env.WATHQ_API_TOKEN!;
 
interface CRInfo {
  crNumber: string;
  crName: string;
  status: string; // 'Active' | 'Expired' | 'Cancelled'
  activities: string[];
  issuanceDate: string;
  expiryDate: string;
}
 
async function verifyCR(id: string, lang: 'ar' | 'en' = 'ar'): Promise<CRInfo> {
  const res = await fetch(`${WATHQ_BASE}/info/${id}?language=${lang}`, {
    headers: {
      Authorization: `Bearer ${WATHQ_TOKEN}`,
      'Content-Type': 'application/json',
    },
  });
 
  if (res.status === 404) throw new Error('CR_NOT_FOUND');
  if (res.status === 401) throw new Error('WATHQ_AUTH_FAILED');
  if (res.status === 429) throw new Error('WATHQ_QUOTA_EXCEEDED');
  if (!res.ok) throw new Error(`WATHQ_ERROR_${res.status}`);
 
  return res.json();
}

منظومة تأهيل التجار الكاملة

interface OnboardingResult {
  valid: boolean;
  crStatus: string;
  errorCode?: string;
}
 
async function onboardSaudiMerchant(
  crNumber: string,
  nationalId: string
): Promise<OnboardingResult> {
  // الخطوة 1: التحقق من أن السجل التجاري نشط
  const info = await verifyCR(crNumber);
  if (info.status !== 'Active') {
    return { valid: false, crStatus: info.status, errorCode: 'CR_NOT_ACTIVE' };
  }
 
  // الخطوة 2: التأكد من وجود نشاط تجارة إلكترونية
  const hasEcommerceActivity = info.activities.some(
    (a) =>
      a.includes('تجارة إلكترونية') ||
      a.toLowerCase().includes('electronic commerce')
  );
  if (!hasEcommerceActivity) {
    return { valid: false, crStatus: info.status, errorCode: 'NO_ECOMMERCE_ACTIVITY' };
  }
 
  // الخطوة 3: التحقق من تطابق الملكية
  const ownersRes = await fetch(
    `${WATHQ_BASE}/owners/${crNumber}?language=ar`,
    { headers: { Authorization: `Bearer ${WATHQ_TOKEN}` } }
  );
  const ownersData = await ownersRes.json();
  const ownerMatch = ownersData.owners?.some(
    (o: { nationalId: string }) => o.nationalId === nationalId
  );
 
  if (!ownerMatch) {
    return { valid: false, crStatus: info.status, errorCode: 'OWNER_MISMATCH' };
  }
 
  return { valid: true, crStatus: info.status };
}

أربعة أخطاء شائعة وكيفية تجنّبها

1. قاعدة الرقم 700

لا يمكن استرجاع السجلات النشطة والمعلّقة إلا باستخدام الرقم الوطني الموحّد المؤلف من 10 أرقام ويبدأ بـ700. استخدام رقم السجل التجاري القديم يُعيد خطأ 400.1.5. احرص على جمع المعرّفين من التاجر عند التسجيل.

2. السجلات المنتهية مع شارة معروف ظاهرة

شارات معروف تبقى على واجهات المتاجر حتى بعد انتهاء صلاحية السجل التجاري. لا تثق بالشارة المرئية وحدها. استعلم من واثق عند كل تأهيل، وجدوِل إعادة تحقق تلقائية كل 30 يوماً للتجار النشطين.

3. استنزاف الحصة (429)

تفرض واثق حصصاً على الاستدعاءات حسب الخطة المشتركة. لعمليات تأهيل التجار بحجم مرتفع، خزّن نتائج واثق في Redis بمفتاح يعتمد رقم السجل وفترة صلاحية 24 ساعة. معظم تغييرات حالة السجل تحدث على دورة شهرية، وإعادة التحقق اليومية مبالغ فيها.

4. عدم تطابق كود النشاط

قد يكون السجل نشطاً لكن مُسجَّلاً لنشاط غير إلكتروني كخدمات الصيانة، دون أي تصنيف للتجارة الإلكترونية. استخدم GET /fullinfo/{id} لقراءة قائمة الأنشطة كاملة وارفض السجلات التي تفتقر إلى كود نشاط التجارة الإلكترونية أو التجزئة.

ربط حالة معروف بواجهة منصتك

توثيق منصة الأعمال (البديل الحالي لمعروف) خطوة يُنجزها التاجر بنفسه على business.sa — لا توجد واجهة API للتحقق منها برمجياً في الوقت الفعلي. النمط الذي تعتمده بوابات الدفع السعودية (HyperPay، Moyasar، STCPay) هو:

1. جمع رقم السجل التجاري والرقم الوطني الموحّد من التاجر
2. التحقق عبر واثق من أن السجل نشط ويتضمن نشاط تجارة إلكترونية
3. طلب تحميل شهادة منصة الأعمال من التاجر (ملف PDF يُصدر عبر business.sa)
4. عرض شارة "تاجر موثّق" على منصتك بعد اجتياز الخطوتين

هذا التحقق نادراً ما يعمل منفرداً

في المنصات السعودية الحقيقية، التحقق من السجل التجاري عقدة واحدة في سلسلة امتثال أوسع. التاجر نفسه سيحتاج أيضاً إلى:

• فحص حماية الأجور (WPS) — للتحقق من الامتثال إن كان يوظّف موظفين. راجع دليل تسوية رواتب WPS.
• حالة قوى / نطاقات — أهلية التوظيف ومستوى السعودة. راجع دليل تكامل منصة قوى.
• ربط فاتورة / ZATCA — المرحلة الثانية لأي معاملات B2B. راجع دليل ربط منصة فاتورة.
• مسار رواتب مدد — إن كانت منصتك تُعالج مدفوعات الموظفين. راجع دليل API مدد.

تشكّل هذه المنظومة مجتمعةً العمود الفقري للامتثال في أي سوق B2B أو منصة موارد بشرية سعودية.

تبني منظومة تحقق من التجار السعوديين وتصطدم بحالات لا تغطيها الوثائق؟ دمج واثق وقوى ومدد وفاتورة في منصات الخليج من عمل فريق نقطة. تواصل معنا — نحدد نطاق طبقة التحقق الخاصة بك في مكالمة واحدة.