توثيق API - وقتم

نظرة عامة

توفر واجهة WAQTUM API إمكانية الوصول الكامل لجميع وظائف النظام برمجياً. جميع الطلبات والاستجابات بصيغة JSON.

Base URL: https://waqtum.qantrah.com/api/v1

فحص الحالة: GET /api/v1/health عام

المصادقة

جميع الطلبات المحمية تتطلب مفتاح API والسر في رأس Authorization:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET
Content-Type: application/json
Accept: application/json

يمكنك إنشاء مفاتيح API من لوحة التحكم في /admin/api

حدود الطلبات

يتم تحديد عدد الطلبات لكل مفتاح API حسب الباقة:

الباقة	الحد
أساسي	100 طلب/دقيقة
شركات	300 طلب/دقيقة
مؤسسات	1000 طلب/دقيقة

عند تجاوز الحد يتم إرجاع خطأ 429 (Too Many Requests).

المستندات

GET /documents قائمة المستندات

المعاملات الاختيارية:

`status`	draft, pending, in_progress, approved, rejected, expired, voided
`page`	رقم الصفحة
`per_page`	عدد النتائج (افتراضي: 15)

GET /documents/{id} عرض مستند

إرجاع تفاصيل المستند مع المعتمدين والحالة.

POST /documents إنشاء مستند

الحقول المطلوبة:

`title_ar`	string	العنوان بالعربية
`title_en`	string	العنوان بالإنجليزية
`file`	file (PDF)	ملف PDF (max 20MB)
`department`	string	القسم
`workflow_type`	string	sequential \| parallel

PUT /documents/{id} تحديث مستند

تحديث المستند (فقط المستندات بحالة draft).

DELETE /documents/{id} حذف مستند

حذف مستند (فقط المستندات بحالة draft).

POST /documents/{id}/send إرسال للاعتماد

إرسال المستند لمسار الاعتماد وإشعار المعتمدين.

POST /documents/{id}/void إلغاء مستند

إلغاء مستند مرسل (يرسل إشعار للمعتمدين).

GET /documents/{id}/status حالة المستند

إرجاع الحالة الحالية للمستند وتقدم الاعتماد.

GET /documents/{id}/download تحميل المستند

تحميل الملف النهائي المعتمد (PDF).

المعتمدون

GET /documents/{documentId}/approvers قائمة المعتمدين

POST /documents/{documentId}/approvers إضافة معتمد

`name_ar`	string	الاسم بالعربية
`name_en`	string	الاسم بالإنجليزية
`phone`	string	رقم الهاتف (WhatsApp)
`role_ar`	string	المسمى الوظيفي (عربي)
`role_en`	string	المسمى الوظيفي (إنجليزي)
`action_type`	string	sign \| stamp \| approve_only \| review_only
`order_index`	integer	ترتيب الاعتماد (للتسلسلي)

PUT /approvers/{id} تحديث معتمد

DELETE /approvers/{id} حذف معتمد

POST /approvers/{id}/remind إرسال تذكير

إعادة إرسال إشعار WhatsApp للمعتمد.

الويب هوك (Webhooks)

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

الأحداث المتاحة

الحدث	الوصف
`document.created`	عند إنشاء مستند جديد
`document.sent`	عند إرسال مستند للاعتماد
`document.approved`	عند اعتماد المستند بالكامل
`document.rejected`	عند رفض المستند
`approver.completed`	عند إتمام معتمد لإجرائه

إدارة الويب هوك

GET /webhooks/events الأحداث المتاحة

GET /webhooks قائمة الويب هوك

POST /webhooks إنشاء ويب هوك

`url`	string	عنوان URL الذي سيستقبل الإشعارات
`events`	array	قائمة الأحداث المطلوبة

POST /webhooks/{id}/test اختبار ويب هوك

POST /webhooks/{id}/rotate-secret تدوير المفتاح السري

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

يتم إرسال توقيع HMAC-SHA256 في رأس كل طلب ويب هوك:

X-Waqtum-Signature: sha256=HMAC_HASH

// Verification (PHP):
$hash = hash_hmac('sha256', $payload, $webhookSecret);
$valid = hash_equals($hash, $signatureFromHeader);

رموز الأخطاء

الرمز	الوصف
`400`	طلب غير صالح — تحقق من المعاملات
`401`	غير مصادق — مفتاح API غير صالح
`403`	ممنوع — لا توجد صلاحية لهذا الإجراء
`404`	غير موجود — المورد غير موجود
`422`	خطأ تحقق — البيانات غير صالحة
`429`	تجاوز الحد — طلبات كثيرة جداً
`500`	خطأ في الخادم — تواصل مع الدعم

شكل الاستجابة

{
    "success": false,
    "error": {
        "code": 422,
        "message": "Validation failed",
        "details": {
            "title_ar": ["The title_ar field is required."]
        }
    }
}

المحتويات

توثيق واجهة API