REST API

واجهة REST API

تقرأ أنظمتك كتالوج Realton وبيانات CRM الخاصة بك، وتكتب العملاء والملاحظات والمهام ومراحل الصفقات، باسم الشخص الذي أنشأ المفتاح.

باقة Agency

البدء السريع

في Realton، يفتح المالك أو أحد المشرفين الإعدادات › API وMCP، ويحدد REST API، ويختار إنشاء مفتاح. انسخه فورًا: يظهر مرة واحدة فقط.
احفظه على خادمك، في متغير بيئة:
```
export REALTON_API_KEY="rtk_live_…"
```

أرسل أول طلب:

curl "https://realton.ai/api/v1/projects?place=Dubai&beds=2&limit=5" \
  -H "Authorization: Bearer $REALTON_API_KEY"

البناء بمساعدة الذكاء الاصطناعي

معظم عمليات الربط اليوم يكتبها الذكاء الاصطناعي. أعطه هذين العنوانين والمهمة في كلمات قليلة، وسيقرأ الباقي بنفسه.

الملخص /docs/api.mdOpenAPI 3.1 /docs/openapi.json

نص جاهز للنسخ، بعد ملء ما بين الأقواس:

أريد ربط [موقعي / نظام CRM الخاص بي / نظامي] بواجهة REST API الخاصة بـ Realton.
اقرأ الملخص أولًا: https://realton.ai/docs/api.md
وثيقة OpenAPI الكاملة: https://realton.ai/docs/openapi.json
التقنيات التي أستخدمها: [مثلًا Next.js على Vercel].
ما أريده: [مثلًا عرض مشاريع Realton في دبي على موقعي، مع تحديثها مرة يوميًا].
مفتاح API موجود في متغير البيئة REALTON_API_KEY. لا تطلب مني المفتاح أبدًا، ولا تكتبه في الشيفرة أبدًا.

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

القواعد

المفتاح

كل طلب يرسل المفتاح في الترويسة Authorization. لا يتيح المفتاح الوصول إلى REST API إلا إذا حُدد REST API عند إنشائه، وطالما بقيت مساحة العمل على باقة Agency.

Authorization: Bearer rtk_live_…

باسم من يعمل الطلب

يعمل الطلب باسم العضو الذي أنشأ المفتاح، وبما يراه هذا العضو: الوسيط يرى عملاءه، والمالك أو المشرف يرى عملاء الوكالة. عندما يغادر هذا العضو مساحة العمل، يتوقف المفتاح.

الحدود

حتى 120 طلبًا في الدقيقة لكل مفتاح. إن تجاوزتها، يكون الرد 429 مع RATE_LIMITED وretryAfterSec: انتظر عدد الثواني هذا ثم أعد الطلب.

الصفحات

يعيد GET /projects حتى 100 مشروع في كل مرة: يحدد limit العدد، وoffset نقطة البداية، وtotal العدد الإجمالي.

المعرّفات

مفتاح المشروع يأتي من GET /projects، ومعرّف العميل من GET /clients، ومعرّف الصفقة من بطاقة العميل، GET /clients/{id}، في deals[].id.

لا شيء يصل إلى العميل

لا يرسل أي طلب شيئًا إلى العميل: يعيد POST /brochures رابطًا يرسله الوسيط. الأسعار هي أسعار المطوّر نفسه، وبعملته.

حالات الرفض

الرفض يأتي بصيغة JSON مع قيمة code ثابتة. اعتمد على الرمز، لا على نص الرسالة.

{ "code": "plan_required" }

الحالة	الرمز	المعنى
401	key_required	لا توجد ترويسة Authorization تحمل مفتاحًا.
401	key_invalid	المفتاح غير معروف أو أُلغي.
403	key_scope	المفتاح لا يتيح الوصول إلى REST API. أنشئ مفتاحًا مع تحديد REST API.
403	plan_required	لم تعد مساحة العمل على باقة Agency.
403	key_member_gone	الشخص الذي أنشأ المفتاح غادر مساحة العمل. أنشئ مفتاحًا جديدًا.
404	not_found	غير موجود، أو ليس من صلاحيات هذا العضو.
429	RATE_LIMITED	طلبات كثيرة جدًا في هذه الدقيقة. انتظر عدد الثواني المحدد في retryAfterSec.
400	place_unknown, whatsapp_invalid, …	حقل خارج النطاق أو قيمة غير صالحة. الرمز يحدد الحقل.

المرجع

كل طلب بحقوله ومثال عليه، كما في وثيقة OpenAPI.

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

https://realton.ai/api/v1

الكتالوج

GET/projectsSearch the catalog

Projects that fit, newest first, with their price from. Up to 100 a page.

المعاملات

