REST API

ה-REST API

המערכות שלכם קוראות את הקטלוג של Realton ואת ה-CRM שלכם, וכותבות לקוחות, הערות, משימות ושלבי עסקה, בשם מי שיצר את המפתח.

מסלול Business

התחלה מהירה

ב-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"

בונים את זה עם AI

היום רוב החיבורים נכתבים על ידי AI. נותנים לו את שתי הכתובות האלה ואת המשימה בכמה מילים, ואת השאר הוא קורא לבד.

התקציר /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 בשרת בעצמכם, וספרו ל-AI רק את השם שלו.

הכללים

המפתח

כל קריאה שולחת את המפתח בכותרת Authorization. מפתח נותן גישה ל-REST API רק אם סימנו REST API כשיצרו אותו, ורק כל עוד סביבת העבודה במסלול Business.

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	סביבת העבודה כבר לא במסלול Business.
403	key_member_gone	מי שיצר את המפתח עזב את סביבת העבודה. צרו מפתח חדש.
404	not_found	לא נמצא, או לא גלוי לחבר הצוות הזה.
429	RATE_LIMITED	יותר מדי קריאות בדקה הזו. חכו retryAfterSec שניות.
400	place_unknown, whatsapp_invalid, …	שדה מחוץ לטווח או ערך לא תקין. הקוד אומר איזה.

רפרנס

כל קריאה עם השדות שלה ודוגמה, כמו במסמך ה-OpenAPI.

כתובת הבסיס

https://realton.ai/api/v1

קטלוג

GET/projectsחיפוש בקטלוג

פרויקטים מתאימים, החדשים קודם, עם המחיר ההתחלתי. עד 100 בעמוד.

פרמטרים

שם	סוג	מה זה
q בכתובת	string ≤ 120	מילים משם הפרויקט או היזם.
place בכתובת	string ≤ 80	עיר או אמירות, בשם או ב-slug: Dubai,‏ Batumi,‏ Limassol.
area בכתובת	string ≤ 80	אזור, בשם או ב-slug: Dubai Islands,‏ JVC.
beds בכתובת	integer 0–9	חדרי שינה: 0 הוא סטודיו, 4 הוא ארבעה ומעלה.
maxPrice בכתובת	number	הסכום הגבוה ביותר שהלקוח ישלם, ב-`currency`.
currency בכתובת	string	המטבע של `maxPrice`.
handoverBy בכתובת	integer 2025–2045	שנת המסירה המאוחרת ביותר.
lang בכתובת	en \| he	השפה של שמות המקומות והאזורים.
limit בכתובת	integer 1–100	כמה פרויקטים בעמוד הזה.
offset בכתובת	integer	כמה לדלג: העמוד הבא מתחיל ב-offset + limit.

תשובה 200

שם	סוג	מה זה
totalחובה	integer	כמה פרויקטים מתאימים בכל העמודים.
offsetחובה	integer	ה-offset של העמוד הזה.
catalogDateחובה	string	היום שבו הקטלוג נבנה לאחרונה, YYYY-MM-DD.
projectsחובה	array

כל אחד מהם

שם	סוג	מה זה
key	string	מפתח הפרויקט, ל-`GET /projects/{key}` ול-`POST /brochures`.
name	string	שם הפרויקט.
developer	string \| null	שם היזם.
market	ae \| cy \| ge \| om \| sa	ae,‏ cy,‏ ge,‏ om או sa.
place	string \| null	העיר או האמירות.
area	string \| null	האזור.
stage	OFF_PLAN \| UNDER_CONSTRUCTION \| READY	OFF_PLAN,‏ UNDER_CONSTRUCTION או READY.
handover	string \| null	מתי הוא נמסר, כמו שהיזם אומר: Q4 2028.
priceFrom	number \| null	המחיר הנמוך ביותר, ב-`currency`.
currency	string	המטבע של היזם: AED,‏ EUR,‏ USD,‏ OMR,‏ SAR.
bedrooms	array	מספרי חדרי השינה שיש בו; 0 הוא סטודיו.
commissionPct	number \| null	העמלה של הסוכן, באחוזים.
photo	string \| null	תמונה שלו.

דוגמה

