<!-- https://api.ibusisrael.online/docs/ar/access/ -->
# الوصول والمفاتيح والخصوصية

## المفاتيح

- يحصل المشروع على المفاتيح بعد قبول طلبه: [كيف يعمل الوصول](/ar/access/). تُنشأ المفاتيح في [صفحة المطوّر](https://app.ibusisrael.online/developers) وتُعرض مرة واحدة.
- الصيغة: `ibk_live_k_<10 أحرف>_<43 حرفًا>` (`ibk_test_…` للتجربة). الجزء الذي يسبق آخر `_` بادئة عامة تراها في صفحة المطوّر وفي الرفض؛ والباقي سري.
- أرسل المفتاح في ترويسة فقط: `Authorization: Bearer <المفتاح>`. يُرفض المفتاح في عنوان الطلب (`KEY_IN_QUERY`) ويُستحسن استبداله، لأن العناوين تُحفَظ في السجلات.
- احفظ المفاتيح على الخوادم: ليس في صفحات الويب ولا في حزم تطبيقات الهاتف ولا في service worker ولا في المستودعات العامة. الصفحة أو التطبيق يتصل بخادمك، وخادمك يتصل بـ iBus.
- الاستبدال: أنشئ المفتاح الجديد ويبقى القديم عاملًا حتى 24 ساعة. ألغِ المفتاح المسرَّب فورًا.

## عناوين IP

يمكن للمشروع قبول الطلبات من العناوين المدرجة فقط (IPv4 وIPv6 والشبكات). عندها يحتاج الطلب إلى مفتاح صحيح وعنوان مسموح معًا (وإلا `IP_NOT_ALLOWED` مع `ip_seen`). لمعرفة العنوان الذي يراه الخادم:

```bash
curl -H "Authorization: Bearer $IBUS_API_KEY" https://api.ibusisrael.online/api/access/whoami
```

يعرض الرد `ip_seen` و`checks` بالترتيب الذي يطبّقه الخادم: السر، المفتاح، المشروع، العنوان (`allowed` أو `denied` أو `not_configured`). يتوقف الرفض عند أول فحص لم ينجح ويعرض رمزه وبادئة المفتاح و`ip_seen` فقط. لا يستهلك حصة البيانات، لكنه محدود بـ 30 طلبًا في الدقيقة.

## رموز الرفض

لكل رفض `code` و`detail` قصير و`docs` (رابط لهذا الجدول) و`request_id`. اذكر `request_id` عندما تكتب إلى iBus.

| code | HTTP | المعنى وما العمل |
|---|---|---|
| `KEY_REQUIRED` | 401 | هذا العنوان يحتاج إلى مفتاح. أرسل `Authorization: Bearer <المفتاح>`، وإن لم يكن لديك مفتاح فقدّم طلبًا. |
| `KEY_INVALID` | 401 | المفتاح غير معروف أو منسوخ بخطأ. انسخه من جديد من صفحة المطوّر؛ تُقيَّد المفاتيح الخاطئة المتكررة من الشبكة نفسها لبعض الوقت. |
| `KEY_REVOKED` | 401 | أُلغي المفتاح (منك أو بعد الاستبدال أو من فريق iBus). أنشئ مفتاحًا جديدًا في صفحة المطوّر. |
| `KEY_EXPIRED` | 401 | انتهت صلاحية المفتاح. أنشئ مفتاحًا جديدًا. |
| `KEY_IN_QUERY` | 400 | وُجد مفتاح أو رمز في عنوان الطلب. يُرسل المفتاح في ترويسة `Authorization` فقط، والأفضل استبدال مفتاح ظهر في عنوان. |
| `KEY_NOT_ACCEPTED_HERE` | 401 | أُرسل المفتاح إلى عنوان غير api.ibusisrael.online (مثلًا عنوان التطبيق نفسه). تُفحص المفاتيح فقط على https://api.ibusisrael.online — أرسل الطلب إليه؛ في العناوين الأخرى يُرفض الطلب الذي يحمل مفتاحًا ولا يُنفَّذ بدونه. |
| `GROUP_NOT_ALLOWED` | 403 | لا يملك مشروعك صلاحية هذه المجموعة من العمليات. اطلبها من صفحة المشروع. |
| `OPERATION_NOT_AVAILABLE` | 403 | العملية غير عامة أو متاحة لمشروع معتمد فقط. |
| `IP_NOT_ALLOWED` | 403 | المفتاح صحيح، لكن الطلب جاء من عنوان غير موجود في قائمة المشروع. يتضمن الرد `ip_seen`: العنوان الذي رآه الخادم. |
| `PROJECT_SUSPENDED` | 403 | أوقف فريق iBus المشروع مؤقتًا. السبب في صفحة المشروع، والمفاتيح محفوظة. |
| `PROJECT_BLOCKED` | 403 | المشروع محظور وأُلغيت مفاتيحه. السبب في صفحة المشروع، ويمكنك الرد هناك. |
| `ACCESS_EXPIRED` | 403 | انتهت مدة وصول المشروع. اطلب التمديد من صفحة المشروع. |
| `PLATE_LOOKUP_NOT_ALLOWED` | 403 | البحث عن مركبة برقم لوحتها غير متاح لمشروعك. تظهر المركبات بأسماء مستعارة يومية. |
| `RATE_LIMITED` | 429 | طلبات كثيرة في الدقيقة - لمشروعك (مع مفتاح) أو لشبكتك (بدون مفتاح). انتظر `Retry-After` ثانية. |
| `QUOTA_EXCEEDED` | 429 | نفدت ميزانية المشروع اليومية أو الشهرية أو ميزانية الطلبات الثقيلة. النوع في `scope`، وموعد التجدد في `Retry-After`. |
| `CONCURRENCY_LIMIT` | 429 | طلبات كثيرة من المشروع في الوقت نفسه. انتظر الردود قبل إرسال المزيد. |
| `TEMPORARILY_RESTRICTED` | 429 | أُوقفت الطلبات لوقت قصير بعد مخالفات متكررة (مثل مفاتيح خاطئة كثيرة). انتظر `Retry-After`. |
| `CAPACITY_RESERVED` | 503 | الخدمة مشغولة وتحتفظ بالموارد للركاب. أعد المحاولة بعد `Retry-After` ثانية. |
| `POLICY_UNAVAILABLE` | 503 | لا يمكن التحقق من قواعد الوصول الآن، لذلك تُرفض الطلبات ذات المفتاح بدل تمريرها. أعد المحاولة بعد قليل. |
| `EXTERNAL_PAUSED` | 503 | أوقف iBus عمليات الربط الخارجية مؤقتًا (حادث أو صيانة). أعد المحاولة بعد `Retry-After`؛ مفاتيحك وحدودك لا تتغير. |
| `BODY_TOO_LARGE` | 413 | جسم الطلب أكبر من المسموح. عمليات القراءة لا تحتاج إلى جسم. |

## ما ليس جزءًا من هذه الواجهة

- الحسابات وتسجيل الدخول والمفضلة والإعدادات والإشعارات والمساعد ليئور: وظائف تطبيق iBus على `app.ibusisrael.online` المرتبطة بجلسته.
- مخطط الرحلات ومسارات المشي والشبكة كلها دفعة واحدة ومواقع المركبات: للمشاريع التي تحتاجها فقط، عند الطلب. تظهر المركبات بأسماء مستعارة يومية؛ ولا تُعطى أرقام اللوحات.
- المسارات القديمة في `api.ibusisrael.online` (مثل `/api/stops/search` بدون `/transport`) تبقى عاملة لعمليات الربط الحالية؛ والجديدة تستخدم `/api/transport/`.

## المتصفحات وCORS

الطلبات عبر النطاقات من المتصفح مسموحة فقط لتطبيق الويب iBus (`https://app.ibusisrael.online`)، بدون ملفات تعريف الارتباط. المفاتيح ليست للمتصفحات: صفحة على موقع آخر تتصل بخادمها.

## ما يحفظه الخادم

- عن كل طلب: الوقت والمشروع وبادئة المفتاح والعملية والحالة والمدة والجزء الشبكي من العنوان (يُحذف الجزء الأخير). التفاصيل 7 أيام، ثم الأعداد فقط.
- المفتاح نفسه لا يُحفَظ (بصمته فقط) ولا يُكتب في السجلات أو التقارير أو الرسائل.
- الواجهة لا تضع ملفات تعريف الارتباط. لا توجد بيانات شخصية في الردود؛ والمركبات بأسماء مستعارة يومية.

## التواصل

الأسئلة والإبلاغ عن المشكلات: [ibusisrael.online/contact](https://ibusisrael.online/contact). بشأن رفض، اذكر `request_id` الخاص به.