Vendors API

Complete reference for Vendor management endpoints.

See also: Vendor Management User Guide.

List Vendors

GET /v1/vendors

Query Parameters

Parameter	Type	Description
status	string	Filter by status: active, inactive, blocked
category	string	Filter by category
search	string	Search by name or email
min_score	integer	Filter by minimum performance score (0-100)

Example Request

curl -X GET "https://api.waqti.sa/v1/vendors?status=active" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    {
      "id": 5,
      "name": "ABC Supplies Co.",
      "email": "sales@abcsupplies.com",
      "phone": "+966500000000",
      "status": "active",
      "category": "Office Supplies",
      "performance_score": 92,
      "total_orders": 45,
      "total_spend": 250000.00,
      "created_at": "2024-06-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 28
  }
}

Create Vendor

POST /v1/vendors

Request Body

{
  "name": "New Supplier Ltd.",
  "name_ar": "المورد الجديد",
  "email": "contact@newsupplier.com",
  "phone": "+966500000000",
  "address": "Riyadh, Saudi Arabia",
  "vat_number": "300000000000003",
  "cr_number": "1010000000",
  "category": "IT Equipment",
  "payment_terms": 30,
  "currency": "SAR",
  "bank_name": "Al Rajhi Bank",
  "bank_account": "SA0000000000000000000000",
  "contacts": [
    {
      "name": "Ahmed Ali",
      "email": "ahmed@newsupplier.com",
      "phone": "+966500000001",
      "role": "Sales Manager"
    }
  ]
}

Get Vendor

GET /v1/vendors/{id}

Returns full vendor details including performance metrics.

Update Vendor

PUT /v1/vendors/{id}

Get Vendor Performance

GET /v1/vendors/{id}/performance

Response

{
  "data": {
    "vendor_id": 5,
    "overall_score": 92,
    "metrics": {
      "delivery_time": {
        "score": 95,
        "average_days": 3.2,
        "on_time_percentage": 96
      },
      "quality": {
        "score": 90,
        "defect_rate": 2.1,
        "return_rate": 1.5
      },
      "pricing": {
        "score": 88,
        "competitiveness": "good"
      },
      "responsiveness": {
        "score": 94,
        "average_response_hours": 4.5
      }
    },
    "trends": {
      "last_30_days": 93,
      "last_90_days": 91,
      "last_year": 89
    }
  }
}

Get Vendor Orders

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

Returns all purchase orders for a specific vendor.

Block Vendor

POST /v1/vendors/{id}/block

Request Body

{
  "reason": "Quality issues on last 3 orders"
}

Unblock Vendor

POST /v1/vendors/{id}/unblock