المصادقة

آخر تحديث: 2026-10-024 دقيقة قراءة

يُصادَق كل طلب بمفتاح API. أرسله رمزا من نوع Bearer:

Authorization: Bearer gsk_live_xxx

إذا كان رمز Bearer غير مريح في بيئتك، فالترويسة x-api-key: gsk_live_xxx مقبولة أيضا. أي طلب بلا مفتاح يتلقى 401 مع title: invalid_key.

صيغة المفتاح

gsk_live_<id>_<secret> أو gsk_test_<id>_<secret>. المفتاح gsk_live ينفذ عملا حقيقيا ويُخصم مقابله. المفتاح gsk_test يعمل في بيئة الاختبار: تُحاكى الأدوات ولا يُخصم شيء، ولا يمكن به تعديل العقارات أو العملاء المحتملين أو غيرها من البيانات الحقيقية. يُختار نوع المفتاح عند إنشائه.

يُعرض السر مرة واحدة عند الإنشاء. يحفظ GREM قيمة التجزئة فقط، لذلك لا يمكن استعادة مفتاح مفقود: أنشئ مفتاحا جديدا وألغِ القديم.

إدارة المفاتيح

في لوحة التحكم، API → المفاتيح:

إنشاء مفتاح مع تسمية. تتيح الإعدادات المتقدمة اختيار النطاقات ومدة صلاحية بالأيام. دون اختيار يحصل المفتاح على كل النطاقات.
تدوير: إصدار سر جديد، ويبقى القديم صالحا 24 ساعة لتستبدله في تكاملك.
إلغاء: يتوقف المفتاح عن العمل فورا ونهائيا.

تظهر حالة المفتاح في القائمة: active يعمل؛ suspended أوقف مسؤول الوصول إلى API مؤقتا (قابل للعكس، والمفتاح لا يُحذف)؛ revoked ملغى. المفتاح ذو الصلاحية المحددة لا يُقبل بعد انتهائها (401).

مفاتيح الوكالة

يستطيع مالك الوكالة أو مديرها إصدار مفتاح باسم الوكالة: حوّل قائمة المفاتيح إلى نطاق الوكالة. هذا المفتاح:

يرى عقارات الوكالة وعملاءها المحتملين، لا الشخصية؛
يستطيع أخذ العملاء المحتملين من مجمع الوكالة المشترك وإعادتهم (العملاء المحتملون)؛
يستطيع نقل العقارات إلى الوكالة وتعيين وكيل (العقارات).

يمكن ربط المفتاح بوكيل واحد، فيعمل حينها بصفته هذا الوكيل وبصلاحياته.

النطاقات

يحمل كل مفتاح مجموعة من النطاقات. الاستدعاء دون النطاق المطلوب يعيد 403 مع title: forbidden_scope. النطاق الذي تحتاجه كل عملية مذكور في وصفها داخل /openapi.json (الحقل x-required-scope).

النطاق	يسمح بـ
`ping`	فحص المفتاح (`GET /ping` يعمل من دونه أيضا)
`tools:valuation`	التقييم السريع وتقرير التقييم الكامل
`tools:rent`	تقدير الإيجار
`tools:review`	مراجعة تقرير تقييم لجهة أخرى
`tools:contentgen`	حزمة محتوى العقار
`tools:text`	نصوص الإعلان
`tools:video`	فيديو من الصور، وقوائم الموسيقى والعبارات الختامية
`tools:avatar`	فيديوهات الأفاتار وقائمة الأفاتارات
`tools:photo`	تحسين الصور
`tools:floorplan`	تنظيف المخططات
`tools:sitegen`	صفحة هبوط للعقار
`tools:pdf`	عرض تقديمي PDF
`tools:flyer`	نشرة شخصية للوسيط
`tools:draft`	مسودة عقار من مستندات أو من موقع ويب
`tools:chat`	محادثة مساعد الذكاء الاصطناعي
`tools:artifacts`	تنزيل الملفات المُنشأة
`objects:write`	إنشاء عقاراتك وتعديلها وحذفها
`leads:read`	قراءة العملاء المحتملين وعملاء Swipe Match
`leads:write`	إنشاء العملاء المحتملين وتعديلهم، وأحداث Swipe Match
`media:write`	رفع الصور
`webhooks`	إدارة الاشتراكات في الأحداث

دون أي نطاق يمكنك استدعاء GET /ping وGET /me وGET /dictionaries وGET /objects وGET /voices وGET /tools/status وGET /works.

أي مفتاح هذا

curl https://developers.grem.capital/api/v1/me \
  -H "Authorization: Bearer gsk_live_xxx"

GET /me يعيد معرّف المفتاح وبادئته، ولمن ينتمي (subjectType: user أو agency، وsubjectId، وagencyMemberId لمفتاح الوكيل)، والنطاقات الممنوحة، والحدود المطبقة على هذا المفتاح تحديدا (rateLimit.rpm في الدقيقة وrateLimit.rpd في اليوم)، وتاريخ انتهاء الصلاحية. لا يُعاد السر أبدا. مجاني.

الأمان

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

احفظ المفاتيح في متغيرات بيئة على الخادم أو في مدير أسرار.
استخدم مفتاحا منفصلا لكل تكامل بالنطاقات التي يحتاجها فقط: إلغاء أحدها لا يؤثر في الباقي.
دوّر المفاتيح بانتظام.
تُقبل الطلبات عبر HTTPS فقط.