الوصول والمفاتيح والخصوصية
المفاتيح#
- يحصل المشروع على المفاتيح بعد قبول طلبه: كيف يعمل الوصول. تُنشأ المفاتيح في صفحة المطوّر وتُعرض مرة واحدة.
- الصيغة:
ibk_live_k_<10 أحرف>_<43 حرفًا>(ibk_test_…للتجربة). الجزء الذي يسبق آخر_بادئة عامة تراها في صفحة المطوّر وفي الرفض؛ والباقي سري. - أرسل المفتاح في ترويسة فقط:
Authorization: Bearer <المفتاح>. يُرفض المفتاح في عنوان الطلب (KEY_IN_QUERY) ويُستحسن استبداله، لأن العناوين تُحفَظ في السجلات. - احفظ المفاتيح على الخوادم: ليس في صفحات الويب ولا في حزم تطبيقات الهاتف ولا في service worker ولا في المستودعات العامة. الصفحة أو التطبيق يتصل بخادمك، وخادمك يتصل بـ iBus.
- الاستبدال: أنشئ المفتاح الجديد ويبقى القديم عاملًا حتى 24 ساعة. ألغِ المفتاح المسرَّب فورًا.
عناوين IP#
يمكن للمشروع قبول الطلبات من العناوين المدرجة فقط (IPv4 وIPv6 والشبكات). عندها يحتاج الطلب إلى مفتاح صحيح وعنوان مسموح معًا (وإلا IP_NOT_ALLOWED مع ip_seen). لمعرفة العنوان الذي يراه الخادم:
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. بشأن رفض، اذكر request_id الخاص به.