API Reference

Waqti provides a RESTful API for programmatic access to procurement data.

Base URL

Production: https://api.waqti.sa/v1

Authentication

All API requests require authentication using Bearer tokens.

Getting an API Token

1. Navigate to Settings → API Keys
2. Click Generate New Key
3. Copy the token (shown only once)

Using the Token

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

Token Security

• Tokens never expire but can be revoked
• Store tokens securely (environment variables)
• Never commit tokens to version control

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer token
Accept	Yes	application/json
Content-Type	For POST/PUT	application/json
Accept-Language	No	en or ar (default: en)

Query Parameters

Common query parameters for list endpoints:

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 15, max: 100)
sort	string	Sort field (e.g., created_at)
order	string	asc or desc
search	string	Search term

Response Format

Success Response

{
  "data": {
    "id": 1,
    "po_number": "PO-2025-0042",
    "status": "approved"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

List Response

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73
  },
  "links": {
    "first": "https://api.waqti.sa/v1/purchase-orders?page=1",
    "last": "https://api.waqti.sa/v1/purchase-orders?page=5",
    "next": "https://api.waqti.sa/v1/purchase-orders?page=2",
    "prev": null
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "vendor_id": ["The vendor id field is required."]
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

Rate Limiting

API requests are rate limited per token:

Plan	Requests/Minute	Requests/Day
Basic	60	1,000
Professional	300	10,000
Enterprise	1,000	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1705312200

Available Endpoints

Purchase Orders

• GET /purchase-orders - List POs
• POST /purchase-orders - Create PO
• GET /purchase-orders/{id} - Get PO
• PUT /purchase-orders/{id} - Update PO
• DELETE /purchase-orders/{id} - Delete PO
• POST /purchase-orders/{id}/submit - Submit for approval

→ Full PO Documentation

Vendors

• GET /vendors - List vendors
• POST /vendors - Create vendor
• GET /vendors/{id} - Get vendor
• PUT /vendors/{id} - Update vendor

→ Full Vendor Documentation

Budgets

• GET /budgets - List budgets
• GET /budgets/{id} - Get budget
• GET /budgets/{id}/utilization - Get utilization

→ Full Budget Documentation

Invoices

• GET /invoices - List invoices
• POST /invoices - Create invoice
• GET /invoices/{id} - Get invoice

→ Full Invoice Documentation

Webhooks

Register webhooks to receive real-time notifications:

POST /webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["po.approved", "invoice.created"]
}

→ Webhook Documentation

Sandbox Environment

Test your integration with our sandbox:

Base URL: https://api.sandbox.waqti.sa/v1

Sandbox data is reset daily at 00:00 UTC.

Support

• Technical Support: api-support@waqti.sa
• WhatsApp: +966 55 578 4686
• API Changelog: /changelog