API منصة اعتماد: أتمتة المشتريات الحكومية السعودية

تُصدر الحكومة السعودية أكثر من 300,000 مناقصة سنوياً عبر منصة اعتماد. معظم الشركات لا تزال تتابعها يدوياً — موظف يدخل المنصة يومياً، وجدول بيانات يُحدَّث أسبوعياً، ولا شيء يعمل أثناء الإجازات أو الاجتماعات. النتيجة: مناقصات تُغلق قبل تقديم العرض، وعقود تُفوَّت بهامش ساعات.

توفر منصة اعتماد واجهة برمجية (API) رسمية عبر بوابة المطورين، وتسدّ أدوات طرف ثالث ما تركته البوابة الرسمية مفتوحاً. هذا الدليل يغطي خطوات التسجيل والمصادقة والتكامل البرمجي من البداية حتى الإنتاج.

ما تقدمه اعتماد للمطورين

تستضيف بوابة المطورين على apiportal.etimad.sa ثلاثة منتجات API رسمية:

• العقود الحكومية (Contracts Plus) — الاستعلام عن العقود القائمة والتاريخية برقم السجل التجاري أو رقم المستفيد أو الرقم 700. يُستخدم من البنوك وأنظمة ERP للتحقق من سجلات الموردين قبل التأهيل أو التمويل.
• شهادة الراتب — استرداد شهادة راتب معتمدة للموظفين الحكوميين بناءً على آخر مسير تم صرفه. يُستخدم على نطاق واسع في منتجات التمويل البنكي والفنتك.
• البيانات المفتوحة (Open Data) — بيانات مشتريات حكومية مجمَّعة للتحليل وإعداد التقارير ولوحات المعلومات.

تسعيرة Contracts Plus مُدرَّجة: من 45 ريالاً للاستعلام الواحد عند أقل من 10 استعلامات شهرياً، وتنخفض إلى 20 ريالاً عند تجاوز 1,000 استعلام. التسعيرة تُطبَّق على الاستعلامات الناجحة والفاشلة على حدٍّ سواء، ما يجعل التحقق من صحة البيانات قبل الإرسال ضرورة لا اختياراً.

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

الوصول مشروط بموافقة مسبقة. الأفراد والشركات كلاهما مؤهلان، لكن المسار يبدأ بسجلك التجاري:

1. سجّل الدخول على apiportal.etimad.sa باستخدام بيانات اعتماد الأعمال المرتبطة بسجلك التجاري عبر منصة نفاذ.
2. تصفّح منتجات API المتاحة واختر ما يتناسب مع حالة الاستخدام لديك.
3. قدِّم طلب اشتراك. الموافقة تستغرق عادةً من يوم إلى ثلاثة أيام عمل.
4. بعد الموافقة، أنشئ تطبيقاً داخل البوابة — سيُولِّد لك Client ID وClient Secret.
5. اختبر على بيئة Sandbox باستخدام بيانات العقود والرواتب الافتراضية قبل الانتقال إلى الإنتاج.

بيئة Sandbox تُمكّنك من التحقق من التكامل كاملاً دون أي تكلفة لكل استعلام.

المصادقة: نمط Client Credentials

تعتمد اعتماد على نمط client credentials — تُبادِل Client ID وClient Secret مقابل توكن Bearer قصير الأمد، ثم تُرفق هذا التوكن مع كل طلب API.

async function getEtimadToken(): Promise<string> {
  const res = await fetch("https://publicapi.etimad.sa/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      clientId: process.env.ETIMAD_CLIENT_ID,
      clientSecret: process.env.ETIMAD_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`فشل طلب التوكن: ${res.status}`);
  const data = await res.json();
  return data.access_token;
}

ملاحظة: عناوين API الدقيقة ومدة صلاحية التوكن موثَّقة في واجهة Swagger داخل بوابة المطورين بعد الاشتراك. جدِّد التوكن بشكل وقائي واحفظ وقت انتهاء الصلاحية معه بدلاً من انتظار خطأ 401.

الاستعلام عن بيانات العقود

بعد المصادقة، تقبل نقطة Contracts Plus معرّف المستفيد وتُعيد تفاصيل العقود التاريخية — أسماء الجهات والقيم والتواريخ وحالة التنفيذ.

