واجهة قراءة فقط · الإصدار الأول

TAC Flow Partner API

واجهة ربط مستقرة لسحب بيانات شركتك إلى أنظمتك — تخطيط الموارد، والمحاسبة، وإدارة الصيانة، ولوحات التقارير، والتكاملات المخصصة — مع إشعارات لحظية موقّعة عند وقوع الأحداث التشغيلية. كل الردود معزولة بشركة المفتاح وصلاحياته ووحدات الشركة المفعلة.

التوثيق

أصدر مفتاح الربط من: الإعدادات ← «الربط والتكامل» ← «إصدار مفتاح» — يظهر المفتاح مرة واحدة فقط، ويُمرر في ترويسة التخويل مع كل طلب.

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/assets?page=1&limit=100"

⚠️ قسم غير مفعل لشركتك لا تُرجع بياناته إطلاقًا حتى لو ملك المفتاح صلاحيته — العزل بالوحدات مطبق على كل النقاط.

البدء في خمس خطوات

أصدر مفتاحًا

بالصلاحيات المطلوبة من شاشة «الربط والتكامل» واحفظه فور ظهوره.

نفّذ أول طلب

على نقطة الأصول بالأمر أعلاه — سترجع أصول شركتك خلال ثوانٍ.

رقّم وزامن

استخدم page وlimit للترقيم، وupdated_since للمزامنة التزايدية الدورية.

سجّل اشتراك إشعارات

عنوان استقبال + الأحداث المطلوبة، واحفظ سر التوقيع.

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

لكل إشعار وارد قبل معالجته — المثال البرمجي في قسم الإشعارات أدناه.

الترقيم والمزامنة

المعامل	الوصف
`page`	رقم الصفحة — الافتراضي 1
`limit`	حجم الصفحة — الافتراضي 50 والأقصى 200
`updated_since`	تاريخ بصيغة ISO-8601 — يرجع السجلات المُنشأة أو المحدثة بعده فقط، للمزامنة الدورية بلا سحب كامل

{ "data": [ ... ],
  "pagination": { "page": 1, "limit": 50, "total": 1234, "has_more": true } }

نقاط القراءة

ثماني نقاط تغطي كل الأقسام التشغيلية — كلها بأسلوب واحد: نفس التوثيق ونفس المظروف ونفس الترقيم.

GET /api/partner/v1/assets

الأصول Assets

سجل المعدات والمركبات بحالتها ومواقعها، شاملًا الأصول المُسقطة من الأسطول.

Scopeassets:read Modulesheavy-equipment vehicles ShapeAsset

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`asset_class`	string	تصفية حسب الفئة: مركبة أو معدة ثقيلة
`status`	string	تصفية حسب الحالة التشغيلية
`include_decommissioned`	boolean	شمول الأصول المُسقطة (الافتراضي: نعم)

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/assets?page=1&limit=100"

GET /api/partner/v1/maintenance-reports

تقارير الصيانة Maintenance reports

تقارير الصيانة المعتمدة بمهامها وتكاليفها وقراءات العدادات.

Scopemaintenance:read Modulespreventive reports ShapeMaintenanceReport

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`equipment_id`	string	تصفية حسب الأصل
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/maintenance-reports?from=2026-07-01&to=2026-07-31"

GET /api/partner/v1/incidents

البلاغات Incidents

بلاغات الأعطال بحالتها وتكاليفها.

Scopeincidents:read Modulesincidents ShapeIncident

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`equipment_id`	string	تصفية حسب الأصل
`status`	string	تصفية حسب الحالة
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/incidents?status=open"

GET /api/partner/v1/movements

الحركات والعُهد Movements & custody

حركات الأصول والعُهد: من أين إلى أين ومن المستلم.

Scopemovements:read Modulesmovements ShapeMovement

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`equipment_id`	string	تصفية حسب الأصل
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/movements?equipment_id=<id>"

GET /api/partner/v1/fuel/dispenses

