Zasoby i pola — API Estalo

Sześć zasobów API Estalo i pola każdego z nich: klienci, oferty, transakcje, kalendarz, zapytania, zadania.

Zasoby

Ścieżka	Zakres	Id
`/api/v1/clients`, `/api/v1/clients/{id}`	`clients:read`	liczba całkowita
`/api/v1/properties`, `/api/v1/properties/{id}`	`properties:read`	UUID
`/api/v1/deals`, `/api/v1/deals/{id}`	`deals:read`	UUID
`/api/v1/events`, `/api/v1/events/{id}`	`events:read`	liczba całkowita
`/api/v1/leads`, `/api/v1/leads/{id}`	`leads:read`	UUID
`/api/v1/tasks`, `/api/v1/tasks/{id}`	`tasks:read`	UUID

Listy pól są w dokumencie OpenAPI i w tabelach poniżej. Są celowo wąskie: bez surowych danych portali i dostawców, wyników AI, notatek wewnętrznych, prowizji i rozliczeń, kosztów, numerów ksiąg wieczystych i informacji o kluczach do lokalu. assigned_user_id ma tę samą nazwę w każdym zasobie (w transakcjach oznacza osobę prowadzącą).

Dwa świadome wyjątki w leads (30.10.2026, na potrzeby integracji z portalami): message to treść zapytania z maila portalu i jest zwracana tylko wtedy, gdy source ma wartość email_import (w zapytaniach wpisanych przez agenta ta sama kolumna przechowuje jego własne notatki, które zostają wewnętrzne i wracają jako null); portal, offer_number, provider_listing_id i listing_title pochodzą z zapisu importu tego zapytania (lead_inquiry_sources) i mają wartość null dla zapytań, które nie przyszły z importu.

Widoczność wynika z ustawienia biura „Widoczność danych między agentami” (Ustawienia → Biuro) tak samo jak w aplikacji: klucz albo połączenie asystenta AI należące do AGENTA czyta wszystkich klientów i wszystkie oferty biura, gdy biuro ma ustawione „Pełne biuro (odczyt)” i aktywny plan; transakcje, wydarzenia, zapytania i zadania zostają ograniczone do własnych rekordów agenta, a kierownictwo zawsze czyta całe biuro.

Oferty z kosza Estalo nie są zwracane nigdy. Klienci ze statusem archived (i jego starszym odpowiednikiem closed) są pomijani w listach, chyba że przekażesz include_archived=true; klient pobrany po id jest zwracany niezależnie od statusu.

Rekord innego biura albo taki, którego klucz nie widzi, odpowiada 404, dokładnie tak jak nieistniejące id.

Klienci (clients)

Klienci biura (kupujący, sprzedający, wynajmujący).

Ścieżki: /api/v1/clients, /api/v1/clients/{id} (liczba całkowita)
Odczyt: clients:read
Zapis: clients:write
DELETE: archiwizuje klienta

Pole	Typ	Zapis	Opis
`id`	integer	tylko odczyt
`status`	string \| null	POST, PATCH	new, contacted, meeting, active, lost, archived (open i closed to starsze odpowiedniki).Wartości: new, contacted, meeting, active, lost, archived
`type`	string \| null	POST, PATCH	buyer, seller lub landlord.Wartości: buyer, seller, landlord
`first_name`	string \| null	POST, PATCH
`last_name`	string \| null	POST, PATCH
`name`	string \| null	POST, PATCH	Pełne imię i nazwisko; gdy nie wyślesz first_name i last_name, powstają z tego pola.
`email`	string \| null	POST, PATCH (null czyści)
`phone`	string \| null	POST, PATCH (null czyści)
`interest`	string \| null	tylko odczyt
`budget`	number \| null	POST, PATCH (null czyści)
`pref_budget_min`	number \| null	tylko odczyt
`pref_budget_max`	number \| null	tylko odczyt
`pref_area_min`	number \| null	tylko odczyt
`pref_rooms_min`	integer \| null	tylko odczyt
`pref_locations`	string \| null	tylko odczyt
`assigned_user_id`	uuid \| null	tylko odczyt
`last_contact_at`	date-time \| null	tylko odczyt
`created_at`	date-time \| null	tylko odczyt
`updated_at`	date-time \| null	tylko odczyt

Oferty (properties)

Oferty biura. Oferty z kosza nie są zwracane nigdy.

Ścieżki: /api/v1/properties, /api/v1/properties/{id} (UUID)
Odczyt: properties:read
Zapis: properties:write
DELETE: przenosi ofertę do kosza

Pole	Typ	Zapis	Opis
`id`	uuid	tylko odczyt
`title`	string	POST (wymagane), PATCH
`status`	string	POST, PATCH	Wartości: active, reserved, sold, rented, inactive, offer
`offer_number`	string \| null	tylko odczyt
`type`	string \| null	POST (wymagane), PATCH	Wartości: flat, house, plot, store, warehouse, garage, room
`category`	string \| null	tylko odczyt
`transaction_type`	string \| null	POST, PATCH	Wartości: sale, rent
`market`	string \| null	POST, PATCH	Wartości: primary, secondary
`price`	number \| null	POST (wymagane), PATCH
`area`	number \| null	POST, PATCH
`rooms`	integer \| null	POST, PATCH
`floor`	integer \| null	POST, PATCH (null czyści)
`total_floors`	integer \| null	POST, PATCH (null czyści)
`build_year`	integer \| null	POST, PATCH (null czyści)
`address_city`	string \| null	POST (wymagane), PATCH
`address_district`	string \| null	POST, PATCH
`address_street`	string \| null	POST, PATCH
`description`	string \| null	POST, PATCH	Publiczny opis oferty.
`assigned_user_id`	uuid \| null	PATCH (null czyści)	Zapis tylko dla kierownictwa biura z aktywnym planem biura; inaczej 403 forbidden.
`created_at`	date-time \| null	tylko odczyt
`updated_at`	date-time \| null	tylko odczyt

