توثيق API

تكام�� مع منصتنا باستخدام واجهة REST API

المصادقة

تتطلب جميع طلبات API رمز Bearer. أنشئ مفتاح API من الإعدادات > التكاملات.

curl -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  https://your-domain.com/api/v1/tenders

حدود الاستخدام

تكون طلبات API محدودة حسب خطة الاشتراك. Pro: 1,000/يوم، Enterprise: غير محدود.

ترقيم الصفحات

تُرجع جميع نقاط النهاية المُرقّمة استجابات بالهيكل التالي:

{
  "data": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

نقاط النهاية

GET/api/v1/tenders

List tenders with pagination and filtering

الصلاحية المطلوبة: tenders.read

المعامل	النوع	مطلوب	الوصف
`page`	number	لا	Page number (default: 1)
`page_size`	number	لا	Items per page (max: 100)
`source`	string	لا	Filter by source (etimad, nupco)
`agency`	string	لا	Filter by agency name

GET/api/v1/tenders/:id

Get tender details with line items

الصلاحية المطلوبة: tenders.read

المعامل	النوع	مطلوب	الوصف
`id`	number	نعم	Tender ID

GET/api/v1/search

Search tenders by keyword (including item names)

الصلاحية المطلوبة: search

المعامل	النوع	مطلوب	الوصف
`q`	string	لا	Search query
`source`	string	لا	Filter by source
`agency`	string	لا	Filter by agency
`type`	string	لا	Filter by tender type
`date_from`	string	لا	Start date (ISO)
`date_to`	string	لا	End date (ISO)
`page`	number	لا	Page number
`page_size`	number	لا	Items per page

GET/api/v1/bids

List your organization's bids

الصلاحية المطلوبة: bids.read

المعامل	النوع	مطلوب	الوصف
`status`	string	لا	Filter by status
`page`	number	لا	Page number
`page_size`	number	لا	Items per page

GET/api/v1/favorites

List your organization's favorite tenders

الصلاحية المطلوبة: favorites.read

المعامل	النوع	مطلوب	الوصف
`page`	number	لا	Page number
`page_size`	number	لا	Items per page

الويب هوك

استقبل إشعارات فورية عند حدوث أحداث. كوّن الويب هوك من الإعدادات > التكاملات.

الأحداث المتاحة

tender.matched — مناقصة جديدة تطابق تنبيهاتك أو منتجاتك
bid.status_changed — تغيرت حالة العرض
deadline.approaching — يقترب الموعد النهائي للمناقصة

التحقق من التوقيع

يتم توقيع جميع حمولات الويب هوك بـ HMAC-SHA256. تحقق من رأس X-Webhook-Signature:

// Verify webhook signature
const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature === expected) {
  // Valid webhook
}