interface ContractRecord {
  contractNumber: string;
  agencyName: string;
  contractValue: number;
  startDate: string;
  endDate: string;
  status: string;
}
 
async function getContractsByCR(
  crNumber: string,
  token: string
): Promise<ContractRecord[]> {
  const res = await fetch(
    `https://publicapi.etimad.sa/contracts/v1/inquiry` +
      `?beneficiaryCR=${encodeURIComponent(crNumber)}&beneficiaryIdType=CR`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  if (!res.ok) throw new Error(`فشل الاستعلام: ${res.status}`);
  const data = await res.json();
  return data.contracts ?? [];
}

مورّد أنهى 50 عقداً حكومياً بالقيمة الكاملة يختلف جوهرياً في مستوى المخاطرة عن مورّد لديه ثلاثة عقود مُنفَّذة جزئياً. هذه البيانات، التي كانت مدفونة في وثائق PDF وصور شاشة، باتت استعلام API واحد.

رصد المناقصات: الحلقة المفقودة

البوابة الرسمية لا تكشف API للمناقصات في الوقت الفعلي — تُركّز على بيانات العقود والمعلومات المالية لا على قوائم الترسية الجديدة. خدمات طرف ثالث مثل Tenders Alerts تسدّ هذه الفجوة بتجميع البيانات من tenders.etimad.sa وكشفها عبر نقاط REST.

نمط الرصد الشائع جدولة زمنية كل 30 أو 60 دقيقة مع دفع المناقصات الجديدة المطابقة إلى Slack أو CRM أو أداة إدارة مشاريع:

async function fetchNewTenders(apiKey: string, region?: string): Promise<void> {
  const params = new URLSearchParams({ status: "open" });
  if (region) params.set("region", region);
 
  const res = await fetch(`https://api.tendersalerts.com/tenders?${params}`, {
    headers: { "x-api-key": apiKey },
  });
  if (!res.ok) throw new Error(`فشل جلب المناقصات: ${res.status}`);
  const body = await res.json();
 
  for (const tender of body.data ?? []) {
    await notifyTeam(tender);
  }
}

الجمع بين الطبقتين يُغطّي الدورة الكاملة: API اعتماد الرسمية للتحقق من الموردين والعقود، وطبقة المناقصات لتدفق الفرص الفوري دون تسجيل دخول يدوي.

أربعة أنماط فشل شائعة

النمط الذي نراه مراراً في تكامل منصات الحكومة السعودية — كما في WPS وNPHIES — هو أن البيانات متاحة لكن افتراضات المسار البرمجي خاطئة:

1. انتهاء التوكن في المهام الطويلة. لا تعتمد على الخطأ 401 لتفعيل التجديد. احفظ وقت انتهاء الصلاحية وجدِّد بشكل وقائي قبل إرسال الدُفعة.
2. الاستعلامات الفاشلة تُحتسب في الفاتورة. تحقق من صحة أرقام السجل التجاري ومعرّفات المستفيدين قبل الإرسال لتجنب الدفع مقابل بيانات خاطئة.
3. اختلاف Sandbox عن الإنتاج. مخطَّطات Sandbox قد تتأخر عن إصدارات الإنتاج. اختبر تحليل الاستجابات على بيانات حقيقية قبل الإطلاق.
4. غياب حماية التصفح الصفحي (pagination). سجلات العقود للموردين الكبار قد تمتد لمئات السجلات. نفِّذ pagination من اليوم الأول واضبط حداً أقصى معقولاً لتجنب ضغط الذاكرة.

ربط اعتماد بنظام ERP الخاص بك

النمط الأكثر شيوعاً للشركات السعودية العاملة مع الجهات الحكومية يربط ثلاثة أنظمة في دورة مشتريات واحدة:

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

نفس منطق الأتمتة الذي يُقلّص التكاليف التشغيلية على المستوى الداخلي ينطبق على دورة المشتريات: كلما قلّت التدخلات اليدوية في حلقة الرصد، قلّت الفرص الضائعة وزادت سرعة تقديم العروض.

ابدأ بأتمتة مشترياتك الحكومية

البنية التحتية لـ API موجودة في اعتماد. ما ينقص هو طبقة التكامل — الخدمة البرمجية وWebhook وموصّل ERP الذي يحوّل بوابة حكومية إلى تغذية بيانات حية تتصرف عليها أنظمتك فوراً.

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