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"

Υλοποίηση με τη βοήθεια 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 κατά τη δημιουργία του, και μόνο όσο ο χώρος εργασίας έχει το πακέτο Agency.

Authorization: Bearer rtk_live_…

Ως ποιος ενεργεί μια κλήση

Μια κλήση ενεργεί ως το μέλος που δημιούργησε το κλειδί, με ό,τι μπορεί να δει εκείνο: ένας μεσίτης τους δικούς του πελάτες, ο κάτοχος ή ένας διαχειριστής όλους τους πελάτες του γραφείου. Όταν το μέλος αποχωρήσει από τον χώρο εργασίας, το κλειδί σταματά να λειτουργεί.

Όρια

Έως 120 κλήσεις το λεπτό ανά κλειδί. Πάνω από αυτό, η απάντηση είναι 429 με RATE_LIMITED και retryAfterSec: περιμένετε τόσα δευτερόλεπτα και καλέστε ξανά.

Σελίδες

Το GET /projects επιστρέφει έως 100 έργα τη φορά: το limit ορίζει πόσα, το offset από πού να ξεκινήσει και το total δείχνει πόσα είναι συνολικά.

Αναγνωριστικά

Το κλειδί ενός έργου έρχεται από το GET /projects, το id ενός πελάτη από το GET /clients και το id μιας συμφωνίας από την καρτέλα του πελάτη, 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 στο query	string ≤ 120	Words of a project's or a developer's name.
place στο query	string ≤ 80	A city or an emirate, by name or slug: Dubai, Batumi, Limassol.
area στο query	string ≤ 80	An area, by name or slug: Dubai Islands, JVC.
beds στο query	integer 0–9	Bedrooms: 0 is a studio, 4 is four and more.
maxPrice στο query	number	The most the client would pay, in `currency`.
currency στο query	string	The currency of `maxPrice`.
handoverBy στο query	integer 2025–2045	The latest handover year.
lang στο query	en \| he	The language of place and area names.
limit στο query	integer 1–100	How many projects in this page.
offset στο query	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 στο query	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 στο query	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 στο query	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 στο query	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"}'