واجهة REST الإصدار 1

المصادقة

أنشئ مفتاحًا في لوحة التحكم، مفاتيح API (يلزم حساب مجاني، بحد أقصى 10 مفاتيح نشطة)، ثم أرسله كرمز Bearer. يُعرض المفتاح مرة واحدة عند إنشائه ويُخزَّن مجزّأً. لكل مفتاح حد لكل دقيقة؛ تجاوزه يعيد 429.

Authorization: Bearer sk_sc_...

POST /api/v1/assess

النطاق: assess. بدون answers، تعيد بنك الأسئلة للمجالات المطلوبة. مع answers، تعيد الدرجات والتقديرات والتفصيل حسب الفئة وتوصيات الخبراء والقوانين المنطبقة.

curl -X POST https://structureclerk.ca/api/v1/assess \
  -H "Authorization: Bearer sk_sc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["data_protection", "cybersecurity"],
    "jurisdictions": ["CA_QC", "EU"],
    "answers": {
      "data_protection": { "dp_1": true, "dp_2": "partial" }
    }
  }'

{
  "overallScore": 62,
  "grade": "B-",
  "domains": {
    "data_protection": {
      "score": 62,
      "answeredQuestions": 2,
      "categoryScores": { "...": { "percentage": 50 } },
      "topRecommendations": [
        {
          "questionId": "dp_2",
          "title": "…",
          "advice": "…",
          "quickWin": "…",
          "effort": "medium",
          "impact": "high",
          "timeline": "30 jours"
        }
      ]
    }
  },
  "applicableLaws": [
    { "jurisdiction": "Québec", "law": "Loi 25", "domain": "data_protection" }
  ]
}

POST /api/v1/scan

النطاق: scan. فحص سلبي لامتثال الموقع: HTTPS، وكشف سياسة الخصوصية، وشريط الكوكيز، وترويسات أمان HTTP، ومعلومات الاتصال. الصفحات العامة فقط، دون اختراق ودون اختبار نشط.

curl -X POST https://structureclerk.ca/api/v1/scan \
  -H "Authorization: Bearer sk_sc_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.example.com" }'

{
  "url": "https://www.example.com",
  "overallScore": 75,
  "checks": {
    "https": { "passed": true, "details": "…" },
    "privacyPolicy": { "found": true, "url": "…", "details": "…" },
    "cookieBanner": { "detected": false, "details": "…" },
    "securityHeaders": { "score": 57, "headers": { "…": {} }, "details": "…" },
    "contactInfo": { "found": true, "details": "…" }
  },
  "recommendations": ["…"]
}

إدارة المفاتيح

نقاط مُصادَقة بالجلسة (المتصفح) تقف خلف واجهة لوحة التحكم:

• GET /api/v1/keys · سرد مفاتيحك (البادئات فقط)
• POST /api/v1/keys · إنشاء مفتاح ({ "name": "...", "scopes": ["assess","scan","authority"] })
• DELETE /api/v1/keys/:id · تعطيل مفتاح

نقاط مجانية

عامة، بلا مفتاح وبلا رصيد. أُطلقت دون توثيق هنا، وهو ما يعادل عدم إطلاقها.

• GET /api/v1/pricing · جدول الأسعار الحي: تكلفة الأرصدة لكل نقطة، وحزم الشحن، والحصة اليومية المجانية. مقروء آليًا، وهو المصدر الذي تقرأ منه هذه الوثائق.
• GET /api/v1/authority/verify/:evidence_id · التحقق من توقيع Ed25519 لقرار ما. مجاني وبلا حساب، بشكل دائم.
• GET /api/v1/authority/verify/anchors · المراسي المنشورة لسجل القرارات المسلسل، للتدقيق من طرف ثالث.
• GET /api/v1/authority/stats · أعداد القرارات المجمّعة. بلا محتوى قرارات وبلا معرّفات.

الأرصدة والحصة المجانية

تُقاس النقاط المدفوعة بأرصدة مدفوعة مسبقًا، وتُستهلك الحصة اليومية أولًا. الرفوض أدناه هي ما ستتلقاه فعلًا؛ وترتيب المعالجة الكامل والأسعار وترويسات الاستجابة على صفحة الفوترة.

الأخطاء