مرجع نقاط نهاية API

مرجع كامل لجميع نقاط نهاية API وقتي. تتطلب جميع النقاط المصادقة وتُرجع استجابات JSON.

عنوان الأساس

https://{your-tenant}.waqti.net/api/v1

أوامر الشراء (Purchase Orders)

قائمة أوامر الشراء

GET /purchase-orders

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

المعامل	النوع	الوصف
page	integer	رقم الصفحة (الافتراضي: 1)
per_page	integer	عناصر لكل صفحة (الافتراضي: 15، الحد الأقصى: 100)
status	string	تصفية حسب الحالة: draft، pending، approved، rejected
approval_status	string	تصفية حسب حالة الموافقة
department_id	integer	تصفية حسب القسم
vendor_id	integer	تصفية حسب المورد
from_date	date	أوامر شراء أُنشئت في هذا التاريخ أو بعده
to_date	date	أوامر شراء أُنشئت في هذا التاريخ أو قبله
sort_by	string	الحقل للفرز (الافتراضي: created_at)
sort_order	string	asc أو desc (الافتراضي: desc)

مثال الطلب:

curl -X GET "https://acme.waqti.net/api/v1/purchase-orders?status=approved&per_page=25" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

مثال الاستجابة:

{
  "success": true,
  "data": [
    {
      "id": 123,
      "po_number": "PO-000123",
      "vendor": {
        "id": 45,
        "name": "Tech Supplies Ltd"
      },
      "department": {
        "id": 12,
        "name": "IT Department"
      },
      "total_inc_vat": 15000.00,
      "currency": "SAR",
      "status": "approved",
      "approval_status": "approved",
      "request_date": "2025-01-15",
      "required_date": "2025-01-30",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 150,
    "last_page": 6
  }
}

الحصول على أمر شراء واحد

GET /purchase-orders/{id}

مثال الاستجابة:

{
  "success": true,
  "data": {
    "id": 123,
    "po_number": "PO-000123",
    "vendor": {
      "id": 45,
      "name": "Tech Supplies Ltd",
      "contact_email": "sales@techsupplies.com"
    },
    "department": {
      "id": 12,
      "name": "IT Department"
    },
    "requester": {
      "id": 78,
      "name": "Ahmed Mohammed"
    },
    "lines": [
      {
        "id": 456,
        "line_number": 1,
        "description": "Laptop Dell XPS 15",
        "quantity": 5,
        "unit_price": 2500.00,
        "vat_rate": 15,
        "vat_amount": 1875.00,
        "total_ex_vat": 12500.00,
        "total_inc_vat": 14375.00
      }
    ],
    "documents": [
      {
        "id": 789,
        "filename": "quotation.pdf",
        "url": "/api/v1/documents/789/download"
      }
    ],
    "total_ex_vat": 12500.00,
    "total_vat": 1875.00,
    "total_inc_vat": 14375.00,
    "status": "approved",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

إنشاء أمر شراء

POST /purchase-orders

جسم الطلب:

{
  "department_id": 12,
  "vendor_id": 45,
  "required_date": "2025-02-15",
  "description": "Office equipment purchase",
  "expense_type": "OPEX",
  "currency": "SAR",
  "lines": [
    {
      "description": "Laptop Dell XPS 15",
      "quantity": 5,
      "unit_price": 2500.00,
      "vat_percentage": 15
    },
    {
      "description": "Monitor 27\"",
      "quantity": 10,
      "unit_price": 800.00,
      "vat_percentage": 15
    }
  ]
}

الاستجابة:

{
  "success": true,
  "message": "Purchase Order created successfully",
  "data": {
    "id": 124,
    "po_number": "PO-000124",
    ...
  }
}

الموافقة على أمر شراء

POST /purchase-orders/{id}/approve

جسم الطلب:

{
  "comments": "Approved for IT budget Q1"
}

رفض أمر شراء

POST /purchase-orders/{id}/reject

جسم الطلب:

{
  "reason": "Budget exceeded for this quarter"
}

---

الموردون (Vendors)

قائمة الموردين

GET /vendors

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

المعامل	النوع	الوصف
search	string	بحث بالاسم أو البريد
status	string	active، inactive، blacklisted
category	string	تصفية حسب فئة المورد

الحصول على مورد واحد

GET /vendors/{id}

إنشاء مورد

POST /vendors

جسم الطلب:

{
  "name": "Tech Supplies Ltd",
  "contact_person": "John Smith",
  "contact_email": "john@techsupplies.com",
  "contact_phone": "+966 50 123 4567",
  "address": "Riyadh, Saudi Arabia",
  "tax_number": "3001234567",
  "payment_terms": "net_30",
  "category": "IT Equipment"
}

تحديث مورد

PUT /vendors/{id}

---

الفواتير (Invoices)

قائمة الفواتير

GET /invoices

الحصول على فاتورة واحدة

GET /invoices/{id}

إنشاء فاتورة

POST /invoices

جسم الطلب:

{
  "purchase_order_id": 123,
  "invoice_number": "INV-2025-001",
  "invoice_date": "2025-01-20",
  "due_date": "2025-02-19",
  "lines": [
    {
      "po_line_id": 456,
      "quantity": 5,
      "unit_price": 2500.00
    }
  ]
}

---

الميزانيات (Budgets)

قائمة الميزانيات

GET /budgets

تفاصيل ميزانية

GET /budgets/{id}

تتضمن الاستجابة:

• المبالغ المخصصة (CAPEX/OPEX)
• المبالغ المنفقة
• المبالغ المحجوزة (أوامر شراء معلقة)
• المبالغ المتاحة
• نسب الاستخدام

---

التقارير (Reports)

تقرير الإنفاق

GET /reports/spending

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

المعامل	النوع	الوصف
from_date	date	تاريخ البداية
to_date	date	تاريخ النهاية
group_by	string	department، vendor، category، month

تقرير أداء الموردين

GET /reports/vendor-performance

تقرير حالة أوامر الشراء

GET /reports/po-status

تقرير مطابقة الفواتير

GET /reports/invoice-matching

---

Webhooks

قائمة Webhooks

GET /webhooks

إنشاء Webhook

POST /webhooks

جسم الطلب:

{
  "url": "https://your-system.com/waqti-webhook",
  "events": ["po.approved", "po.rejected", "invoice.created"],
  "secret": "your-webhook-secret"
}

اختبار Webhook

POST /webhooks/{id}/test

أحداث Webhook

الحدث	الوصف
po.created	تم إنشاء أمر شراء
po.submitted	أُرسل أمر الشراء للموافقة
po.approved	وُافق على أمر الشراء
po.rejected	رُفض أمر الشراء
po.updated	حُدّثت تفاصيل أمر الشراء
invoice.created	أُنشئت فاتورة
invoice.matched	طُابقت الفاتورة مع أمر الشراء
vendor.created	أُضيف مورد جديد
budget.alert	بُلغت عتبة الميزانية

---

معالجة الأخطاء

تتبع جميع الأخطاء تنسيقًا موحدًا:

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "vendor_id": ["The vendor id field is required."],
    "lines": ["At least one line item is required."]
  }
}

رموز حالة HTTP

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