المنتج
الحلول
الأسعار
المصادر
تسجيل الدخولاحجز عرضاً توضيحياً
المنطقة
اللغة
المطورون

ابنوا على Acreonix.

REST API وwebhooks لدفع العملاء المحتملين إلى المنصة وسحب الأملاك منها والتفاعل مع الأحداث لحظياً. وتتم المصادقة بمفتاح API من الإعدادات.

البدء

البدء السريع

ثلاث خطوات إلى أول استدعاء لـ Acreonix API.

الخطوة 1 — احصل على مفتاح API

سجّل الدخول إلى المنصة، وانتقل إلى Settings → API & Integrations، ثم أنشئ مفتاحاً. كل مفتاح مقيّد بمؤسستك. احفظه في مكان آمن — فلن يُعرض مرة أخرى.

الخطوة 2 — أجرِ أول استدعاء

إدخال عميل محتمل من نموذج أو بوابة خارجية:

curl
curl -X POST https://platform.acreonix.co.uk/api/v1/leads \
  -H 'Authorization: Bearer ak_live_••••••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":    "Sarah Ahmed",
    "phone":   "+971501234567",
    "email":   "sarah@example.com",
    "source":  "property-finder",
    "message": "Looking for 2-bed in Marina, ⁦$33K⁩ budget"
  }'

الخطوة 3 — استقبل البيانات

تُرجع الاستجابة الناجحة معرّف العميل المحتمل الجديد وحالته الحالية في مسارك.

الاستجابة 201
{
  "id":        "lead_8f4a…",
  "status":    "new",
  "created_at":"2026-08-24T09:12:00Z"
}

المصادقة

يجب أن يتضمن كل طلب مفتاح API صالحاً في ترويس Authorization بصيغة Bearer token.

الترويسة
Authorization: Bearer ak_live_••••••••
المفاتيح التي تبدأ بـ ak_test_ هي مفاتيح بيئة تجريبية، وتكون العملاء المحتملون والأحداث فيها معزولة عن بياناتك الحية. استخدم مفاتيح ak_live_ في بيئة الإنتاج.

تُدار المفاتيح ضمن الإعدادات ← API & التكاملات. يمكنك إنشاء عدة مفاتيح بتسميات مختلفة (مثلاً مفتاح لكل تكامل مع بوابة) وإلغاء كل منها على حدة.


الأخطاء & وحدود المعدلات

تُرجع جميع الأخطاء نص JSON يتضمن الحقلين error وmessage.

الحالةالمعنى
200 / 201نجاح
400طلب غير صالح — معاملات مفقودة أو غير صحيحة. راجعوا message للتفاصيل.
401مفتاح API غير صالح أو مفقود.
403لا تشمل باقتك الوصول إلى API. قم بالترقية إلى الباقة الاحترافية أو أعلى.
404المورد غير موجود.
422فشل التحقق: لم يجتز حقل واحد أو أكثر التحقق من المخطط.
429تم تجاوز حد المعدل. الافتراضي: 120 طلباً في الدقيقة لكل مفتاح.
500خطأ في الخادم. أعد المحاولة مع التراجع الأسّي (exponential back-off).

تُطبَّق حدود المعدل لكل مفتاح API. وتوضح ترويسات الاستجابة X-RateLimit-Remaining وX-RateLimit-Reset عدد الطلبات المتبقية في النافذة الحالية وموعد إعادة التعيين (طابع زمني Unix).


REST API

POST /api/v1/leads

POST   https://platform.acreonix.co.uk/api/v1/leads

أدخل عميلاً محتملاً إلى مسار المبيعات في Acreonix. استخدم هذا لدفع الاستفسارات من البوابات العقارية (Property Finder وBayut وRightmove) أو من نماذج موقعك الإلكتروني أو أي مصدر خارجي آخر. يُنشأ العميل المحتمل بالحالة new ويصبح متاحاً فوراً لوكيلك الذكي للتأهيل.

نص الطلب

الحقلالنوعمطلوبالوصف
namestringمطلوبالاسم الكامل للعميل المحتمل.
phonestringمطلوبرقم الهاتف بصيغة E.164 (مثال: +971501234567).
emailstringاختياريعنوان البريد الإلكتروني.
sourcestringاختياريمصدر العميل المحتمل. القيم المقترحة: property-finder، bayut، rightmove، website، whatsapp، manual.
messagestringاختيارينص الاستفسار أو الرسالة الأولى من العميل المحتمل.
property_refstringاختياريالمرجع الداخلي للعقار (BRN أو معرّف العقار المعروض وغيرهما) الذي استفسر عنه العميل المحتمل.
metadataobjectاختياريأي أزواج مفتاح-قيمة إضافية لتخزينها في سجل العميل المحتمل (مثل معرّف إعلان البوابة العقارية، ومعاملات UTM).

