API الميزانيات

مرجع كامل لنقاط نهاية إدارة الميزانيات.

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

GET /v1/budgets

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

المعامل	النوع	الوصف
department_id	integer	تصفية حسب القسم
fiscal_year	integer	تصفية حسب السنة المالية (مثل 2026)
status	string	تصفية حسب الحالة: draft، active، closed، frozen
page	integer	رقم الصفحة (الافتراضي: 1)
per_page	integer	عناصر لكل صفحة (الافتراضي: 15، الحد الأقصى: 100)

مثال الطلب

curl -X GET "https://api.waqti.sa/v1/budgets?department_id=2&fiscal_year=2026&status=active&per_page=20" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

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

{
  "data": [
    {
      "id": 18,
      "name": "Operations — FY2026 Capex",
      "currency": "SAR",
      "allocated_amount": 500000.00,
      "committed_amount": 127500.00,
      "spent_amount": 84250.00,
      "available_amount": 288250.00,
      "utilization_percentage": 42.35,
      "department": {
        "id": 2,
        "name": "Operations",
        "code": "OPS"
      },
      "fiscal_year": 2026,
      "status": "active",
      "created_at": "2026-01-05T08:15:00Z"
    },
    {
      "id": 19,
      "name": "IT — Software & Licenses",
      "currency": "SAR",
      "allocated_amount": 200000.00,
      "committed_amount": 45000.00,
      "spent_amount": 120000.00,
      "available_amount": 35000.00,
      "utilization_percentage": 82.50,
      "department": {
        "id": 4,
        "name": "Information Technology",
        "code": "IT"
      },
      "fiscal_year": 2026,
      "status": "active",
      "created_at": "2026-01-06T11:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 20,
    "total": 24
  }
}

الحصول على ميزانية

GET /v1/budgets/{id}

يُرجع تفاصيل الميزانية الكاملة بما في ذلك المبالغ والقسم والفئة والطوابع الزمنية.

مثال الطلب

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

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

{
  "data": {
    "id": 18,
    "name": "Operations — FY2026 Capex",
    "category": "Capex",
    "currency": "SAR",
    "allocated_amount": 500000.00,
    "committed_amount": 127500.00,
    "spent_amount": 84250.00,
    "available_amount": 288250.00,
    "utilization_percentage": 42.35,
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "fiscal_year": 2026,
    "status": "active",
    "notes": "Includes warehouse upgrades and fleet maintenance.",
    "created_at": "2026-01-05T08:15:00Z",
    "updated_at": "2026-03-28T09:40:00Z"
  }
}

استخدام الميزانية (Utilization)

GET /v1/budgets/{id}/utilization

يُرجع تفصيل الاستخدام: الملتزم مقابل المنفق، وتقسيمات فترة اختيارية، والمتبقي مقابل التخصيص.

مثال الطلب

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

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

{
  "data": {
    "budget_id": 18,
    "name": "Operations — FY2026 Capex",
    "currency": "SAR",
    "allocated_amount": 500000.00,
    "committed_amount": 127500.00,
    "spent_amount": 84250.00,
    "available_amount": 288250.00,
    "utilization_percentage": 42.35,
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "fiscal_year": 2026,
    "status": "active",
    "breakdown": {
      "by_po_status": {
        "approved_uninvoiced": 43250.00,
        "invoiced_pending_payment": 41000.00,
        "paid": 84250.00
      },
      "remaining_against_committed": 211750.00
    },
    "as_of": "2026-04-04T12:00:00Z"
  }
}

إنشاء ميزانية

POST /v1/budgets

جسم الطلب

{
  "name": "Facilities — FY2026 Opex",
  "allocated_amount": 350000.00,
  "department_id": 3,
  "fiscal_year": 2026,
  "category": "Opex",
  "currency": "SAR",
  "notes": "Building maintenance, utilities, and security services."
}

مثال الطلب

curl -X POST "https://api.waqti.sa/v1/budgets" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Facilities — FY2026 Opex",
    "allocated_amount": 350000.00,
    "department_id": 3,
    "fiscal_year": 2026,
    "category": "Opex",
    "currency": "SAR"
  }'

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

{
  "data": {
    "id": 27,
    "name": "Facilities — FY2026 Opex",
    "category": "Opex",
    "currency": "SAR",
    "allocated_amount": 350000.00,
    "committed_amount": 0.00,
    "spent_amount": 0.00,
    "available_amount": 350000.00,
    "utilization_percentage": 0.00,
    "department": {
      "id": 3,
      "name": "Facilities",
      "code": "FAC"
    },
    "fiscal_year": 2026,
    "status": "draft",
    "created_at": "2026-04-04T14:22:00Z"
  }
}

تحديث ميزانية

PUT /v1/budgets/{id}

جسم الطلب

{
  "name": "Operations — FY2026 Capex (revised)",
  "allocated_amount": 525000.00,
  "department_id": 2,
  "fiscal_year": 2026,
  "category": "Capex",
  "status": "active",
  "notes": "Adjusted after Q1 forecast review."
}

جميع الحقول اختيارية؛ أرسل فقط السمات المراد تغييرها.

مثال الطلب

curl -X PUT "https://api.waqti.sa/v1/budgets/18" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "allocated_amount": 525000.00,
    "notes": "Adjusted after Q1 forecast review."
  }'

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

{
  "data": {
    "id": 18,
    "name": "Operations — FY2026 Capex",
    "category": "Capex",
    "currency": "SAR",
    "allocated_amount": 525000.00,
    "committed_amount": 127500.00,
    "spent_amount": 84250.00,
    "available_amount": 313250.00,
    "utilization_percentage": 40.33,
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "fiscal_year": 2026,
    "status": "active",
    "notes": "Adjusted after Q1 forecast review.",
    "created_at": "2026-01-05T08:15:00Z",
    "updated_at": "2026-04-04T15:05:00Z"
  }
}