الاسم	النوع	ما هو
q في الاستعلام	string ≤ 120	Words of a project's or a developer's name.
place في الاستعلام	string ≤ 80	A city or an emirate, by name or slug: Dubai, Batumi, Limassol.
area في الاستعلام	string ≤ 80	An area, by name or slug: Dubai Islands, JVC.
beds في الاستعلام	integer 0–9	Bedrooms: 0 is a studio, 4 is four and more.
maxPrice في الاستعلام	number	The most the client would pay, in `currency`.
currency في الاستعلام	string	The currency of `maxPrice`.
handoverBy في الاستعلام	integer 2025–2045	The latest handover year.
lang في الاستعلام	en \| he	The language of place and area names.
limit في الاستعلام	integer 1–100	How many projects in this page.
offset في الاستعلام	integer	How many to skip: the next page starts at offset + limit.

الرد 200

الاسم	النوع	ما هو
totalإلزامي	integer	How many projects fit, across all pages.
offsetإلزامي	integer	The offset of this page.
catalogDateإلزامي	string	The day the catalog was last built, YYYY-MM-DD.
projectsإلزامي	array

كل عنصر منها

الاسم	النوع	ما هو
key	string	The project key, for `GET /projects/{key}` and `POST /brochures`.
name	string	The project's name.
developer	string \| null	The developer's name.
market	ae \| cy \| ge \| om \| sa	ae, cy, ge, om or sa.
place	string \| null	The city or emirate.
area	string \| null	The area.
stage	OFF_PLAN \| UNDER_CONSTRUCTION \| READY	OFF_PLAN, UNDER_CONSTRUCTION or READY.
handover	string \| null	When it is handed over, as the developer says it: Q4 2028.
priceFrom	number \| null	The lowest price, in `currency`.
currency	string	The developer's currency: AED, EUR, USD, OMR, SAR.
bedrooms	array	The bedroom counts it has; 0 is a studio.
commissionPct	number \| null	The agent's commission, in percent.
photo	string \| null	A photo of it.

مثال

{
  "total": 312,
  "offset": 0,
  "catalogDate": "2026-10-24",
  "projects": [
    {
      "key": "studio:soma-residences",
      "name": "Soma Residences",
      "developer": "Origami Properties",
      "market": "ae",
      "place": "Dubai",
      "area": "Dubai Islands",
      "stage": "OFF_PLAN",
      "handover": "Q4 2028",
      "priceFrom": 1670000,
      "currency": "AED",
      "bedrooms": [
        1,
        2,
        3
      ],
      "commissionPct": 5,
      "photo": "https://…/soma-residences.avif"
    }
  ]
}

curl

curl -X GET "https://realton.ai/api/v1/projects" \
  -H "Authorization: Bearer $REALTON_API_KEY"

GET/projects/{key}One project in full

Unit types with sizes and prices, payment plans, amenities, the gallery and what is nearby.

المعاملات

الاسم	النوع	ما هو
keyإلزامي في المسار	string	The project key from `GET /projects`.
lang في الاستعلام	en \| he	The language of names, plans and amenities.

الرد 200

الاسم	النوع	ما هو
entry	object	Its catalog line: the same figures as `GET /projects`, with `title` for the name and slugs for place and area.
placeName	string \| null	The city or emirate.
areaName	string \| null	The area.
unitTypes	array	Each unit type: label, beds, available (from the inventory), sizeSqft, sizeSqm, priceFrom, currency, pricePerArea, areaUnit.
plans	array	Payment plans: each with its steps (label, timing, percent, phase) and its share before and after handover.
dldPct	number \| null	Dubai's registration fee on booking, in percent; null elsewhere.
amenities	array	What the project offers.
gallery	object	count, and images with their url.
nearby	array	Places near it: category, name, km.

curl

curl -X GET "https://realton.ai/api/v1/projects/{key}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

العملاء

GET/clientsYour clients

An agent's own clients; an owner's or an admin's, the agency's. Last active first.

المعاملات

الاسم	النوع	ما هو
q في الاستعلام	string ≤ 80	A name, a number or an email to look for.

الرد 200

الاسم	النوع	ما هو
clientsإلزامي	array

كل عنصر منها

الاسم	النوع	ما هو
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
source	string	Where they came from.
stage	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The stage of their most advanced open deal.
project	string \| null	The project of that deal.
lastActivityAt	string	The last thing that happened with them, ISO date-time.
ownerUserId	string	The member they belong to.
openTasks	integer	Their open tasks.

curl

curl -X GET "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clientsA new client

A name and at least one way to reach them is the usual; a name alone is accepted.

المحتوى

الاسم	النوع	ما هو
nameإلزامي	string ≤ 120	Their full name.
whatsapp	string ≤ 30	A number with its country code, +971 50 555 0147.
email	string ≤ 200	An email address.
language	string ≤ 5	The language they speak, a two-letter code: en, ar, he, ru…

مثال