أمثلة

JavaScript
const res = await fetch('https://platform.acreonix.co.uk/api/v1/leads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACREONIX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name:       'Sarah Ahmed',
    phone:      '+971501234567',
    email:      'sarah@example.com',
    source:     'property-finder',
    message:    'Looking for 2-bed in Marina, ⁦$33K⁩ budget',
    property_ref: 'MRN-1204',
  }),
});
const lead = await res.json();
console.log(lead.id); // lead_8f4a…
Python
import requests, os

res = requests.post(
    "https://platform.acreonix.co.uk/api/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['ACREONIX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name":     "Sarah Ahmed",
        "phone":    "+971501234567",
        "source":   "property-finder",
        "message":  "Looking for 2-bed in Marina, ⁦$33K⁩ budget",
    },
)
print(res.json()["id"])

GET /api/v1/properties

GET   https://platform.acreonix.co.uk/api/v1/properties

يعرض قائمة مقسّمة إلى صفحات بالعقارات في محفظة مؤسستك. مفيد لمزامنة جردك المباشر مع خلاصة بوابة عقارية أو موقع إلكتروني أو أداة تقارير خارجية.

معاملات الاستعلام

المعاملالنوعالوصف
statusstringصفِّ النتائج حسب الحالة: available أو occupied أو maintenance أو off_market.
typestringنوع العقار: residential، commercial.
limitintegerعدد النتائج في كل صفحة، بحد أقصى 100. الافتراضي 50.
offsetintegerإزاحة تقسيم الصفحات. القيمة الافتراضية 0.

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

JSON
{
  "total": 229,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id":        "prop_a1b2…",
      "ref":       "MRN-1204",
      "name":      "Marina Gate II · 1204",
      "type":      "residential",
      "status":    "occupied",
      "bedrooms":  2,
      "area":      "JBR, Dubai",
      "rent_aed":  142000,
      "created_at":"2026-01-15T08:00:00Z"
    }
  ]
}
curl
curl -G https://platform.acreonix.co.uk/api/v1/properties \
  -H 'Authorization: Bearer ak_live_••••••••' \
  --data-urlencode 'status=available' \
  --data-urlencode 'limit=25'

Webhooks

نظرة عامة

يمكن لـ Acreonix إرسال إشعارات الأحداث الفورية إلى أي نقطة HTTPS تتحكمون بها. اضبطوا عنوان webhook من Settings → API & Integrations → Webhooks.

كيف يعمل

عند وقوع حدث (عميل محتمل جديد، أو حجز معاينة، أو اقتراب انتهاء عقد إيجار)، ترسل Acreonix طلب POST إلى نقطة النهاية لديك مع محتوى JSON يصف الحدث. ينبغي أن ترد نقطة النهاية بـ 200 OK خلال 10 ثوانٍ. وتُعاد المحاولة عند الفشل حتى 5 مرات مع تأخير متزايد أسّياً.

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

يتضمن كل طلب webhook ترويسة X-Acreonix-Signature — وهي ملخص HMAC-SHA256 بصيغة سداسية عشرية لمحتوى الطلب الخام، موقَّع بالمفتاح السري لـ webhook الخاص بك (ظاهر في الإعدادات).

التحقق عبر Node.js
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}
تحققوا دائماً من التوقيع قبل معالجة حمولة webhook. وارفضوا أي طلب يفشل في التحقق باستجابة 401.

مرجع الأحداث

تحتوي حمولة كل حدث على سلسلة event في المستوى الأعلى وكائن data يضم السجل المعني.

lead.created
أُضيف عميل محتمل جديد، عبر API أو رسالة WhatsApp أو يدوياً. يحتوي data.lead على سجل العميل المحتمل الكامل.
lead.qualified
أكمل الوكيل الذكي عملية التأهيل. أصبح الحقلان data.lead.score وdata.lead.tags مملوءين الآن.
viewing.booked
تم تأكيد معاينة. يتضمن data.viewing الموعد المحدد ومعرّف العقار والوكيل المعيَّن.
lease.expiring
اقترب عقد إيجار من تاريخ انتهائه (يُطلق التنبيه قبل 90 و60 و30 يوماً). يوضح data.lease.days_remaining مدى قرب الانتهاء.
payment.overdue
تجاوزت دفعة مجدولة تاريخ استحقاقها دون سداد. يتضمن data.payment المستأجر والمبلغ وعدد أيام التأخر.
maintenance.raised
فُتحت تذكرة صيانة جديدة. يتضمن data.ticket العقار والوصف ومستوى الإلحاح.

الموارد

