مرجع API

مقدمة

واجهة Reviewlee API هي واجهة RESTful تتيح لك إدارة جميع جوانب بنية المراجعات برمجياً. جميع نقاط النهاية مُنسَّخة تحت /api/v1/ وتعيد استجابات JSON.

• نقاط نهاية RESTful مع أجسام طلب/استجابة JSON
• مصادقة بمفتاح API مع نطاقات دقيقة (قراءة، كتابة، مسؤول)
• نقاط نهاية قوائم مقسمة لصفحات بتنسيق meta متسق
• دعم خطافات الويب لإشعارات الأحداث الفورية

الرابط الأساسي

يجب إجراء جميع طلبات API إلى الرابط الأساسي التالي. جميع نقاط النهاية تتطلب البادئة /api/v1/.

تتم إصدارية API عبر مسار الرابط. الإصدار الحالي هو v1. سنعلن عن إيقاف الإصدارات القديمة مسبقاً.

المصادقة

قم بمصادقة طلبات API باستخدام مصادقة Bearer مع مفتاح API الخاص بمنظمتك. تبدأ المفاتيح بـ rk_ وهي مرتبطة بمنظمة واحدة.

curl -X GET https://api.reviewlee.com/api/v1/reviews \
  -H "Authorization: Bearer rk_your_api_key_here"

حدود الطلبات

طلبات API محدودة لكل مفتاح API. يتم تضمين رؤوس الحدود في كل استجابة لمساعدتك على تتبع الاستخدام.

التصفح

جميع نقاط نهاية القوائم تدعم التصفح عبر معاملات page و limit. تتضمن الاستجابات كائن meta مع العدد الإجمالي ومعلومات الصفحة.

// Paginated response format
{
  "data": [...],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

// Query parameters
GET /api/v1/reviews?page=2&limit=10

المراجعات

المراجعات هي المورد الأساسي. قم بعرض واسترجاع وإدارة وإرسال المراجعات. لا يمكن حذف المراجعات — فقط إخفاؤها عبر الإشراف مع سجل تدقيق كامل.

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

{
  "id": "cm...",
  "rating": 5,
  "title": "Excellent service",
  "content": "Great experience with the product!",
  "reviewer_name": "Jane Doe",
  "reviewer_email": "[email protected]",
  "verification_status": "verified",
  "is_hidden": false,
  "created_at": "2026-01-15T12:00:00Z",
  "form_id": "cm..."
}

نماذج المراجعات

تحدد النماذج كيفية جمع المراجعات. قم بتكوين أوضاع التحقق والحقول المخصصة وروابط الإرسال العامة.

المنظمات

إدارة إعدادات المنظمة وأعضاء الفريق والدعوات. جميع البيانات مرتبطة بالمنظمة المرتبطة بمفتاح API الخاص بك.

التصديرات

تصدير بيانات المراجعات بتنسيق CSV أو JSON. تعمل التصديرات بشكل غير متزامن — أنشئ مهمة ثم قم بالتنزيل عندما تكون جاهزة.

// Create an export job
POST /api/v1/organizations/:orgId/exports
{
  "format": "csv",   // "csv" or "json"
  "filters": {
    "startDate": "2026-01-01",
    "endDate": "2026-02-01"
  }
}

خطافات الويب

تلقي إشعارات فورية عند حدوث أحداث في منظمتك. حمولات خطافات الويب موقعة بـ HMAC-SHA256 للتحقق.

// Webhook payload example
{
  "event": "review.created",
  "timestamp": "2026-02-15T10:30:00Z",
  "data": {
    "id": "cm...",
    "rating": 5,
    "content": "Amazing product!",
    "reviewer_name": "John Smith"
  }
}

// Verify HMAC signature
const signature = request.headers["x-webhook-signature"];
const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(JSON.stringify(body))
  .digest("hex");

عنصر التضمين

قم بتضمين مراجعاتك في أي موقع ويب باستخدام عنصر JavaScript خفيف. يدعم تخطيطات القائمة والشبكة والعرض الدوار مع سمات فاتحة وداكنة.

<!-- Embed reviews on any website -->
<div id="reviewlee-widget" data-slug="your-business-slug"></div>
<script src="https://www.reviewlee.com/embed.js"></script>

الملفات العامة

الملفات التجارية العامة هي صفحات مفهرسة لمحركات البحث تعرض المراجعات مع التقييمات المجمعة. إدارة إعدادات الملف والوصول للبيانات العامة.

مفاتيح API

إنشاء وعرض وتدوير وإلغاء مفاتيح API لمنظمتك. المفاتيح محددة بنطاقات قراءة أو كتابة أو مسؤول.

التحقق

تحقق من المراجعات باستخدام طرق متعددة. يمكن تكوين كل نموذج بوضع تحقق محدد.

طلبات المراجعات

أتمتة جمع المراجعات بإرسال طلبات بالبريد الإلكتروني للعملاء. دعم الإرسال الفردي والجماعي مع تتبع التسليم.

معالجة الأخطاء

تستخدم API رموز حالة HTTP القياسية. رموز 2xx تشير للنجاح، 4xx لأخطاء العميل، و5xx لأخطاء الخادم.

// Error response format
{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "error": "Unauthorized"
}