إنتربرايز

واجهة بيانات فلايترز للمطورين

زامن بيانات سفر شركتك مع نظام تخطيط الموارد أو مستودع البيانات أو النظام المالي. تُصدر المفاتيح من بوابة الأعمال.

هذه الواجهة للقراءة والمزامنة فقط. تتيح نقاط نهاية للقراءة وإشعارات تغيير موقّعة. لا يمكنها البحث أو الحجز أو الإصدار أو التعديل أو الإلغاء إطلاقًا.

احصل على مفاتيحك

المصادقة

أرسل مفتاحك كرمز Bearer في كل طلب عبر HTTPS. يرتبط كل مفتاح بحساب شركة واحد، فلا تقرأ إلا بياناتك.

curl https://flighterz.com/api/v1/me \
  -H "Authorization: Bearer flz_live_xxxxxxxxxxxx"

الرابط الأساسي: https://flighterz.com/api/v1

النطاقات

يحمل كل مفتاح مجموعة من نطاقات القراءة. تعيد نقطة النهاية insufficient_scope إذا لم يحمل المفتاح نطاقها.

account:readقراءة ملف الشركة والباقة ورصيد المحفظة.
employees:readقراءة دليل الموظفين.
org:readقراءة الإدارات ومراكز التكلفة والمشاريع.
trips:readقراءة الرحلات ومساراتها.
bookings:readقراءة حجوزات الطيران والخدمات والتذاكر.
invoices:readقراءة الفواتير الضريبية وقيود كشف الحساب.
budgets:readقراءة الميزانيات والإنفاق الملتزم به.
reports:readقراءة تحليلات الإنفاق المجمعة.

نقاط النهاية

نقطة النهايةالنطاقالوصف
GET/meaccount:readملف الشركة والباقة والمحفظة.
GET/employeesemployees:readقائمة الموظفين. مقسّمة لصفحات.
GET/employees/{id}employees:readموظف واحد.
GET/departmentsorg:readقائمة الإدارات.
GET/cost-centersorg:readقائمة مراكز التكلفة.
GET/projectsorg:readقائمة المشاريع.
GET/tripstrips:readقائمة الرحلات. المرشحات: status وdepartmentId.
GET/trips/{id}trips:readرحلة واحدة مع حجوزاتها.
GET/bookingsbookings:readقائمة حجوزات الطيران. المرشحات: status وtripId.
GET/bookings/{id}bookings:readحجز طيران واحد بالمعرّف أو المرجع.
GET/service-bookingsbookings:readقائمة حجوزات الفنادق والأنشطة والنقل.
GET/invoicesinvoices:readقائمة الفواتير الضريبية.
GET/budgetsbudgets:readالميزانيات مع الإنفاق الملتزم به لحظيًا.
GET/reports/spendreports:readالإنفاق المجمّع خلال اثني عشر شهرًا.

قوائم البيانات مقسّمة بمؤشر: مرّر ?limit= (بحد أقصى 200) و?cursor= من meta.nextCursor السابق. المبالغ بالهللات (الريال × 100).

الاستجابات

تعيد كل استجابة ناجحة الحقل data، وتضيف القوائم الحقل meta للتقسيم إلى صفحات.

{
  "data": [ { "id": "...", "reference": "TRP-ABCDE", "status": "TICKETED" } ],
  "meta": { "limit": 50, "count": 50, "nextCursor": "clx..." }
}

تعيد الأخطاء كائن error يحمل رمزًا ثابتًا ورسالة مفهومة.

{ "error": { "code": "insufficient_scope", "message": "This key is missing the trips:read scope." } }

حدود المعدل

تسمح مفاتيح التشغيل بـ 120 طلبًا في الدقيقة، ومفاتيح الاختبار بـ 60. تحمل كل استجابة ترويسات X-RateLimit-Limit وX-RateLimit-Window، ويتضمن الرد 429 ترويسة Retry-After.

خطافات الويب

سجّل روابط HTTPS في بوابتك واشترك في الأحداث. عند حدوث تغيير نرسل حدث JSON موقّعًا لتسحب الحالة الحالية من نقاط القراءة.

booking.createdتم تسجيل حجز طيران للشركة.
booking.issuedتم إصدار تذكرة حجز طيران للشركة.
service_booking.createdتم تسجيل حجز فندق أو نشاط أو نقل للشركة.
trip.createdتم فتح رحلة جديدة للشركة.
subscription.updatedتغيّرت باقة الشركة أو حالتها.

تحقق من التوقيع

تحمل كل رسالة ترويسة X-Flighterz-Signature. أعد حساب HMAC على الطابع الزمني والمحتوى الخام بمفتاح رابطك، وارفض أي طابع زمني قديم لمنع إعادة التشغيل.

// Header: X-Flighterz-Signature: t=1700000000,v1=<hex>
import crypto from "node:crypto";

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < toleranceSec;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

تُعاد المحاولات بتباعد متزايد حتى ثماني محاولات. ردّ بأي رمز 2xx للإقرار بالاستلام.

بيئة الاختبار

أنشئ مفتاح اختبار (flz_test_) للبناء على نفس نقاط القراءة بحد معدل أقل قبل الانتقال إلى مفتاح تشغيل.