تجاوز إلى المحتوى الرئيسي
قارن لي
توثيق API لقارن لي

واجهات آمنة لقراءة الكتالوج وإدارة الإدخال التحريري

هذه الصفحة مخصصة للمطورين والمشغلين. واجهة v1 للقراءة العامة المحمية بمفتاح read، وواجهة Agent لإدخال الأدوات والمحتوى ضمن مسار مراجعة. قارن لي لا ينشر أدوات آليا بلا مصدر ومراجعة.

قاعدة الإطلاق الحالية

التوسع في الأدوات يجب أن يمر عبر مصدر واضح وحالة مراجعة. استخدم الواجهة لتسريع الإدخال، وليس لتجاوز جودة الكتالوج.

مفاتيح API

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

نطاقات واضحة

استخدم read للواجهات العامة، وagent:read أو agent:write للوكيل حسب الحاجة.

مراجعة قبل النشر

الحالة الافتراضية في إدخال الأدوات هي review_only حتى يراجعها محرر.

المصادقة

واجهة القراءة العامة v1

أرسل مفتاحا يحمل scope: read في ترويسة Authorization.

Authorization: Bearer qrn_your_api_key

واجهة Agent API

أرسل مفتاح الوكيل في x-agent-api-key، وامنحه أقل نطاقات ممكنة.

x-agent-api-key: qrn_your_api_key
لإنشاء مفتاح جديد، سجل الدخول بحساب إداري ثم افتح مفاتيح API. لا تشارك المفاتيح داخل تطبيقات المتصفح أو مستودعات عامة.

Public API v1

Base URL: https://www.qaranly.com/api/v1

الحد الافتراضي الحالي: 60 طلبا/دقيقة و10,000 طلب/يوم للمفتاح.

GET/api/v1/toolsscope: read

إرجاع أدوات منشورة وموثقة للاستخدام العام مع الفلترة والصفحات.

معاملات الاستعلام: category, search, featured, verified, pricing, limit, offset, locale

GET/api/v1/tools/[slug]scope: read

إرجاع ملف أداة واحدة عبر الرابط canonical الخاص بها.

معاملات الاستعلام: locale

GET/api/v1/categoriesscope: read

إرجاع التصنيفات المنشورة لاستخدامها في الفلاتر أو الواجهات الخارجية.

معاملات الاستعلام: locale

Agent API

هذه الواجهة تشغيلية لإدخال الأدوات والمحتوى. لا تستخدمها لإطلاق نشر جماعي بلا مراجعة، ولا تمنح agent:delete إلا لوظيفة محددة ومراقبة.

GET/api/agent/toolsscope: agent:read

قراءة قائمة الأدوات من منظور إداري أو آلي.

معاملات الاستعلام: page, limit

POST/api/agent/toolsscope: agent:write

إرسال أداة جديدة أو تحديث أداة موجودة. الوضع الافتراضي هو review_only حتى لا تنشر الأدوات قبل المراجعة.

{
  "slug": "tool-slug",
  "websiteUrl": "https://example.com",
  "pricingType": "freemium",
  "publishState": "review_only",
  "translations": {
    "ar": {
      "name": "اسم الأداة",
      "shortDescription": "وصف قصير وواضح",
      "fullContent": "مراجعة تحريرية أو وصف كامل"
    },
    "en": {
      "name": "Tool name",
      "shortDescription": "Short English description"
    }
  },
  "categoryIds": ["category-uuid"],
  "sourceName": "Official website",
  "sourceUrl": "https://example.com"
}
PUT/api/agent/toolsscope: agent:write

تحديث أداة موجودة عبر slug مع دعم حالة النشر والثقة والمصدر.

GET/api/agent/categoriesscope: agent:read

قراءة التصنيفات لاستخدامها أثناء تجهيز دفعات الأدوات.

POST/api/agent/categoriesscope: agent:write

إنشاء تصنيف جديد عندما يكون ضروريا لمسار تحريري واضح.

GET/api/agent/statsscope: agent:read

قراءة أرقام تشغيلية مختصرة عن الكتالوج والمحتوى.

مسار العمل الموصى به

  1. 1اجمع المصدر الرسمي أو صفحة المنتج قبل أي إدخال.
  2. 2أرسل الأدوات الجديدة بحالة review_only أو pending_review عند الشك.
  3. 3لا تستخدم published إلا بعد تحقق تحريري واضح من الاسم والرابط والتصنيف.
  4. 4احتفظ بمفتاح API على الخادم فقط، ولا تضعه في المتصفح أو ملفات عامة.

أخطاء متوقعة

401-مفتاح مفقود أو غير صحيح
403-المفتاح لا يملك النطاق المطلوب
400-جسم الطلب أو الحقول غير صالحة
404-العنصر غير موجود
429-تجاوز حد الطلبات
500-خطأ داخلي يجب تتبعه من السجلات
توثيق واجهة API | قارن لي