API أوامر الشراء

مرجع كامل لنقاط نهاية أوامر الشراء (Purchase Order).

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

GET /v1/purchase-orders

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

المعامل	النوع	الوصف
status	string	تصفية حسب الحالة: draft، pending_approval، approved، rejected، completed، cancelled
vendor_id	integer	تصفية حسب المورد
department_id	integer	تصفية حسب القسم
created_from	date	تصفية حسب تاريخ الإنشاء (البداية)
created_to	date	تصفية حسب تاريخ الإنشاء (النهاية)
min_amount	number	تصفية حسب الحد الأدنى للمبلغ الإجمالي
max_amount	number	تصفية حسب الحد الأقصى للمبلغ الإجمالي

مثال الطلب

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

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

{
  "data": [
    {
      "id": 42,
      "po_number": "PO-2025-0042",
      "status": "approved",
      "vendor": {
        "id": 5,
        "name": "ABC Supplies Co."
      },
      "department": {
        "id": 2,
        "name": "Operations"
      },
      "currency": "SAR",
      "subtotal": 45000.00,
      "vat_amount": 6750.00,
      "total_amount": 51750.00,
      "created_at": "2025-01-15T10:30:00Z",
      "approved_at": "2025-01-15T14:22:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 42
  }
}

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

POST /v1/purchase-orders

جسم الطلب

{
  "vendor_id": 5,
  "department_id": 2,
  "project_id": 1,
  "currency": "SAR",
  "notes": "Quarterly office supplies",
  "delivery_address": "Riyadh, Main Office",
  "expected_delivery_date": "2025-02-01",
  "items": [
    {
      "description": "Printer Paper A4",
      "quantity": 100,
      "unit": "ream",
      "unit_price": 25.00,
      "vat_rate": 15
    },
    {
      "description": "Ink Cartridges",
      "quantity": 20,
      "unit": "piece",
      "unit_price": 150.00,
      "vat_rate": 15
    }
  ],
  "attachments": [
    {
      "name": "Quote.pdf",
      "url": "https://..."
    }
  ]
}

الاستجابة

{
  "data": {
    "id": 43,
    "po_number": "PO-2025-0043",
    "status": "draft",
    "vendor_id": 5,
    "department_id": 2,
    "subtotal": 5500.00,
    "vat_amount": 825.00,
    "total_amount": 6325.00,
    "items": [...],
    "created_at": "2025-01-15T16:00:00Z"
  }
}

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

GET /v1/purchase-orders/{id}

الاستجابة

{
  "data": {
    "id": 42,
    "po_number": "PO-2025-0042",
    "status": "approved",
    "vendor": {
      "id": 5,
      "name": "ABC Supplies Co.",
      "email": "sales@abcsupplies.com"
    },
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "project": {
      "id": 1,
      "name": "Q1 Procurement",
      "code": "PRJ-2025-Q1"
    },
    "created_by": {
      "id": 10,
      "name": "Mohammed Ali"
    },
    "currency": "SAR",
    "subtotal": 45000.00,
    "vat_amount": 6750.00,
    "total_amount": 51750.00,
    "notes": "Quarterly office supplies",
    "delivery_address": "Riyadh, Main Office",
    "expected_delivery_date": "2025-02-01",
    "items": [
      {
        "id": 101,
        "line_number": 1,
        "description": "Printer Paper A4",
        "quantity": 100,
        "unit": "ream",
        "unit_price": 25.00,
        "vat_rate": 15,
        "vat_amount": 375.00,
        "total": 2875.00
      }
    ],
    "approvals": [
      {
        "step": 1,
        "approver": "Ahmed Khalid",
        "status": "approved",
        "approved_at": "2025-01-15T14:22:00Z",
        "comments": "Approved"
      }
    ],
    "attachments": [
      {
        "id": 1,
        "name": "Quote.pdf",
        "size": 245000,
        "url": "https://..."
      }
    ],
    "audit_trail": [
      {
        "action": "created",
        "user": "Mohammed Ali",
        "timestamp": "2025-01-15T10:30:00Z"
      },
      {
        "action": "submitted",
        "user": "Mohammed Ali",
        "timestamp": "2025-01-15T10:35:00Z"
      },
      {
        "action": "approved",
        "user": "Ahmed Khalid",
        "timestamp": "2025-01-15T14:22:00Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T14:22:00Z"
  }
}

تحديث أمر شراء

PUT /v1/purchase-orders/{id}

WARNING

يمكن تحديث أوامر الشراء في حالة draft فقط. تتطلب الأوامر المُرسلة أو المُوافَق عليها تعديلات (amendments).

جسم الطلب

{
  "notes": "Updated notes",
  "expected_delivery_date": "2025-02-15",
  "items": [
    {
      "id": 101,
      "quantity": 150
    },
    {
      "description": "New Item",
      "quantity": 10,
      "unit_price": 100.00
    }
  ]
}

حذف أمر شراء

DELETE /v1/purchase-orders/{id}

WARNING

يمكن حذف أوامر الشراء في حالة draft فقط. يجب إلغاء الأوامر ذات الحالات الأخرى بدل الحذف.

الإرسال للموافقة

POST /v1/purchase-orders/{id}/submit

يُرسل أمر الشراء للموافقة. يُوجَّه الأمر وفق سير عمل الموافقة المُعدّ.

الاستجابة

{
  "data": {
    "id": 43,
    "status": "pending_approval",
    "current_approval_step": 1,
    "pending_approvers": [
      {
        "id": 15,
        "name": "Ahmed Khalid",
        "role": "Department Head"
      }
    ]
  }
}

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

POST /v1/purchase-orders/{id}/approve

جسم الطلب

{
  "comments": "Approved as requested"
}

رفض أمر شراء

POST /v1/purchase-orders/{id}/reject

جسم الطلب

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

إلغاء أمر شراء

POST /v1/purchase-orders/{id}/cancel

جسم الطلب

{
  "reason": "Vendor no longer available"
}

تنزيل PDF

GET /v1/purchase-orders/{id}/pdf

يُرجع أمر الشراء كمستند PDF.

الاستجابة

ملف PDF ثنائي مع الترويسات:

Content-Type: application/pdf
Content-Disposition: attachment; filename="PO-2025-0042.pdf"

بنود أمر الشراء (Line Items)

إضافة بند

POST /v1/purchase-orders/{id}/items

تحديث بند

PUT /v1/purchase-orders/{id}/items/{item_id}

حذف بند

DELETE /v1/purchase-orders/{id}/items/{item_id}