مرجع API

يوفّر وقتي واجهة برمجة تطبيقات (API) على نمط REST للوصول برمجيًا إلى بيانات المشتريات.

عنوان الأساس

Production: https://api.waqti.sa/v1

المصادقة

تتطلب جميع طلبات API المصادقة باستخدام رموز من نوع Bearer.

الحصول على رمز API

1. انتقل إلى الإعدادات ← مفاتيح API
2. انقر إنشاء مفتاح جديد
3. انسخ الرمز (يُعرض مرة واحدة فقط)

استخدام الرمز

curl -X GET "https://api.waqti.sa/v1/purchase-orders" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

أمان الرمز

• الرموز لا تنتهي صلاحيتها تلقائيًا، لكن يمكن إلغاؤها
• خزّن الرموز بأمان (متغيرات البيئة)
• لا تُضمّن الرموز في نظام التحكم بالإصدارات أبدًا

تنسيق الطلب

الترويسات

الترويسة	مطلوب	الوصف
Authorization	نعم	Bearer token
Accept	نعم	application/json
Content-Type	لطلبات POST/PUT	application/json
Accept-Language	لا	en أو ar (الافتراضي: en)

معاملات الاستعلام

معاملات شائعة لنقاط نهاية القوائم:

المعامل	النوع	الوصف
page	integer	رقم الصفحة (الافتراضي: 1)
per_page	integer	عدد العناصر في الصفحة (الافتراضي: 15، الحد الأقصى: 100)
sort	string	حقل الفرز (مثل created_at)
order	string	asc أو desc
search	string	مصطلح البحث

تنسيق الاستجابة

استجابة ناجحة

{
  "data": {
    "id": 1,
    "po_number": "PO-2025-0042",
    "status": "approved"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

استجابة قائمة

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73
  },
  "links": {
    "first": "https://api.waqti.sa/v1/purchase-orders?page=1",
    "last": "https://api.waqti.sa/v1/purchase-orders?page=5",
    "next": "https://api.waqti.sa/v1/purchase-orders?page=2",
    "prev": null
  }
}

استجابة خطأ

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "vendor_id": ["The vendor id field is required."]
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

رموز حالة HTTP

الرمز	الوصف
200	نجاح
201	تم الإنشاء
204	بلا محتوى (حذف ناجح)
400	طلب غير صالح
401	غير مصرّح
403	ممنوع
404	غير موجود
422	خطأ في التحقق من الصحة
429	تجاوز حد المعدل
500	خطأ في الخادم

تحديد المعدل

تُقيَّد طلبات API حسب معدل لكل رمز:

الخطة	طلبات/دقيقة	طلبات/يوم
أساسي (Basic)	60	1,000
احترافي (Professional)	300	10,000
مؤسسي (Enterprise)	1,000	غير محدود

تُضمَّن ترويسات حد المعدل في كل استجابة:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1705312200

نقاط النهاية المتاحة

أوامر الشراء

• GET /purchase-orders - قائمة أوامر الشراء
• POST /purchase-orders - إنشاء أمر شراء
• GET /purchase-orders/{id} - جلب أمر شراء
• PUT /purchase-orders/{id} - تحديث أمر شراء
• DELETE /purchase-orders/{id} - حذف أمر شراء
• POST /purchase-orders/{id}/submit - إرسال للموافقة

→ التوثيق الكامل لأوامر الشراء

الموردون

• GET /vendors - قائمة الموردين
• POST /vendors - إنشاء مورد
• GET /vendors/{id} - جلب مورد
• PUT /vendors/{id} - تحديث مورد

→ التوثيق الكامل للموردين

الميزانيات

• GET /budgets - قائمة الميزانيات
• GET /budgets/{id} - جلب ميزانية
• GET /budgets/{id}/utilization - جلب الاستخدام

→ التوثيق الكامل للميزانيات

الفواتير

• GET /invoices - قائمة الفواتير
• POST /invoices - إنشاء فاتورة
• GET /invoices/{id} - جلب فاتورة

→ التوثيق الكامل للفواتير

الويب هوكس (Webhooks)

سجّل Webhooks لتلقّي إشعارات فورية:

POST /webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["po.approved", "invoice.created"]
}

→ توثيق Webhooks

بيئة Sandbox

اختبر تكاملك باستخدام بيئة Sandbox:

Base URL: https://api.sandbox.waqti.sa/v1

تُعاد تهيئة بيانات Sandbox يوميًا عند الساعة 00:00 بتوقيت UTC.

الدعم

• الدعم الفني: api-support@waqti.sa
• واتساب: +966 55 578 4686
• سجل تغييرات API: /ar/changelog