{
  "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}פרויקט אחד במלואו

סוגי יחידות עם שטחים ומחירים, תוכניות תשלום, מתקנים, הגלריה ומה יש בסביבה.

פרמטרים

שם	סוג	מה זה
keyחובה בנתיב	string	מפתח הפרויקט מ-`GET /projects`.
lang בכתובת	en \| he	השפה של השמות, תוכניות התשלום והמתקנים.

תשובה 200

שם	סוג	מה זה
entry	object	השורה שלו בקטלוג: אותם נתונים כמו ב-`GET /projects`, עם `title` לשם ו-slugs למקום ולאזור.
placeName	string \| null	העיר או האמירות.
areaName	string \| null	האזור.
unitTypes	array	כל סוג יחידה: label,‏ beds,‏ available (מהמלאי), sizeSqft,‏ sizeSqm,‏ priceFrom,‏ currency,‏ pricePerArea,‏ areaUnit.
plans	array	תוכניות תשלום: לכל אחת השלבים (label,‏ timing,‏ percent,‏ phase) והחלק לפני המסירה ואחריה.
dldPct	number \| null	אגרת הרישום של דובאי בהזמנה, באחוזים; null במקומות אחרים.
amenities	array	מה הפרויקט מציע.
gallery	object	count, ו-images עם ה-url שלהן.
nearby	array	מקומות קרובים: category,‏ name,‏ km.

curl

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

לקוחות

GET/clientsהלקוחות שלכם

סוכן מקבל את הלקוחות שלו, ובעלים או מנהל את כל לקוחות הסוכנות. הפעילים לאחרונה קודם.

פרמטרים

שם	סוג	מה זה
q בכתובת	string ≤ 80	שם, מספר או מייל לחיפוש.

תשובה 200

שם	סוג	מה זה
clientsחובה	array

כל אחד מהם

שם	סוג	מה זה
id	string	מזהה הלקוח.
name	string \| null	השם.
whatsapp	string \| null	המספר.
email	string \| null	המייל.
language	string \| null	השפה שהם מדברים.
source	string	מאיפה הם הגיעו.
stage	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	השלב של העסקה הפתוחה המתקדמת ביותר שלהם.
project	string \| null	הפרויקט של אותה עסקה.
lastActivityAt	string	הדבר האחרון שקרה איתם, תאריך ושעה ב-ISO.
ownerUserId	string	חבר הצוות שהם שייכים לו.
openTasks	integer	המשימות הפתוחות שלהם.

curl

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

POST/clientsלקוח חדש

בדרך כלל שם ולפחות דרך אחת ליצור קשר; גם שם לבד מתקבל.

גוף הבקשה

שם	סוג	מה זה
nameחובה	string ≤ 120	השם המלא.
whatsapp	string ≤ 30	מספר עם קידומת מדינה, ‎+971 50 555 0147.
email	string ≤ 200	כתובת מייל.
language	string ≤ 5	השפה שהם מדברים, בקוד של שתי אותיות: en,‏ ar,‏ he,‏ ru…

דוגמה

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

תשובה 201

שם	סוג	מה זה
id	string	מזהה הלקוח.
name	string \| null	השם.
language	string \| null	השפה שהם מדברים.
whatsapp	string \| null	המספר, בפורמט E.164.
email	string \| null	המייל.
ownerUserId	string	חבר הצוות שהם שייכים לו.
updatedAt	string	תאריך ושעה ב-ISO.

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}כרטיס הלקוח

הפרטים, מה הם מחפשים, והעסקאות שלהם עם המזהה של כל עסקה ל-PATCH /deals/{id}.

פרמטרים

שם	סוג	מה זה
idחובה בנתיב	string	מזהה הלקוח מ-`GET /clients`.
lang בכתובת	en \| he	השפה של שמות המקומות.

תשובה 200

שם	סוג	מה זה
id	string	מזהה הלקוח.
name	string \| null	השם.
whatsapp	string \| null	המספר.
email	string \| null	המייל.
language	string \| null	השפה שהם מדברים.
requirements	object	מה הם מחפשים: מקומות, חדרי שינה, תקציב, מסירה.
ownerName	string \| null	חבר הצוות שהם שייכים לו.
deals	array	העסקאות שלהם: 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}/notesהערה בכרטיס לקוח