{
  "name": "Elena Petrova",
  "whatsapp": "+971505550147",
  "language": "ru"
}

الرد 201

الاسم	النوع	ما هو
id	string	The client id.
name	string \| null	Their name.
language	string \| null	The language they speak.
whatsapp	string \| null	Their number, E.164.
email	string \| null	Their email.
ownerUserId	string	The member they belong to.
updatedAt	string	ISO date-time.

curl

curl -X POST "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Elena Petrova","whatsapp":"+971505550147","language":"ru"}'

GET/clients/{id}A client's card

Their details, what they are looking for, and their deals with each deal's id for PATCH /deals/{id}.

المعاملات

الاسم	النوع	ما هو
idإلزامي في المسار	string	The client id from `GET /clients`.
lang في الاستعلام	en \| he	The language of place names.

الرد 200

الاسم	النوع	ما هو
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
requirements	object	What they are looking for: places, bedrooms, budget, handover.
ownerName	string \| null	The member they belong to.
deals	array	Their deals: id, stage, projectKey, projectTitle, beds, unitLabel, price, currency, commissionPct, commission, lostReason.

curl

curl -X GET "https://realton.ai/api/v1/clients/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clients/{id}/notesA note on a client's card

Free text on the client's timeline, as the member.

المعاملات

الاسم	النوع	ما هو
idإلزامي في المسار	string	The client id.

المحتوى

الاسم	النوع	ما هو
textإلزامي	string ≤ 4000	The note.

مثال

{
  "text": "Wants a sea view, budget AED 2M, moving in 2028."
}

الرد 201

الاسم	النوع	ما هو
idإلزامي	string	The note id.

curl

curl -X POST "https://realton.ai/api/v1/clients/{id}/notes" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Wants a sea view, budget AED 2M, moving in 2028."}'

المهام

GET/tasksYour tasks

The member's own tasks, with how many there are in each scope.

المعاملات

الاسم	النوع	ما هو
scope في الاستعلام	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

الرد 200

الاسم	النوع	ما هو
tasksإلزامي	array
countsإلزامي	object	How many tasks in overdue, today, upcoming, someday and done.

كل عنصر منها

الاسم	النوع	ما هو
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X GET "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/tasksA new task

A task at a time, on a day, or with no date; for a client when clientId is given.

المحتوى

الاسم	النوع	ما هو
titleإلزامي	string ≤ 200	What to do.
note	string ≤ 2000	More words about it.
dueAt	string ≤ 40	When: an ISO date-time with its offset, 2026-10-25T11:00:00+04:00. With dueKind DAY, any time on that day.
dueKind	AT \| DAY \| NONE	AT for a time, DAY for a whole day, NONE for no date.
clientId	string	The client the task is for.

مثال

{
  "title": "Call Elena about Soma Residences",
  "dueAt": "2026-10-25T11:00:00+04:00",
  "dueKind": "AT",
  "clientId": "cm2x8k1qz0001abcdeffghijk"
}

الرد 201

الاسم	النوع	ما هو
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X POST "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Elena about Soma Residences","dueAt":"2026-10-25T11:00:00+04:00","dueKind":"AT","clientId":"cm2x8k1qz0001abcdeffghijk"}'

الصفقات

PATCH/deals/{id}Move a deal's stage

A deal's id is on its client's card (GET /clients/{id}, deals[].id).

المعاملات

الاسم	النوع	ما هو
idإلزامي في المسار	string	The deal id.

المحتوى

الاسم	النوع	ما هو
stageإلزامي	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

مثال

{
  "stage": "VIEWING"
}

الرد 200

الاسم	النوع	ما هو
okإلزامي	boolean

curl

curl -X PATCH "https://realton.ai/api/v1/deals/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"VIEWING"}'

الكتيّبات

POST/brochuresA brochure link

A brochure of a project in your brand, with open tracking, for the agent to send. Realton does not send it.

المحتوى

الاسم	النوع	ما هو
projectإلزامي	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langإلزامي	en \| he	The language of the brochure.

مثال

{
  "project": "studio:soma-residences",
  "clientId": "cm2x8k1qz0001abcdeffghijk",
  "lang": "en"
}

الرد 201

الاسم	النوع	ما هو
idإلزامي	string	The link id.
urlإلزامي	string	The address to send: it opens the brochure in the agency's brand.
projectإلزامي	string	The project name.
langإلزامي	string	The language of the brochure.
clientإلزامي	string \| null	The client's name, when it is for one.

مثال

{
  "id": "cm2x9p0aa0002abcdeffghijk",
  "url": "https://realton.ai/b/Hk3…",
  "project": "Soma Residences",
  "lang": "en",
  "client": "Elena Petrova"
}

curl

curl -X POST "https://realton.ai/api/v1/brochures" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"studio:soma-residences","clientId":"cm2x8k1qz0001abcdeffghijk","lang":"en"}'