📦 Dokumentacja API
API REST dla biur nieruchomości i deweloperów — automatyczny import i synchronizacja ofert z zewnętrznych systemów CRM. Oferty pojawiają się na portalu natychmiast po przesłaniu.
Wprowadzenie
Bazowy URL wszystkich endpointów:
https://zaadresowani.pl/api/v1
API używa formatu JSON zarówno dla żądań (Content-Type: application/json), jak i odpowiedzi. Każde żądanie musi zawierać nagłówek autoryzacyjny z kluczem API.
Klucz API wygenerujesz w Panelu konta → Klucze API. Dostępny dla biur nieruchomości i deweloperów.
Autentykacja
Każde żądanie musi zawierać nagłówek Authorization z tokenem Bearer:
Authorization: Bearer TWÓJ_KLUCZ_API
Klucz API jest powiązany z kontem biura lub dewelopera. Wszystkie oferty importowane przez dany klucz trafiają automatycznie na to konto.
Klucz API zapewnia pełny dostęp do zasobów systemu, dlatego należy traktować go jak dane uwierzytelniające (np. hasło).
Nie powinien być przechowywany w publicznych repozytoriach ani udostępniany poza zaufanym środowiskiem.
W przypadku podejrzenia wycieku należy niezwłocznie wygenerować nowy klucz i dezaktywować poprzedni.
Nie powinien być przechowywany w publicznych repozytoriach ani udostępniany poza zaufanym środowiskiem.
W przypadku podejrzenia wycieku należy niezwłocznie wygenerować nowy klucz i dezaktywować poprzedni.
Limity zapytań
Każdy klucz API ma przypisany dzienny limit zapytań, ustalany przez administratora portalu. Domyślna wartość to 1 000 zapytań/dzień. Po przekroczeniu limitu API zwraca kod 429 Too Many Requests.
Aktualny stan wykorzystania limitu widoczny jest w Panelu konta → Klucze API.
Kody błędów
| Kod HTTP | Znaczenie |
|---|---|
200 | OK — zapytanie zakończone sukcesem |
201 | Created — oferta została utworzona |
400 | Bad Request — nieprawidłowy JSON lub brakujące pola |
401 | Unauthorized — brak lub nieważny klucz API |
404 | Not Found — oferta o podanym ref nie istnieje |
409 | Conflict — oferta o tym ref już istnieje (użyj PUT) |
422 | Unprocessable — błąd walidacji; szczegóły w polu error |
429 | Too Many Requests — przekroczono dzienny limit zapytań |
Każda odpowiedź zawiera pole success (bool) oraz opcjonalnie error z opisem błędu:
{ "success": false, "error": "Pole title jest wymagane", "code": 422 }
GET — Pobierz ofertę
GET /api/v1/listings/{ref}
Zwraca dane oferty identyfikowanej numerem ref z Twojego CRM.
Przykład
cURLcurl -X GET \ https://zaadresowani.pl/api/v1/listings/CRM-12345 \ -H "Authorization: Bearer TWÓJ_KLUCZ_API"
Odpowiedź 200
{ "success": true, "listing": { "id": 42, "external_ref": "CRM-12345", "title": "Mieszkanie 3 pokoje, Poznań", "price": 450000, "area": 68.5, "status": "active", "images": ["https://cdn.crm.pl/foto1.jpg"] }
}
POST — Utwórz ofertę
POST /api/v1/listings
Tworzy nową ofertę. Pole ref to unikalny identyfikator z Twojego CRM — służy do późniejszej aktualizacji i usuwania. Oferta trafia od razu ze statusem aktywnym.
Nagłówki
Content-Type: application/json
Authorization: Bearer TWÓJ_KLUCZ_API
Ciało żądania
{ "ref": "CRM-12345", // wymagane — unikalny ID z Twojego CRM"title": "Mieszkanie 3 pokoje", "type": "apartment", "deal": "sell", "city": "Poznań", "price": 450000, "area": 68.5, "market": "secondary", "description": "Przestronne mieszkanie w centrum...", "address": "ul. Przykładowa 1", "district": "Jeżyce", "rooms": 3, "floor": 2, "floors_total": 5, "build_year": 1985, "building_type": "blok", "build_material": "wielka płyta", "heating": ["miejskie"], "amenities": ["balkon", "piwnica", "winda"], "media": ["internet", "gaz"], "finish": "do zamieszkania", "ownership": "pełna własność", "lat": 52.4064, "lng": 16.9252, "images": [ "https://cdn.crm.pl/zdjecia/12345/foto1.jpg", "https://cdn.crm.pl/zdjecia/12345/foto2.jpg" ]
}
Odpowiedź 201
{ "success": true, "id": 42, "ref": "CRM-12345", "message": "Oferta została utworzona" }
PUT — Zaktualizuj ofertę
PUT /api/v1/listings/{ref}
Aktualizuje istniejącą ofertę. Wszystkie przesłane pola zostają nadpisane. Jeśli podasz tablicę images, stare zdjęcia zostaną zastąpione nowymi.
Przykład
cURLcurl -X PUT \ https://zaadresowani.pl/api/v1/listings/CRM-12345 \ -H "Authorization: Bearer TWÓJ_KLUCZ_API" \ -H "Content-Type: application/json" \ -d '{ "title": "Mieszkanie 3 pokoje — cena obniżona", "price": 420000, "type": "apartment", "deal": "sell", "city": "Poznań" }'
Odpowiedź 200
{ "success": true, "id": 42, "ref": "CRM-12345", "message": "Oferta została zaktualizowana" }
DELETE — Usuń ofertę
DELETE /api/v1/listings/{ref}
Trwale usuwa ofertę i jej zdjęcia. Operacja jest nieodwracalna.
Przykład
cURLcurl -X DELETE \ https://zaadresowani.pl/api/v1/listings/CRM-12345 \ -H "Authorization: Bearer TWÓJ_KLUCZ_API"
Odpowiedź 200
{ "success": true, "ref": "CRM-12345", "message": "Oferta została usunięta" }
Pola oferty
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
ref | string | tak | Unikalny ID oferty w Twoim CRM (maks. 100 znaków) |
title | string | tak | Tytuł ogłoszenia |
type | string | tak | Typ nieruchomości — patrz Typy |
deal | string | tak | sell lub rent |
city | string | tak | Miasto (np. Poznań) |
price | number | nie | Cena w PLN |
area | number | nie | Powierzchnia w m² |
market | string | nie | primary lub secondary |
description | string | nie | Opis oferty |
address | string | nie | Ulica i numer |
district | string | nie | Dzielnica |
rooms | integer | nie | Liczba pokoi |
floor | integer | nie | Piętro (0 = parter) |
floors_total | integer | nie | Liczba pięter w budynku |
build_year | integer | nie | Rok budowy |
building_type | string | nie | Typ budynku (np. blok, kamienica) |
build_material | string | nie | Materiał budowlany |
heating | string | array | nie | Ogrzewanie, np. ["miejskie"] |
amenities | array | nie | Udogodnienia, np. ["balkon","winda"] |
media | array | nie | Media, np. ["internet","gaz"] |
finish | string | nie | Stan wykończenia |
ownership | string | nie | Forma własności |
seller_type | string | nie | agency, developer lub private |
lat | number | nie | Szerokość geograficzna (np. 52.4064) |
lng | number | nie | Długość geograficzna (np. 16.9252) |
images | array | nie | Tablica publicznych URL-ów zdjęć (https). PUT zastępuje poprzednie. |
Typy i wartości
type — typ nieruchomości
| Wartość | Opis |
|---|---|
apartment | Mieszkanie |
house | Dom |
plot | Działka |
commercial | Lokal użytkowy |
garage | Garaż / miejsce parkingowe |
room | Pokój |
studio | Kawalerka |
other | Inne |
deal — transakcja
| Wartość | Opis |
|---|---|
sell | Sprzedaż |
rent | Wynajem |
market — rynek
| Wartość | Opis |
|---|---|
primary | Rynek pierwotny |
secondary | Rynek wtórny |
Przykłady kodu
PHP
PHP// Utwórz ofertę
$ch = curl_init('https://zaadresowani.pl/api/v1/listings');
curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'ref' =>'CRM-99', 'title' =>'Dom jednorodzinny, Warszawa', 'type' =>'house', 'deal' =>'sell', 'city' =>'Warszawa', 'price' =>1200000, 'area' =>180, ]), CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Authorization: Bearer TWÓJ_KLUCZ_API', ],
]);
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $resp['success'] ? 'ID: ' . $resp['id'] : $resp['error'];
Python
Pythonimport requests headers = { "Authorization": "Bearer TWÓJ_KLUCZ_API", "Content-Type": "application/json",
}
BASE = "https://zaadresowani.pl/api/v1"# Utwórz
r = requests.post(f"{BASE}/listings", json={ "ref": "PY-001", "title": "Apartament, Kraków", "type": "apartment", "deal": "rent", "city": "Kraków", "price": 3500,
}, headers=headers) # Aktualizuj
r = requests.put(f"{BASE}/listings/PY-001", json={ "title": "Apartament, Kraków", "type": "apartment", "deal": "rent", "city": "Kraków", "price": 3200,
}, headers=headers) # Usuń
r = requests.delete(f"{BASE}/listings/PY-001", headers=headers)
Lokale inwestycyjne — wprowadzenie
Oprócz standardowych ofert, API umożliwia import lokali w inwestycjach deweloperskich. Każdy lokal jest przypisany do konkretnej inwestycji i opcjonalnie do jej etapu.
Aby korzystać z endpointów lokali musisz mieć konto dewelopera i mieć dodaną inwestycję w panelu. Inwestycje zarządzasz w Panelu konta → Inwestycje.
Identyfikatory UUID inwestycji i etapów
Każda inwestycja i każdy etap posiadają unikalny identyfikator UUID, który jest wymagany przy wysyłaniu lokali przez API. Znajdziesz je w panelu edycji inwestycji — w sekcji „🔑 Identyfikatory API". Każdy UUID możesz skopiować jednym kliknięciem.
Pole
investment_uuid jest zawsze wymagane. Pole phase_uuid jest opcjonalne — jeśli inwestycja ma tylko jeden etap, możesz je pominąć. Bazowy URL endpointów lokali:
https://zaadresowani.pl/api/v1/units
GET — Pobierz lokal
GET /api/v1/units/{ref}?investment_uuid={uuid}
Zwraca dane lokalu identyfikowanego numerem ref z Twojego CRM w ramach wskazanej inwestycji.
Parametry URL
| Parametr | Wymagane | Opis |
|---|---|---|
ref | tak | Identyfikator lokalu w Twoim CRM (w URL) |
investment_uuid | tak | UUID inwestycji (query string) |
Przykład
cURLcurl -X GET \ "https://zaadresowani.pl/api/v1/units/M-001?investment_uuid=xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" \ -H "Authorization: Bearer TWÓJ_KLUCZ_API"
Odpowiedź 200
{ "success": true, "unit": { "id": 15, "uuid": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", "external_ref": "M-001", "unit_number": "M.1.01", "rooms": 3, "floor": 1, "area": 62.5, "price": 590000, "show_price": 1, "status": "available" }
}
POST — Utwórz lokal
POST /api/v1/units
Tworzy nowy lokal w inwestycji. Pole ref to unikalny identyfikator z Twojego CRM w obrębie danej inwestycji.
Nagłówki
Content-Type: application/json
Authorization: Bearer TWÓJ_KLUCZ_API
Ciało żądania
{ "ref": "M-001", // wymagane"investment_uuid": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", // wymagane"unit_number": "M.1.01", // wymagane — numer lokalu"phase_uuid": "yyyyyyyy-yyyy-4yyy-zyyy-yyyyyyyyyyyy", // opcjonalne"rooms": 3, "floor": 1, "area": 62.5, "price": 590000, "show_price": true, "status": "available", "description": "Przestronny lokal z widokiem na park"
}
Odpowiedź 201
{ "success": true, "id": 15, "ref": "M-001", "investment_uuid": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", "phase_uuid": "yyyyyyyy-yyyy-4yyy-zyyy-yyyyyyyyyyyy", "message": "Lokal został utworzony"
}
PUT — Zaktualizuj lokal
PUT /api/v1/units/{ref}
Aktualizuje istniejący lokal. Wszystkie przesłane pola zostają nadpisane. Najczęstszy przypadek użycia to zmiana statusu (np. z available na reserved lub sold).
Przykład
cURLcurl -X PUT \ https://zaadresowani.pl/api/v1/units/M-001 \ -H "Authorization: Bearer TWÓJ_KLUCZ_API" \ -H "Content-Type: application/json" \ -d '{ "investment_uuid": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", "unit_number": "M.1.01", "status": "reserved", "price": 575000 }'
Odpowiedź 200
{ "success": true, "id": 15, "ref": "M-001", "message": "Lokal został zaktualizowany" }
DELETE — Usuń lokal
DELETE /api/v1/units/{ref}?investment_uuid={uuid}
Trwale usuwa lokal z inwestycji. Operacja jest nieodwracalna.
Przykład
cURLcurl -X DELETE \ "https://zaadresowani.pl/api/v1/units/M-001?investment_uuid=xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" \ -H "Authorization: Bearer TWÓJ_KLUCZ_API"
Odpowiedź 200
{ "success": true, "ref": "M-001", "message": "Lokal został usunięty" }
Pola lokalu
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
ref | string | tak | Unikalny ID lokalu w Twoim CRM (maks. 100 znaków). Wymagany przy POST; dla PUT podawany w URL. |
investment_uuid | string | tak | UUID inwestycji — widoczny w Panelu → Inwestycje → Edytuj → sekcja „Identyfikatory API" |
unit_number | string | tak | Numer / oznaczenie lokalu widoczne na portalu (np. M.1.01, A3) |
phase_uuid | string | nie | UUID etapu inwestycji — widoczny obok nazwy etapu w sekcji „Identyfikatory API". Pomiń jeśli inwestycja ma jeden etap. |
rooms | integer | nie | Liczba pokoi |
floor | integer | nie | Piętro (0 = parter) |
area | number | nie | Powierzchnia lokalu w m² |
price | number | nie | Cena w PLN |
show_price | boolean | nie | true — cena widoczna publicznie; false — ukryta. Domyślnie false. |
status | string | nie | Status lokalu: available (dostępny), reserved (zarezerwowany), sold (sprzedany). Domyślnie available. |
description | string | nie | Opis lokalu |
Wartości pola status
| Wartość | Opis |
|---|---|
available | Lokal dostępny — widoczny jako wolny |
reserved | Lokal zarezerwowany |
sold | Lokal sprzedany |