טקסט חופשי בציר הזמן של הלקוח, בשם חבר הצוות.

פרמטרים

שם	סוג	מה זה
idחובה בנתיב	string	מזהה הלקוח.

גוף הבקשה

שם	סוג	מה זה
textחובה	string ≤ 4000	ההערה.

דוגמה

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

תשובה 201

שם	סוג	מה זה
idחובה	string	מזהה ההערה.

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/tasksהמשימות שלכם

המשימות של חבר הצוות, עם המספר בכל קבוצה.

פרמטרים

שם	סוג	מה זה
scope בכתובת	open \| overdue \| today \| upcoming \| someday \| done	open הן כל המשימות שלא הושלמו.

תשובה 200

שם	סוג	מה זה
tasksחובה	array
countsחובה	object	כמה משימות יש ב-overdue,‏ today,‏ upcoming,‏ someday ו-done.

כל אחד מהם

שם	סוג	מה זה
id	string	מזהה המשימה.
title	string	מה צריך לעשות.
note	string \| null	עוד פרטים.
dueAt	string \| null	מתי, תאריך ושעה ב-ISO.
dueKind	AT \| DAY \| NONE	AT,‏ DAY או NONE.
doneAt	string \| null	מתי היא הושלמה.
scope	overdue \| today \| upcoming \| someday \| done	איפה היא עומדת עכשיו, באזור הזמן של חבר הצוות.
contact	object \| null	הלקוח שהמשימה שלו: id ו-name.
dealId	string \| null	העסקה שהיא שייכת לה.

curl

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

POST/tasksמשימה חדשה

משימה בשעה מסוימת, ביום מסוים או בלי תאריך; של לקוח כשנשלח clientId.

גוף הבקשה

שם	סוג	מה זה
titleחובה	string ≤ 200	מה צריך לעשות.
note	string ≤ 2000	עוד פרטים.
dueAt	string ≤ 40	מתי: תאריך ושעה ב-ISO עם ההפרש מ-UTC, ‎2026-10-25T11:00:00+04:00. עם dueKind DAY, כל שעה באותו יום.
dueKind	AT \| DAY \| NONE	AT לשעה, DAY ליום שלם, NONE בלי תאריך.
clientId	string	הלקוח שהמשימה שלו.

דוגמה

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

תשובה 201

שם	סוג	מה זה
id	string	מזהה המשימה.
title	string	מה צריך לעשות.
note	string \| null	עוד פרטים.
dueAt	string \| null	מתי, תאריך ושעה ב-ISO.
dueKind	AT \| DAY \| NONE	AT,‏ DAY או NONE.
doneAt	string \| null	מתי היא הושלמה.
scope	overdue \| today \| upcoming \| someday \| done	איפה היא עומדת עכשיו, באזור הזמן של חבר הצוות.
contact	object \| null	הלקוח שהמשימה שלו: id ו-name.
dealId	string \| null	העסקה שהיא שייכת לה.

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}העברת עסקה לשלב

המזהה של עסקה נמצא בכרטיס הלקוח (GET /clients/{id},‏ deals[].id).

פרמטרים

שם	סוג	מה זה
idחובה בנתיב	string	מזהה העסקה.

גוף הבקשה

שם	סוג	מה זה
stageחובה	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	השלב החדש.
lostReason	string ≤ 200	למה העסקה אבדה; נקרא רק עם 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/brochuresקישור לברושור

ברושור של פרויקט במותג שלכם, עם מעקב פתיחות, לשליחה על ידי הסוכן. Realton לא שולח אותו.

גוף הבקשה

שם	סוג	מה זה
projectחובה	string	מפתח הפרויקט.
clientId	string	הלקוח שהקישור בשבילו: הפתיחות יופיעו בכרטיס שלו.
langחובה	en \| he	שפת הברושור.

דוגמה

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

תשובה 201

שם	סוג	מה זה
idחובה	string	מזהה הקישור.
urlחובה	string	הכתובת לשליחה: היא פותחת את הברושור במותג של הסוכנות.
projectחובה	string	שם הפרויקט.
langחובה	string	שפת הברושור.
clientחובה	string \| null	שם הלקוח, אם הקישור בשבילו.

דוגמה

{
  "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"}'