Transakcje (sprzedaż) (deals)

Sprzedaż: transakcje łączące klienta z ofertą. Pola prowizji i rozliczeń nie są udostępniane.

Ścieżki: /api/v1/deals, /api/v1/deals/{id} (UUID)
Odczyt: deals:read
Zapis: deals:write
DELETE: brak; zmiana przez PATCH

Pole	Typ	Zapis	Opis
`id`	uuid	tylko odczyt
`title`	string	POST (wymagane), PATCH
`stage`	string	POST (wymagane), PATCH	Wartości: new, presentation, negotiation, agreement, closed
`value`	number \| null	POST (wymagane), PATCH
`client_id`	integer \| null	POST, PATCH (null czyści)
`property_id`	uuid \| null	POST, PATCH (null czyści)
`assigned_user_id`	uuid \| null	POST, PATCH	Zapis tylko dla kierownictwa biura z aktywnym planem biura; inaczej 403 forbidden.
`close_date`	date-time \| null	POST, PATCH (null czyści)
`created_at`	date-time \| null	tylko odczyt
`updated_at`	date-time \| null	tylko odczyt

Kalendarz (events)

Wydarzenia w kalendarzu (spotkania, prezentacje, telefony, wizyty u notariusza).

Ścieżki: /api/v1/events, /api/v1/events/{id} (liczba całkowita)
Odczyt: events:read
Zapis: events:write
DELETE: usuwa rekord

Pole	Typ	Zapis	Opis
`id`	integer	tylko odczyt
`title`	string	POST (wymagane), PATCH
`type`	string	POST, PATCH	Wartości: meeting, test_drive, other, call, notary
`start_time`	date-time	POST (wymagane), PATCH
`end_time`	date-time	POST (wymagane), PATCH
`client_id`	integer \| null	POST, PATCH (null czyści)
`property_id`	uuid \| null	POST, PATCH (null czyści)
`assigned_user_id`	uuid \| null	tylko odczyt
`outcome`	string \| null	PATCH (null czyści)	Wynik odbytego spotkania; ustawia outcome_at.Wartości: interested, too_expensive, location, layout, to_negotiate, not_interested
`outcome_at`	date-time \| null	tylko odczyt
`created_at`	date-time \| null	tylko odczyt
`updated_at`	date-time \| null	tylko odczyt

Zapytania (leads)

Zapytania z portali, formularzy i importu maili.

Ścieżki: /api/v1/leads, /api/v1/leads/{id} (UUID)
Odczyt: leads:read
Zapis: leads:write
DELETE: brak; zmiana przez PATCH

Pole	Typ	Zapis	Opis
`id`	uuid	tylko odczyt
`status`	string \| null	POST, PATCH	Wartości: new, no_answer, callback, contacted, interested, meeting, negotiating, converted, not_interested, stale
`source`	string \| null	POST, PATCH	Dowolny tekst; email_import jest zarezerwowane dla importu maili Estalo.
`message`	string \| null	POST, PATCH (null czyści)	Treść zapytania z maila portalu (source = email_import); dla innych źródeł null. Zapisaną treść GET zwraca tylko dla email_import, dla innych źródeł pole działa tylko w zapisie.
`first_name`	string \| null	POST, PATCH
`last_name`	string \| null	POST, PATCH
`customer_name`	string \| null	POST, PATCH
`email`	string \| null	POST, PATCH (null czyści)
`phone`	string \| null	POST, PATCH (null czyści)
`marketing_consent`	boolean \| null	tylko odczyt
`property_id`	uuid \| null	tylko odczyt
`converted_client_id`	integer \| null	tylko odczyt
`assigned_user_id`	uuid \| null	PATCH (null czyści)	Zapis tylko dla kierownictwa biura z aktywnym planem biura; inaczej 403 forbidden.
`created_at`	date-time \| null	tylko odczyt
`updated_at`	date-time	tylko odczyt
`portal`	string \| null	tylko odczyt	otodom, nieruchomosci_online, gratka, morizon, adresowo lub unknown.
`offer_number`	string \| null	tylko odczyt	Numer oferty biura podany przez portal.
`provider_listing_id`	string \| null	tylko odczyt	Identyfikator ogłoszenia na portalu.
`listing_title`	string \| null	tylko odczyt

Zadania (tasks)

Zadania i przypomnienia.

Ścieżki: /api/v1/tasks, /api/v1/tasks/{id} (UUID)
Odczyt: tasks:read
Zapis: tasks:write
DELETE: usuwa rekord

Pole	Typ	Zapis	Opis
`id`	uuid	tylko odczyt
`title`	string	POST (wymagane), PATCH
`status`	string \| null	POST, PATCH	todo, in_progress lub done.Wartości: todo, in_progress, done
`priority`	string \| null	POST, PATCH	Wartości: low, medium, high
`task_type`	string \| null	POST, PATCH	Wartości: call, meeting, viewing, other
`due_date`	date-time	POST, PATCH
`completed_at`	date-time \| null	tylko odczyt
`related_client_id`	integer \| null	POST, PATCH (null czyści)
`related_property_id`	uuid \| null	POST, PATCH (null czyści)
`related_deal_id`	uuid \| null	POST, PATCH (null czyści)
`assigned_user_id`	uuid \| null	POST, PATCH	Zapis tylko dla kierownictwa biura z aktywnym planem biura; inaczej 403 forbidden.
`created_at`	date-time \| null	tylko odczyt
`updated_at`	date-time \| null	tylko odczyt