البدء السريع
ثلاث خطوات إلى أول استدعاء لـ Acreonix API.
الخطوة 1 — احصل على مفتاح API
سجّل الدخول إلى المنصة، وانتقل إلى Settings → API & Integrations، ثم أنشئ مفتاحاً. كل مفتاح مقيّد بمؤسستك. احفظه في مكان آمن — فلن يُعرض مرة أخرى.
الخطوة 2 — أجرِ أول استدعاء
إدخال عميل محتمل من نموذج أو بوابة خارجية:
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, 120 درهم budget" }'
الخطوة 3 — استقبل البيانات
تُرجع الاستجابة الناجحة معرّف العميل المحتمل الجديد وحالته الحالية في مسارك.
{
"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).
POST /api/v1/leads
أدخل عميلاً محتملاً إلى مسار المبيعات في Acreonix. استخدم هذا لدفع الاستفسارات من البوابات العقارية (Property Finder وBayut وRightmove) أو من نماذج موقعك الإلكتروني أو أي مصدر خارجي آخر. يُنشأ العميل المحتمل بالحالة new ويصبح متاحاً فوراً لوكيلك الذكي للتأهيل.
نص الطلب
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
| name | string | مطلوب | الاسم الكامل للعميل المحتمل. |
| phone | string | مطلوب | رقم الهاتف بصيغة E.164 (مثال: +971501234567). |
string | اختياري | عنوان البريد الإلكتروني. | |
| source | string | اختياري | مصدر العميل المحتمل. القيم المقترحة: property-finder، bayut، rightmove، website، whatsapp، manual. |
| message | string | اختياري | نص الاستفسار أو الرسالة الأولى من العميل المحتمل. |
| property_ref | string | اختياري | المرجع الداخلي للعقار (BRN أو معرّف العقار المعروض وغيرهما) الذي استفسر عنه العميل المحتمل. |
| metadata | object | اختياري | أي أزواج مفتاح-قيمة إضافية لتخزينها في سجل العميل المحتمل (مثل معرّف إعلان البوابة العقارية، ومعاملات UTM). |
أمثلة
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, 120 درهم budget', property_ref: 'MRN-1204', }), }); const lead = await res.json(); console.log(lead.id); // lead_8f4a…
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, 120 درهم budget", }, ) print(res.json()["id"])
GET /api/v1/properties
يعرض قائمة مقسّمة إلى صفحات بالعقارات في محفظة مؤسستك. مفيد لمزامنة جردك المباشر مع خلاصة بوابة عقارية أو موقع إلكتروني أو أداة تقارير خارجية.
معاملات الاستعلام
| المعامل | النوع | الوصف |
|---|---|---|
| status | string | صفِّ النتائج حسب الحالة: available أو occupied أو maintenance أو off_market. |
| type | string | نوع العقار: residential، commercial. |
| limit | integer | عدد النتائج في كل صفحة، بحد أقصى 100. الافتراضي 50. |
| offset | integer | إزاحة تقسيم الصفحات. القيمة الافتراضية 0. |
مثال على الاستجابة
{
"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 -G https://platform.acreonix.co.uk/api/v1/properties \ -H 'Authorization: Bearer ak_live_••••••••' \ --data-urlencode 'status=available' \ --data-urlencode 'limit=25'
نظرة عامة
يمكن لـ Acreonix إرسال إشعارات الأحداث الفورية إلى أي نقطة HTTPS تتحكمون بها. اضبطوا عنوان webhook من Settings → API & Integrations → Webhooks.
كيف يعمل
عند وقوع حدث (عميل محتمل جديد، أو حجز معاينة، أو اقتراب انتهاء عقد إيجار)، ترسل Acreonix طلب POST إلى نقطة النهاية لديك مع محتوى JSON يصف الحدث. ينبغي أن ترد نقطة النهاية بـ 200 OK خلال 10 ثوانٍ. وتُعاد المحاولة عند الفشل حتى 5 مرات مع تأخير متزايد أسّياً.
التحقق من التوقيع
يتضمن كل طلب webhook ترويسة X-Acreonix-Signature — وهي ملخص HMAC-SHA256 بصيغة سداسية عشرية لمحتوى الطلب الخام، موقَّع بالمفتاح السري لـ webhook الخاص بك (ظاهر في الإعدادات).
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) ); }
مرجع الأحداث
تحتوي حمولة كل حدث على سلسلة event في المستوى الأعلى وكائن data يضم السجل المعني.
data.lead على سجل العميل المحتمل الكامل.data.lead.score وdata.lead.tags مملوءين الآن.data.viewing الموعد المحدد ومعرّف العقار والوكيل المعيَّن.data.lease.days_remaining مدى قرب الانتهاء.data.payment المستأجر والمبلغ وعدد أيام التأخر.data.ticket العقار والوصف ومستوى الإلحاح.التكامل مع الموقع الإلكتروني
إذا كان لديك موقع إلكتروني خاص بعقاراتك أو موقع مصغّر لأحد عملائك، فيمكنك إرسال نماذج الاستفسار مباشرة إلى Acreonix، دون وسيط بوابات ودون إدخال يدوي. يظهر العميل المحتمل في CRM فوراً ويبدأ وكيلك الذكي بالتأهيل تلقائياً.
نموذج تواصل جاهز للإدراج
انسخ المقتطف أدناه إلى أي صفحة HTML. استبدل ak_live_•••••••• بمفتاح API الخاص بك، وعيّن اختيارياً property_ref بالعقار الذي يظهر فيه النموذج.
<!-- 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>
WordPress & Webflow
لا توجد إضافة رسمية حتى الآن؛ استخدموا المقتطف أعلاه عبر عنصر HTML مخصص (Webflow) أو إضافة Code Snippets (WordPress). وتتيح نقطة النهاية الطلبات عبر CORS من أي نطاق ما دام مفتاحكم صالحاً.
وكيل (Proxy) من جهة الخادم (موصى به)
النمط الأكثر أماناً: يجمع موقعكم بيانات النموذج، ثم يحوّلها خادمكم إلى Acreonix. يبقى مفتاحكم سرياً، ويمكنكم إضافة تحقق من جهة الخادم قبل التحويل.
// 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، وهو ما يفيد في معرفة الإعلان أو الحملة التي أتت بالاستفسار.
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 كنقطة انطلاق:
// 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 وصيانته.