كيفية استخدام مفتاح API لمساحة العمل

يمنحك مفتاح API لمساحة العمل وصولاً برمجياً إلى شهاداتك — اقرأها، واعتمدها، وأنشئها من مصادر خارجية، أو زامنها مع منتجك الخاص. هذه هي نقطة التكامل للمطورين الراغبين في تجاوز أدوات التضمين المدمجة.

إنشاء مفتاح API الخاص بك

الخطوة 1: فتح لوحة تحكم مساحة العمل

سجّل الدخول إلى SocialProof.Reviews وانتقل إلى مساحة عملك. انقر فوق تبويب الإعدادات أو التكاملات في الشريط الجانبي الأيسر.

الخطوة 2: إنشاء المفتاح

انقر فوق إنشاء مفتاح API. سيُعرَض مفتاحك الكامل مرة واحدة — انسخه فوراً واحفظه في موقع آمن مثل مدير كلمات المرور أو خزنة الأسرار.

بعد مغادرة الصفحة، تُعرَض الأحرف العشرة الأولى فقط من المفتاح. إذا فقدت المفتاح، يجب إعادة إنشائه — يُبطَل المفتاح القديم.

الخطوة 3: التخزين الآمن

لا تضع مفتاح API أبداً في:

JavaScript على جانب العميل (سيكون مرئياً في المتصفح)
مستودع GitHub عام
قناة Slack مشتركة أو مستند

احفظه دائماً في:

متغيرات البيئة على خادمك (process.env.SPR_API_KEY)
مدير الأسرار (AWS Secrets Manager، HashiCorp Vault، Doppler)
Firebase Secret Manager للـ Cloud Functions

المصادقة

أدرج مفتاح API في كل طلب كرمز Bearer في رأس Authorization:

Authorization: Bearer YOUR_API_KEY

يجب إجراء جميع طلبات API عبر HTTPS. يُرفَض طلبات HTTP.

عنوان URL الأساسي

https://api.socialproof.reviews/v1

جميع نقاط النهاية محدودة النطاق لمساحة عملك تلقائياً بناءً على مفتاح API.

نقاط النهاية الأساسية

سرد الشهادات

استرجاع جميع الشهادات في مساحة عملك:

GET /testimonials
Authorization: Bearer YOUR_API_KEY

معاملات الاستعلام الاختيارية:

المعامل	النوع	الوصف
`approved`	boolean	التصفية حسب حالة الاعتماد
`rating`	number	التصفية حسب الحد الأدنى للتقييم (1–5)
`limit`	number	عدد النتائج (الافتراضي 20، الحد الأقصى 100)
`offset`	number	إزاحة التصفح

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

{
  "data": [
    {
      "id": "t_abc123",
      "reviewer": {
        "name": "Sarah Chen",
        "email": "[email protected]",
        "jobTitle": "Product Manager",
        "company": "TechCorp"
      },
      "rating": 5,
      "review": "Incredible tool. We embedded the wall on our homepage and saw a 23% lift in demo requests.",
      "approved": true,
      "submittedAt": "2026-03-10T14:22:00Z",
      "photos": [],
      "videoUrl": null
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

الحصول على شهادة واحدة

GET /testimonials/:id
Authorization: Bearer YOUR_API_KEY

اعتماد شهادة

PATCH /testimonials/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "approved": true
}

إنشاء شهادة

استيراد شهادة من مصدر خارجي (استيراد CSV، أو ترحيل من منصة قديمة، أو استبيان مكتمل):

POST /testimonials
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "reviewer": {
    "name": "Marcus Webb",
    "email": "[email protected]",
    "jobTitle": "CEO",
    "company": "Acme Corp"
  },
  "rating": 5,
  "review": "We replaced our old review widget within a day. The setup was seamless.",
  "approved": false,
  "source": "import"
}

حذف شهادة

DELETE /testimonials/:id
Authorization: Bearer YOUR_API_KEY

يُرجع 204 No Content عند النجاح.

أمثلة على الكود

Node.js (fetch)

const SPR_API_KEY = process.env.SPR_API_KEY;

async function getApprovedTestimonials() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&limit=10',
    {
      headers: {
        'Authorization': `Bearer ${SPR_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );
  const data = await res.json();
  return data.data;
}

Python (requests)

import os
import requests

api_key = os.environ['SPR_API_KEY']
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(
    'https://api.socialproof.reviews/v1/testimonials',
    headers=headers,
    params={'approved': 'true', 'rating': 5}
)
testimonials = response.json()['data']

cURL

curl -X GET \
  "https://api.socialproof.reviews/v1/testimonials?approved=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

أنماط التكامل الشائعة

سحب الشهادات إلى موقعك الإلكتروني

إذا احتجت إلى عرض الشهادات بتصميم مخصص بالكامل لا يتطابق مع أدوات التضمين، اجلبها من API وصوّرها بنفسك:

// مثال على جانب الخادم في Next.js
export async function getStaticProps() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&rating=5',
    { headers: { Authorization: `Bearer ${process.env.SPR_API_KEY}` } }
  );
  const { data } = await res.json();
  return { props: { testimonials: data }, revalidate: 3600 };
}

الاعتماد التلقائي للشهادات ذات التقييم العالي عبر webhook + API

ادمج مشغّل الـ webhook مع API لإنشاء تدفق اعتماد آلي بالكامل:

ينطلق الـ webhook عند تقديم الشهادة
يستلم خادمك الحمل الزائد
إذا كان rating === 5، استدعِ PATCH /testimonials/:id مع { "approved": true }
تظهر الشهادة في جدار الحب فوراً

المزامنة مع CRM الخاص بك

بعد تقديم شهادة، استخدم API لسحب السجل الكامل ودفعه إلى CRM الخاص بك كملاحظة عميل أو نشاط:

// يُشغَّل بواسطة معالج webhook الخاص بك
async function syncToCRM(testimonialId) {
  const testimonial = await fetchTestimonial(testimonialId);
  await crm.createNote({
    contactEmail: testimonial.reviewer.email,
    note: `Left a ${testimonial.rating}-star testimonial: "${testimonial.review}"`,
    date: testimonial.submittedAt,
  });
}

حدود معدل الطلبات

الخطة	الطلبات في الدقيقة	الطلبات في اليوم
Starter	30	1,000
Pro	120	10,000
Agency	300	50,000

تتلقى الطلبات التي تتجاوز حد المعدل استجابة 429 Too Many Requests. نفّذ التراجع الأسّي في تكاملك.

مرجع الأخطاء

الحالة	المعنى
`200`	نجاح
`201`	تم الإنشاء
`204`	تم الحذف
`400`	طلب سيئ — تحقق من نص الطلب
`401`	مفتاح API غير صالح أو مفقود
`403`	المفتاح لا يملك صلاحية لهذا الإجراء
`404`	لم يُعثَر على الشهادة
`429`	تم تجاوز حد المعدل
`500`	خطأ في الخادم — حاول مجدداً