الواجهة البرمجية

المصادقة

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

curl https://grc.cybers.biz/api/v1/frameworks \
  -H "Authorization: Bearer ehk_xxxxxxxxxxxxxxxxxxxxxxxx"

المفتاح يمنح قراءة كل بيانات منظمتك، فتعامل معه معاملة كلمة المرور: لا تضعه في شفرة العميل ولا في مستودع عام، ودوّره عند الاشتباه، والإلغاء فوري من اللوحة نفسها.

الحدود والأخطاء

الحالة	المعنى
`401 missing_key`	ما فيه ترويسة تفويض
`401 invalid_key`	مفتاح غير معروف أو ملغى
`404 not_found`	المورد غير موجود أو خارج نطاق منظمتك
`429 rate_limited`	تجاوز 600 طلب في الساعة

كل استجابة ناجحة تتضمن ok: true، وبيانات الأطر ثابتة يمكن تخزينها مؤقتًا لديك.

الأطر التنظيمية

GET/api/v1/frameworksقائمة الأطر وإحصاءاتها

GET/api/v1/frameworks/{slug}الإطار كاملًا بنصوص ضوابطه

القيم المتاحة لـslug: ecc، cscc، ccc، tcc، corf، nbcc.

{
  "ok": true,
  "framework": {
    "slug": "ecc", "code": "ECC-2:2024",
    "name": { "ar": "الضوابط الأساسية للأمن السيبراني", "en": "Essential Cybersecurity Controls" },
    "stats": { "domains": 4, "subdomains": 28, "controls": 108, "subcontrols": 59 },
    "domains": [ /* المجالات والمكونات والضوابط بنصوصها */ ]
  }
}

المواءمة

GET/api/v1/alignmentالإحالات الرسمية بين الأطر

يعيد الإحالات مرتبة حسب ضابط الضوابط الأساسية، ومعها جملة الإحالة كما وردت في نص الجهة، وهو ما يسمح لك ببناء تغطية متعددة الأطر داخل أنظمتك.

{
  "ok": true, "hub": "ecc",
  "stats": { "links": 82, "ecc_anchors": 31, "confirmed_both_languages": 36 },
  "by_ecc": { "2-2-3": [ { "fw": "cscc", "num": "2-2-1", "evidence": { "ar": "..." } } ] }
}

التقييمات

GET/api/v1/assessmentsتقييمات منظمتك ونتائجها

GET/api/v1/assessments/{id}التفاصيل والإجابات

{
  "ok": true,
  "assessments": [
    { "id": 12, "title": "تقييم الربع الثالث", "framework": "ecc",
      "score": { "pct": 62.5, "answered": 108, "total": 108, "yes": 60, "partial": 25, "no": 20, "na": 3 } }
  ]
}

خطط المعالجة والأدلة

GET/api/v1/assessments/{id}/tasksالمهام بحالاتها وملاكها

GET/api/v1/assessments/{id}/evidenceسجل الأدلة

حالات المهام: open، in_progress، done، accepted. هذا المسار مخصص لمزامنة المهام مع نظام التذاكر لديك.

أمثلة عملية

لوحة التزام في نظامك الداخلي

const H = { Authorization: `Bearer ${process.env.EHKAM_KEY}` };
const { assessments } = await (await fetch(
  'https://grc.cybers.biz/api/v1/assessments', { headers: H })).json();
const latest = assessments[0];
console.log(latest.title, latest.score.pct + '%');

فتح تذكرة لكل فجوة مفتوحة

const { tasks } = await (await fetch(
  `https://grc.cybers.biz/api/v1/assessments/${id}/tasks`, { headers: H })).json();
tasks.filter(t => t.status === 'open')
     .forEach(t => createTicket(t.control_num, t.title, t.owner, t.due));

الواجهة اليوم للقراءة فقط عمدًا: الكتابة تمر عبر الواجهة التفاعلية حيث تُسجَّل كل تغييرات المستخدمين في سجل التدقيق، ومسارات الكتابة والخطافات ضمن خطة الإصدار القادم.