واجهة برمجة تطبيقات تقارير SonarQube و Webhooks

تصف هذه المقالة كيفية الوصول برمجياً إلى تقارير أمان SonarQube المخزنة في منصة Procurize. يغطي الدليل API REST لسرد واسترجاع التقارير، تنزيل أرشيفات التقارير، والاشتراك في إشعارات webhook عند إضافة تقارير جديدة.

نظرة عامة

يتيح وحدة تقارير SonarQube للمنظمات تخزين وإدارة تقارير الأمان وجودة الشيفرة التي ينشئها SonarQube مركزيًا. توفر منصة Procurize هذه البيانات عبر:

• API REST لاسترجاع البيانات الوصفية للتقارير المخزنة
• نهج (endpoint) لتنزيل ملفات التقارير كأرشيفات ZIP
• Webhooks للحصول على إشعارات تقريبًا فورية عندما يصبح تقرير جديد متاحًا

تسمح هذه الإمكانات بدمجها في خطوط أنابيب CI/CD، أنظمة GRC، لوحات التحكم الداخلية، وأدوات إدارة المخاطر الطرفية.

المصادقة والتفويض

جميع طلبات API المذكورة في هذه المقالة لا تتطلب مصادقة.

معرف المنظمة

يتطلب كل طلب في هذا الدليل وجود معرف منظمة. يمكنك العثور عليه في لوحة إعدادات المنظمة على https://dashboard.procurize.ai. لاحظ أن الوصول إلى لوحة الإعدادات يحتاج إلى تفويض، ويتطلب أن يكون للمستخدم دور “مسؤول” على الأقل في تلك المنظمة.

عنوان URL الأساسي

جميع نقط النهاية (endpoints) الخاصة بـ REST API تُقدَّم تحت عنوان URL الأساسي التالي:

https://api.procurize.com

API REST لتقارير SonarQube

سرد التقارير

يعيد قائمة مقسَّمة إلى صفحات من تقارير أمان SonarQube المخزنة في المنصة.

النهج

GET /security/report/list

معاملات الاستعلام

• org (إلزامي): معرف المنظمة.
• version (اختياري): النسخة الدقيقة للمنتجات وفق صيغة Semantic Versioning.
• minver (اختياري): الحد الأدنى لإصدار المنتجات وفق صيغة Semantic Versioning.
• maxver (اختياري): الحد الأقصى لإصدار المنتجات وفق صيغة Semantic Versioning.

يرجى ملاحظة أن أحد المعاملات version أو minver أو maxver يجب أن يكون موجودًا على الأقل.

مثال طلب

curl "https://api.procurize.com/security/report/list?org=00000000-0000-0000-0000-000000000001&version=1.0"

مثال استجابة

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

تنزيل أرشيف التقرير

يُنزّل أرشيف ZIP يحتوي على كافة ملفات تقرير SonarQube الكاملة. يشمل الأرشيف تقارير HTML وPDF.

النهج

GET /security/report/files

• org (إلزامي): معرف المنظمة.
• reports (إلزامي): مصفوفة من معرفات التقارير.

مثال طلب

curl "https://api.procurize.com/security/report/files?org=00000000-0000-0000-0000-000000000001&reports=00000000-0000-0000-0000-000000000002&reports=00000000-0000-0000-0000-000000000003"

استجابة

• نوع المحتوى: application/zip
• جسم الاستجابة يحتوي على ملف ZIP ثنائي

يجب على العملاء بث الاستجابة وحفظها على القرص.

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

يستخدم الـ API رموز حالة HTTP القياسية.

• 200 OK: الطلب نجح
• 204 No Content: التقرير غير موجود
• 400 Bad Request: معلمات غير صالحة أو طلب غير مُنَسَّق
• 500 Internal Server Error: خطأ غير متوقع في الخادم

تحتوي استجابات الأخطاء على رمز خطأ قابل للقراءة آليًا ورسالة قابلة للقراءة من قبل الإنسان.

Webhooks

تتيح Webhooks الخاصة بـ Procurize للأنظمة الخارجية استلام إشعارات عندما تُستقبل تقارير SonarQube جديدة أو تُحدَّث.

إعداد Webhooks

يمكن إضافة أو تعديل Webhooks في لوحة إعدادات المنظمة، قسم تقارير الأمان على https://dashboard.procurize.ai. يرجى ملاحظة أن الوصول إلى لوحة الإعدادات يحتاج إلى تفويض، ويجب أن يكون للمستخدم دور “مسؤول” على الأقل في تلك المنظمة.

للتحقق من Webhooks، يمكنك استخدام خدمات اختبار عبر الإنترنت مثل https://webhook-test.com

حمولة Webhook

يتم تسليم أحداث Webhook كطلبات HTTP POST مع حمولة JSON.

مثال حمولة

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

أمان Webhook

لضمان الأصالة، تتضمن طلبات Webhook رأس توقيع يتم إنشاؤه باستخدام سر مُشترك.

• يُحسب التوقيع باستخدام HMAC‑SHA256
• يجب على العملاء التحقق من التوقيع قبل معالجة الحمولة

هذا يمنع تسليم Webhooks غير المصرح به أو المُزيف.

التسليم وإعادة المحاولة

• يتوقع Webhook استجابة 2xx ليُعتبر تم تسليمه بنجاح
• تُعاد المحاولات الفاشلة تلقائيًا كل ساعة.
• قد تُسلم الأحداث أكثر من مرة؛ لذا يجب على المستهلكين تنفيذ معالجة غير متكررة (idempotent).

حالات الاستخدام النموذجية

• استيراد نتائج SonarQube تلقائيًا إلى لوحات التحكم الداخلية للأمان
• تشغيل تدفقات عمل الامتثال عند فشل بوابات الجودة
• أرشفة تقارير الأمان للمراجعات والتدقيقات ومراجعات مخاطر البائعين
• الحفاظ على تزامن الأنظمة الطرفية مع أحدث وضعية أمان الشيفرة