FixWeb

// docs / rest api

واجهة REST API

JSON API موثقة عبر Bearer لأتمتة الفحوصات السلبية، وحالة الفحص، والنتائج. تستخدم pagination بالمؤشر، ومحدودة المعدل، ومرفقة بمواصفة OpenAPI قابلة للقراءة آليًا لتوليد العملاء. تبقى الفحوصات النشطة داخل dashboard UI لإثبات الملكية.

المصادقة

يجب أن يحمل كل طلب رمز Bearer في ترويسة Authorization. تصدر الرموز من الحساب → رموز API؛ وتُعرض القيمة النصية لك مرة واحدة فقط عند الإنشاء. إلغاء رمز يعيد 401 في الاستدعاء التالي.

bash
curl -H "Authorization: Bearer fxw_..." \
  https://fixweb.app/api/v1/scans

صيغة الرمز: fxw_ متبوعة بـ 43 محرف base64url. يُخزن ساكنًا كتجزئة SHA-256؛ ولا تُحفظ القيمة النصية أبدًا من جهة الخادم.

حدود المعدل

نافذتان على كل طلب مصادق عليه: اندفاع 10 طلبات/ثانية وثابت 60 طلبًا/دقيقة، وكلاهما مبني على تجزئة Bearer. يضاف فرض الحصة (حدود الفحوص الشهرية لكل باقة) فوق ذلك — راجع الحصص والحدود.

ترقيم الصفحات

تستخدم نقاط نهاية القوائم (/api/v1/scans، /api/v1/findings) ترقيم صفحات قائمًا على المؤشر ومبنيًا على (created_at, id) بترتيب تنازلي. مرّر ?cursor=<next_cursor> لجلب الصفحة التالية. يبقى المؤشر صحيحًا تحت الكتابات المتزامنة (بلا انحراف OFFSET).

أشكال الأخطاء

كل خطأ هو كائن JSON يحتوي على الأقل على مفتاح error.

jsonc
{ "error": "invalid_token" }                              // 401
{ "error": "forbidden" }                                  // 403
{ "error": "not_found" }                                  // 404
{ "error": "quota_exceeded", "quota": {...} }             // 429
{ "error": "rate_limited", "retry_after_seconds": 47 }    // 429
{ "error": "invalid_input", "issues": [...] }             // 400

نقاط النهاية

بدء فحص

POST/api/v1/scans

Enqueues a passive scan. Returns immediately with a queued scan id; poll GET /api/v1/scans/[scanId] until status === "completed". Owner-depth mode is not exposed — see Scan types for the attestation-flow rationale.

curl -X POST https://fixweb.app/api/v1/scans \
  -H "Authorization: Bearer fxw_..." \
  -H "content-type: application/json" \
  -d '{"target":"https://staging.example.com"}'

// استجابة 200

{
  "id": "8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d",
  "status": "queued",
  "target": "https://staging.example.com",
  "mode": "passive"
}

سرد فحوصك

GET/api/v1/scans

يعيد الفحوص للمؤسسة المرتبطة بالرمز المستدعي، الأحدث أولًا. رقّم الصفحات باستخدام ?cursor=. الحد الافتراضي 50، والأقصى 100.

curl -H "Authorization: Bearer fxw_..." \
  "https://fixweb.app/api/v1/scans?limit=25"

// استجابة 200

{
  "scans": [
    {
      "id": "8f1c4e2a-...",
      "target_url": "https://staging.example.com",
      "target_hostname": "staging.example.com",
      "mode": "passive",
      "status": "completed",
      "started_at": "2026-05-07T14:00:00Z",
      "completed_at": "2026-05-07T14:00:23Z",
      "findings_count": { "critical": 1, "high": 3, "medium": 7, "low": 2, "info": 4 },
      "triggered_by": "api",
      "created_at": "2026-05-07T14:00:00Z"
    }
  ],
  "next_cursor": "2026-05-07T14:00:00Z:8f1c4e2a-..."
}

جلب فحص

GET/api/v1/scans/{scanId}

يعيد غلاف الفحص + ملخص الشدة لكل فئة افتراضيًا. مرّر ?include_findings=true للحصول على التقرير الكامل (كبير للفحوص كثيرة الضوضاء — فضّل نقطة نهاية النتائج مع المرشحات).

curl -H "Authorization: Bearer fxw_..." \
  https://fixweb.app/api/v1/scans/8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d

سرد النتائج

GET/api/v1/findings

Filterable findings list across every scan in the caller's org. Filters: severity=critical,high, check_id=performance.delivery, since=2026-04-01T00:00:00Z. Cursor-paginated.

curl -H "Authorization: Bearer fxw_..." \
  "https://fixweb.app/api/v1/findings?severity=critical,high&limit=50"

// استجابة 200

{
  "findings": [
    {
      "id": "...",
      "scan_id": "...",
      "check_id": "secrets.js-bundle-sweep",
      "severity": "critical",
      "title": "Supabase service role key exposed in JS bundle",
      "description": "...",
      "evidence": { ... },
      "remediation": "...",
      "cwe_id": "CWE-798",
      "created_at": "2026-05-07T14:00:23Z"
    }
  ],
  "next_cursor": null
}

مواصفة OpenAPI

مواصفة قابلة للقراءة آليًا في /docs/api/openapi (text/yaml). ضعها في مولد الشفرة المفضل لديك (openapi-typescript أو openapi-python-client أو أي سلسلة أدوات OpenAPI 3.1) للحصول على عملاء مضبوطين الأنواع.

واجهة REST API — Docs · FixWeb