API Endpoints Reference

Complete reference for all Waqti API endpoints. All endpoints require authentication and return JSON responses.

Base URL

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

Purchase Orders

List Purchase Orders

GET /purchase-orders

Query Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 15, max: 100)
status	string	Filter by status: draft, pending, approved, rejected
approval_status	string	Filter by approval status
department_id	integer	Filter by department
vendor_id	integer	Filter by vendor
from_date	date	Filter POs created on or after this date
to_date	date	Filter POs created on or before this date
sort_by	string	Field to sort by (default: created_at)
sort_order	string	asc or desc (default: desc)

Example Request:

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"

Example Response:

{
  "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 Single Purchase Order

GET /purchase-orders/{id}

Example Response:

{
  "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"
  }
}

Create Purchase Order

POST /purchase-orders

Request Body:

{
  "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
    }
  ]
}

Response:

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

Approve Purchase Order

POST /purchase-orders/{id}/approve

Request Body:

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

Reject Purchase Order

POST /purchase-orders/{id}/reject

Request Body:

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

---

Vendors

List Vendors

GET /vendors

Query Parameters:

Parameter	Type	Description
search	string	Search by name or email
status	string	active, inactive, blacklisted
category	string	Filter by vendor category

Get Single Vendor

GET /vendors/{id}

Create Vendor

POST /vendors

Request Body:

{
  "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"
}

Update Vendor

PUT /vendors/{id}

---

Invoices

List Invoices

GET /invoices

Get Single Invoice

GET /invoices/{id}

Create Invoice

POST /invoices

Request Body:

{
  "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

List Budgets

GET /budgets

Get Budget Details

GET /budgets/{id}

Response includes:

• Allocated amounts (CAPEX/OPEX)
• Spent amounts
• Reserved amounts (pending POs)
• Available amounts
• Utilization percentages

---

Reports

Spending Report

GET /reports/spending

Query Parameters:

Parameter	Type	Description
from_date	date	Start date
to_date	date	End date
group_by	string	department, vendor, category, month

Vendor Performance Report

GET /reports/vendor-performance

PO Status Report

GET /reports/po-status

Invoice Matching Report

GET /reports/invoice-matching

---

Webhooks

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Request Body:

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

Test Webhook

POST /webhooks/{id}/test

Webhook Events

Event	Description
po.created	Purchase Order created
po.submitted	PO submitted for approval
po.approved	PO approved
po.rejected	PO rejected
po.updated	PO details updated
invoice.created	Invoice created
invoice.matched	Invoice matched with PO
vendor.created	New vendor added
budget.alert	Budget threshold reached

---

Error Handling

All errors follow a consistent format:

{
  "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 Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid/missing token
403	Forbidden - Insufficient permissions
404	Not Found
422	Validation Error
429	Too Many Requests
500	Internal Server Error