digna REST API 2026.11¶

تتيح REST API الخاصة بـ digna لأدواتك ومسارات البيانات الخاصة بك العمل مع digna عبر HTTP وJSON: قراءة المشاريع ونتائج الفحص، وإدارة مصادر البيانات ومجموعات البيانات والسمات، وبدء عمليات الفحص، على سبيل المثال في نهاية تحميل البيانات. وتستخدم Python SDK واجهة API نفسها.

تتناول هذه الصفحة ما تشترك فيه جميع الطلبات. وتسرد صفحات الموارد كل نقطة نهاية مع معاملاتها ونص الطلب والاستجابات والمخططات:

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

واجهة API جزء من الواجهة الخلفية لـ digna. يبدأ كل مسار بـ /v1 بعد عنوان الواجهة الخلفية:

https://digna.example.com/v1/projects

عنوان الواجهة الخلفية هو العنوان نفسه الذي تستخدمه لوحة التحكم، أي baseUrl في القسم [api] من الملف dashboard/dashboard_config.toml. استخدم HTTPS كلما لم يكن المستدعي وdigna على الجهاز نفسه، لأن كل طلب يحمل مفتاح API.

المصادقة¶

يرسل كل طلب مفتاح API لمستخدم في digna في الترويسة Authorization:

Authorization: Bearer <api key>

لإنشاء مفتاح، افتح ملفك الشخصي في الزاوية السفلية اليسرى من لوحة التحكم، وانقر على API Keys، ثم على Add API Key، وانسخ المفتاح. لا يُعرض إلا مرة واحدة. وتعمل المفاتيح نفسها أيضًا مع digna MCP Server.

يُنفَّذ الطلب بصلاحيات المستخدم صاحب المفتاح. ويتطلب الإنشاء والتغيير والحذف دور editor في المشروع؛ وإلا يُرفض الطلب بالرمز 403 والرسالة You don't have permission to edit this project.

إرسال طلب¶

export DIGNA_API_KEY='<api key>'
curl https://digna.example.com/v1/projects -H "Authorization: Bearer $DIGNA_API_KEY"

الاستجابات بتنسيق JSON. وتُعاد القوائم كمصفوفة JSON. ونصوص الطلبات بتنسيق JSON أيضًا، وتُرسل مع Content-Type: application/json.

الحدود وعوامل التصفية¶

تُعيد نقاط نهاية القوائم limit عنصرًا على الأكثر: 200 افتراضيًا، وحتى 5000. وتُرفض القيمة الواقعة خارج هذا النطاق بالرمز 400. لا توجد إزاحة ولا رمز صفحة، لذا ضيّق القائمة بعوامل التصفية الخاصة بها بدلًا من ذلك، على سبيل المثال project_id أو data_source_id أو start_date وend_date في حالات الفحص.

يُلغى الطلب الذي يستغرق أكثر من 60 ثانية مع 408 Request Timeout.

الأخطاء¶

تحتوي استجابة الخطأ على نص JSON يتضمن رمزًا ورسالة:

{
  "code": "NOT_FOUND",
  "message": "Data set not found"
}

يوضح message في استجابة 401 ما المشكلة في المفتاح:

تشغيل فحص¶

يبدأ التكامل النموذجي فحصًا عند انتهاء تحميل البيانات، وينتظر اكتماله، ثم يقرأ النتيجة:

1. ابدأ الفحص باستخدام POST /v1/inspection-requests. تحتوي الاستجابة على id الطلب.
2. تابع تقدّمه باستخدام GET /v1/inspection-requests/{inspection_request_id}. تنتقل قيمة status من PENDING مرورًا بـ RUNNING إلى COMPLETED، أو تنتهي بـ FAILED أو ABORTED أو CANCELLED. اسأل مجددًا كل بضع ثوانٍ إلى أن تتوقف عن التغيّر.
3. اقرأ النتيجة باستخدام GET /v1/inspection-statuses/data-sources للتواريخ التي جرى فحصها. لكل عنصر status إجمالية: 0 (OK) أو 1 (تحذير) أو 2 (حرجة) أو -1 (بلا حالة)، وحالة لكل وحدة مع عدد الفحوصات الناجحة وغير المؤكدة والفاشلة.

curl -X POST https://digna.example.com/v1/inspection-requests \
  -H "Authorization: Bearer $DIGNA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": 1,
    "include_all_data_sources": true,
    "data_source_ids": [],
    "start_date": "2026-11-06",
    "end_date": "2026-11-06",
    "mode": "DAILY",
    "weekly_mode_weekdays": [],
    "monthly_mode_days": [],
    "use_notification": true
  }'

مستند OpenAPI¶

تصف كل عملية تثبيت لـ digna واجهة API هذه في مستند OpenAPI 3.1، وتوفّر Swagger UI تفاعلية لتجربة الطلبات عليها:

مستند Release 2026.11 متاح هنا أيضًا: openapi.json. استخدمه لتوليد عميل بلغة برمجة أخرى.