التكامل مع الموقع الإلكتروني

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

نموذج تواصل جاهز للإدراج

انسخ المقتطف أدناه إلى أي صفحة HTML. استبدل ak_live_•••••••• بمفتاح API الخاص بك، وعيّن اختيارياً property_ref بالعقار الذي يظهر فيه النموذج.

HTML — نموذج الاستفسار
<!-- Acreonix lead capture form -->
<form id="acx-form">
  <input name="name"  placeholder="Full name"  required />
  <input name="phone" placeholder="Phone"      required />
  <input name="email" placeholder="Email"               />
  <textarea name="message" placeholder="Message"></textarea>
  <button type="submit">Send enquiry</button>
</form>

<script>
document.getElementById('acx-form').addEventListener('submit', async e => {
  e.preventDefault();
  const data = Object.fromEntries(new FormData(e.target));
  const res = await fetch('https://platform.acreonix.co.uk/api/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ak_live_••••••••',
      'Content-Type':  'application/json',
    },
    body: JSON.stringify({
      name:         data.name,
      phone:        data.phone,
      email:        data.email,
      source:       'website',
      message:      data.message,
      property_ref: 'OPTIONAL-LISTING-REF',
    }),
  });
  if (res.ok) alert('Thanks — we\'ll be in touch shortly.');
});
</script>
احتفظ بمفتاح API على جهة الخادم في بيئة الإنتاج. وبالنسبة للنماذج على جهة العميل، استخدم وسيط خادم خفيفاً (مسار API في Next.js أو Netlify Function أو ما شابه) كي لا يظهر المفتاح أبداً في مصدر الصفحة.

WordPress & Webflow

لا توجد إضافة رسمية حتى الآن؛ استخدموا المقتطف أعلاه عبر عنصر HTML مخصص (Webflow) أو إضافة Code Snippets (WordPress). وتتيح نقطة النهاية الطلبات عبر CORS من أي نطاق ما دام مفتاحكم صالحاً.

وكيل (Proxy) من جهة الخادم (موصى به)

النمط الأكثر أماناً: يجمع موقعكم بيانات النموذج، ثم يحوّلها خادمكم إلى Acreonix. يبقى مفتاحكم سرياً، ويمكنكم إضافة تحقق من جهة الخادم قبل التحويل.

Next.js API route
// pages/api/enquiry.js  (or app/api/enquiry/route.js)
export default async function handler(req, res) {
  if (req.method !== 'POST') return res.status(405).end();
  const fwd = await fetch('https://platform.acreonix.co.uk/api/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ACREONIX_API_KEY}`,
      'Content-Type':  'application/json',
    },
    body: JSON.stringify(req.body),
  });
  const data = await fwd.json();
  res.status(fwd.status).json(data);
}

تتبع معلمات UTM والإعلانات

مرّر أي معاملات UTM أو معاملات إعلانات البوابات في الحقل metadata. يتم حفظها مع العميل المحتمل وتظهر في CRM، وهو ما يفيد في معرفة الإعلان أو الحملة التي أتت بالاستفسار.

JavaScript — التقاط UTM
const params = new URLSearchParams(window.location.search);
const metadata = {
  utm_source:   params.get('utm_source'),
  utm_campaign: params.get('utm_campaign'),
  utm_medium:   params.get('utm_medium'),
  ref_url:      window.location.href,
};
// Include in your fetch body:
body: JSON.stringify({ name, phone, email, source: 'website', metadata })

الموارد

حزم SDK والأمثلة

حزم SDK الرسمية قيد التطوير. وفي الوقت الحالي يتبع API اصطلاحات REST ويعمل مع أي عميل HTTP. وفيما يلي جسر webhook مبسّط لـ Property Finder كنقطة انطلاق:

Node.js — جسر عملاء PF المحتملين
// Receives leads from Property Finder's webhook
// and forwards them into Acreonix.
app.post('/pf-webhook', async (req, res) => {
  const { lead } = req.body;
  await fetch('https://platform.acreonix.co.uk/api/v1/leads', {
    method:  'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ACREONIX_API_KEY}`,
      'Content-Type':  'application/json',
    },
    body: JSON.stringify({
      name:    lead.name,
      phone:   lead.mobile,
      email:   lead.email,
      source:  'property-finder',
      message: lead.message,
    }),
  });
  res.sendStatus(200);
});

الدعم

للحصول على صلاحية الوصول إلى API، أو لأي استفسارات حول التكامل، أو لطلب حد أعلى للطلبات، راسلنا على sales@acreonix.co.uk بعنوان "API Integration".

تتضمن خطط Enterprise مهندس تكامل مخصصاً يساعدك في بناء اتصالك مع Acreonix وصيانته.