مركز المساعدة · للطاقم الإداري

التكاملات: مفاتيح API وخطافات الويب وواجهة العمليات

يمكن لبيانات شركتك أن تغذي أدواتك الخاصة: بوت Discord، أو موقعك، أو جدول بيانات. كل ذلك في تبويب التكاملات (Integrations) من الطاقم الإداري ← إعدادات شركة الطيران ← الإعدادات. تحتاج إلى صلاحية إعدادات شركة الطيران ومفتاح العمليات (Airline settings and the operations key)؛ ولا يرى هذا التبويب أعضاء الطاقم الذين يديرون Discord فقط.

مفتاح واجهة العمليات

إنشاء مفتاح يعطي الشركة مفتاحًا واحدًا يقرأ كل شيء في واجهة العمليات ولا يغيّر شيئًا. يُعرض مرة واحدة فقط؛ ولا يُحفظ إلا بصمته، فانسخه فورًا. إن فقدته، أنشئ مفتاحًا جديدًا (فيتوقف القديم).

أرسله مع كل طلب في الترويسة Authorization: Bearer your-key. افتح /api/v1/ops على الموقع لترى كل العناوين؛ وأهمها:

/api/v1/ops/flights: الرحلات في الجو الآن وتلك المقدَّمة في الدقائق الأخيرة، مع نتيجة PIREP.
/api/v1/ops/pireps: سجل تقارير PIREP التي بُتّ فيها (المقبولة والمرفوضة وغيرها)، الأقدم قرارًا أولًا، مع المسار والأوقات والطائرة ومعدل الهبوط والنقاط.
/api/v1/ops/pilots و/api/v1/ops/pilots/FCV0002: قائمة الطيارين، ورتبة طيار واحد وقاعدته وساعاته وموقعه.
/api/v1/ops/routes و/api/v1/ops/fleet و/api/v1/ops/events و/api/v1/ops/ranks: الجدول والأسطول (الطرازات وكل طائرة) والفعاليات القادمة وسلّم الرتب، لموقعك الخاص.

كل العناوين للقراءة فقط. يمكن لكل مفتاح إرسال 120 طلبًا في الدقيقة كحد أقصى.

أمثلة

قائمة طياريك، 100 طيار في كل مرة: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
المئة التالية: الطلب نفسه مع offset=100. يبيّن next_offset في الرد أين تبدأ الصفحة التالية، ويكون null في الصفحة الأخيرة؛ ويبيّن total العدد الكامل. ومن دون limit تصلك القائمة كلها دفعة واحدة.
أسطولك: curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
تقارير PIREP التي بُتّ فيها منذ 1 أكتوبر: curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
الصفحة التي تليها: أضف cursor= مع قيمة next_cursor من الرد. احتفظ بآخر next_cursor وصلك، فتكمل أداتك من حيث توقفت بعد أي انقطاع. وإذا تغيّر القرار في PIREP لاحقًا، يظهر مجددًا بحالته الجديدة.

ما لا تعرضه الواجهة أبدًا

لا تعطي الواجهة عناوين البريد الإلكتروني ولا أي بيانات خاصة أخرى. وتُحترم خيارات الخصوصية لدى الطيارين هنا كما على الموقع:

الطيار الذي يخفي رحلاته عن الخرائط الحية لا يظهر في /flights ولا في /pireps.
الطيار الذي يخفي نفسه من لوحات الصدارة يظهر في /pireps بلا اسم ("pilot": null)، فلا يمكن ترتيب رحلاته.
الطيارون الذين سيُحذف حسابهم قريبًا لا يظهرون في أي مكان.

مفاتيح API المسمّاة

مع تفعيل مفاتيح API المسمّاة (الميزات الاختيارية)، أنشئ مفتاحًا لكل أداة، يُسمح له فقط بما يحتاجه: الرحلات أو الطيارون أو الجدول أو تغييرات الطيارين (تشغيل إعفاء الطيار من النشاط أو إيقافه). الرحلات تشمل /flights و/pireps؛ والجدول يشمل المسارات والأسطول والفعاليات والرتب. يمكن أن ينتهي المفتاح في تاريخ محدد ويمكن إلغاؤه وحده. حتى 10 مفاتيح لكل شركة؛ وتعرض القائمة متى استُخدم كل منها آخر مرة.

خطافات الويب

مع تفعيل خطافات الويب، يتلقى خادمك رسالة خلال ثوانٍ عند حدوث شيء: تقديم PIREP أو مراجعته، انضمام طيار أو مغادرته، تغيير رتبة، حجز رحلة أو إلغاؤه، إقلاع رحلة. كل رسالة موقّعة، ليتحقق خادمك أنها من Vaeroly (الترويسة X-Vaeroly-Signature، وهي HMAC للطابع الزمني والمحتوى بسرّ الخطاف).

يُعاد إرسال الرسائل الفاشلة لنحو 15 ساعة. لكل خطاف سجل إرسال وزر إرسال تجربة. الخطاف الذي يفشل 3 أيام يُوقف ويتلقى المالك رسالة بريد. حتى 5 خطافات لكل شركة (افتح السجل والإعدادات على الخطاف لترى سجله وزر التجربة). يمكن لكل خطاف إرسال تجربة، أو إعادة إرسال رسالة، مرة كل 30 ثانية، ويمكن للشركة إرسال 20 تجربة وإعادة إرسال في الساعة.