> ## Documentation Index
> Fetch the complete documentation index at: https://docs.resq.software/llms.txt
> Use this file to discover all available pages before exploring further.

# مقدمة

> وثائق مرجعية لواجهات برمجة ResQ

## واجهات برمجة ResQ

تكشف ResQ عن واجهتين رئيسيتين لتنسيق الاستجابة للكوارث:

<CardGroup cols={2}>
  <Card title="Infrastructure API" icon="server" href="#infrastructure-api">
    إدارة الحوادث، جمع الأدلة، التحقق عبر البلوكشين، تحليل الذكاء
    الاصطناعي، وعمليات Solana على السلسلة.
  </Card>

  <Card title="Coordination API" icon="satellite-dish" href="#coordination-api">
    تنسيق أسطول الطائرات بدون طيار في الوقت الفعلي، استيعاب القياسات
    عن بُعد، تخزين IPFS، حقن الأخطاء، وموافقة المهام (HITL).
  </Card>
</CardGroup>

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

| API            | عنوان URL الأساسي                    |
| -------------- | ------------------------------------ |
| Infrastructure | `https://api.resq.software`          |
| Coordination   | `https://coordination.resq.software` |

عمليات النشر الذاتية تستبدل أسماء المضيفين بأسمائها الخاصة؛ أشكال الطلب
والاستجابة متطابقة.

## المصادقة

تستخدم كلتا الواجهتين رموز JWT من نوع bearer.

```bash theme={null}
# 1. استبدل بيانات الاعتماد برمز وصول
curl -X POST https://api.resq.software/login \
  -H "Content-Type: application/json" \
  -d '{"username":"مشغّل","password":"REDACTED"}'

# 2. أرسل الرمز مع كل طلب محمي
curl https://api.resq.software/evidence \
  -H "Authorization: Bearer $RESQ_TOKEN"
```

راجع [المصادقة](/ar/authentication) لدورة حياة الرمز، ومعالجة الصلاحيات،
وإرشادات التدوير.

## الاصطلاحات

### نوع المحتوى

تستخدم جميع الطلبات والاستجابات `application/json` ما لم توثّق نقطة نهاية
صراحةً نوع وسائط مختلفًا (على سبيل المثال، الرفع متعدد الأجزاء على
`POST /storage`).

### الوقت

الطوابع الزمنية في حمولات الموارد هي سلاسل ISO-8601 بتوقيت UTC
(`2026-05-04T06:01:27Z`). انتهاء صلاحية الرمز في `/login` هو الاستثناء —
فهو طابع زمني Unix بالثواني لتسهيل العمليات الحسابية.

### المعرّفات

معرّفات الموارد سلاسل غير شفافة. لا تحلّلها؛ تعامل معها كمعرّفات فقط.
يُشار إلى أدلة IPFS عبر CID (معرّف المحتوى)، وهو معرّف مبني على المحتوى
ومستقر.

### التقسيم إلى صفحات

تقبل نقاط نهاية القوائم معاملي الاستعلام `limit` (الافتراضي 50، الحد
الأقصى 200) و`cursor`. تحمل الاستجابة الحقل `next_cursor` عند توفّر
صفحات إضافية.

```http theme={null}
GET /evidence?limit=50&cursor=eyJpZCI6Ii4uLiJ9
```

### الإتقان التكراري (Idempotency)

تقبل نقاط النهاية المُعدِّلة الترويسة `Idempotency-Key`. تخزّن ResQ
الاستجابة مؤقتًا لمدة 24 ساعة، لذا تُعيد المحاولات النتيجة الأصلية بدلًا
من تكرار الأثر الجانبي.

### معرّفات الطلبات

تحمل كل استجابة الترويسة `X-Request-Id`. أدرجها في أي بلاغ دعم أو حادثة
حتى نتمكن من ربط السجلات.

### الأخطاء

تستخدم حالات الفشل رموز حالة HTTP القياسية مع غلاف JSON صغير. راجع
[الأخطاء](/ar/errors) للجدول الكامل لرموز الحالة، وإرشادات إعادة
المحاولة، ومخطط التراجع التدريجي.

## Infrastructure API

مبنية بـ Rust/Axum. تتعامل مع البيانات الدائمة، وتفاعلات البلوكشين، والتحليل المدعوم بالذكاء الاصطناعي.
عنوان URL الأساسي: `https://api.resq.software`.

| Tag            | الوصف                                                       |
| -------------- | ----------------------------------------------------------- |
| **incidents**  | إنشاء، إدراج، واسترجاع حوادث الكوارث                        |
| **evidence**   | إدارة الأدلة التي تجمعها الطائرات بدون طيار (مدعوم بـ IPFS) |
| **blockchain** | تسجيل واستعلام الأحداث على السلسلة، التحقق من المواقع       |
| **solana**     | إدارة المجال الجوي، سجلات التسليم، والتصاريح                |
| **auth**       | مصادقة قائمة على JWT                                        |

## Coordination API

مبنية بـ TypeScript/Elysia. تتعامل مع عمليات الأسطول في الوقت الفعلي وتنسيق المهام.

| Tag               | الوصف                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| **Fleet**         | معالجة دفعات القياسات عن بُعد                                                                  |
| **Intelligence**  | الإبلاغ عن الحوادث والتنبيهات التنبؤية                                                         |
| **Storage**       | رفع ملفات IPFS                                                                                 |
| **Simulation**    | حقن الأخطاء للاختبار                                                                           |
| **Admin**         | صحة الخدمة، التنميط، موافقة المهام (المادة 14 من قانون الذكاء الاصطناعي للاتحاد الأوروبي HITL) |
| **Observability** | مقاييس Prometheus وتدفقات أحداث SSE                                                            |

## حِزم التطوير (SDKs)

تجنّب كتابة عميل من الصفر — ثبّت إحدى حزم التطوير الرسمية.

<CardGroup cols={2}>
  <Card title="TypeScript" icon="js" href="/sdks/typescript">
    `@resq-systems/http` و`@resq-systems/security` ومكوّنات واجهة المستخدم.
  </Card>

  <Card title="Python" icon="python" href="/sdks/python">
    `resq-mcp` (خادم FastMCP) و`resq-dsa`.
  </Card>

  <Card title="Rust" icon="rust" href="/sdks/rust">
    واجهة `resq` الموحّدة إضافة إلى سبع أدوات TUI.
  </Card>

  <Card title=".NET" icon="hashtag" href="/sdks/dotnet">
    عملاء مُنمّطون، وعقود Protobuf، وبيئات محاكاة.
  </Card>
</CardGroup>