عمليات الديزل الداخلي Internal fuel dispenses

عمليات صرف الديزل الداخلي من الصهاريج للمعدات.

Scopefuel:read Modulesfuel-internal ShapeFuelDispense

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`equipment_id`	string	تصفية حسب الأصل
`tanker_id`	string	تصفية حسب الصهريج
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/fuel/dispenses?from=2026-07-01"

GET /api/partner/v1/fuel/transactions

حركات بطاقات الوقود Fuel card transactions

حركات بطاقات الوقود للمركبات (محايد لمزوّد الخدمة).

Scopefuel:read Modulesfuel-analytics ShapeFuelTransaction

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`plate_number`	string	تصفية حسب رقم اللوحة
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/fuel/transactions?from=2026-07-01&to=2026-07-31"

GET /api/partner/v1/meters/readings

قراءات العدادات Meter readings

قراءات الكيلومترات وساعات التشغيل لكل أصل.

Scopemeters:read Modulesheavy-equipment vehicles ShapeMeterReading

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`equipment_id`	string	تصفية حسب الأصل
`meter_type`	string	نوع العداد
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/meters/readings?equipment_id=<id>&from=2026-07-01"

GET /api/partner/v1/inspections

الفحص اليومي Daily inspections

نتائج الفحص اليومي المعتمدة بملخصها.

Scopeinspections:read Modulesdaily-inspection ShapeInspection

المعامل	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي 1)
`limit`	integer	حجم الصفحة (الافتراضي 50، الأقصى 200)
`updated_since`	date-time	المزامنة التزايدية — السجلات بعد هذه اللحظة فقط
`equipment_id`	string	تصفية حسب الأصل
`result`	string	تصفية حسب النتيجة
`from`	date	من تاريخ
`to`	date	إلى تاريخ

curl -H "Authorization: Bearer tacp_live_..." \
  "https://tacflow.app/api/partner/v1/inspections?result=needs_action"

الصلاحيات

Scope	الوصف
`assets:read`	قراءة الأصول
`maintenance:read`	قراءة تقارير الصيانة
`incidents:read`	قراءة البلاغات
`movements:read`	قراءة الحركات
`fuel:read`	قراءة الوقود
`meters:read`	قراءة العدادات
`inspections:read`	قراءة الفحص اليومي
`webhooks:manage`	إدارة الإشعارات اللحظية

الإشعارات اللحظية

سجّل عنوان استقبال واختر الأحداث؛ يرسل النظام طلبًا موقّعًا فور وقوع الحدث، ويعيد المحاولة تلقائيًا حتى خمس محاولات بتدرج زمني عند التعذر.

Event	الحدث
`incident.reported`	تسجيل بلاغ عطل
`maintenance_report.approved`	اعتماد تقرير صيانة
`movement.approved`	اعتماد حركة
`fuel.dispense_recorded`	تسجيل عملية وقود
`asset.decommissioned`	إسقاط أصل من الأسطول

ترويسات التسليم

X-TacFlow-Event X-TacFlow-Signature: sha256=<hex> X-TacFlow-Delivery X-TacFlow-Retry

التحقق من التوقيع — Node.js

const crypto = require('crypto')

function verifyTacFlowSignature(rawBody, signatureHeader, secret) {
  // signatureHeader = 'sha256=<hex>' (X-TacFlow-Signature)
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
}

رموز الأخطاء

كل خطأ يرجع بمظروف ثابت واحد:

{ "error": { "code": "insufficient_scope", "message": "..." } }

unauthorized key_expired key_revoked insufficient_scope module_disabled subscription_suspended invalid_request rate_limited not_found method_not_allowed server_error

حدود الطلبات

120 طلبًا في الدقيقة لكل مفتاح — عند التجاوز يرجع رمز 429 مع ترويسة Retry-After، وترويسات X-RateLimit-Limit وX-RateLimit-Remaining مرافقة لكل رد ناجح.