# ForDevo API Documentation

### Přehled

ForDevo API umožňuje přístup k inzertnímu systému pro developery a realitní kanceláře. API poskytuje funkce pro získávání, filtrování a správu inzerátů nemovitostí.

### Base URL

```
https://your-domain.com/api
```

### Autentifikace

*Zatím bez autentifikace - doporučuje se implementovat API klíče pro produkci*

### Rate Limiting

*Zatím bez omezení - doporučuje se implementovat pro produkci*

***

### Endpointy

#### 1. Získání všech inzerátů

**Endpoint:** `GET /listings/all`

**Popis:** Vrací seznam všech inzerátů seřazených podle data vytvoření (nejnovější první).

**Query parametry:**

* `limit` (number, optional) - Omezí počet vrácených výsledků (výchozí: 100)

**Příklad requestu:**

```http
httpGET /api/listings/all?limit=50
```

**Response:**

```json
json[  {    "_id": "507f1f77bcf86cd799439011",    "name": "Moderní byt 2+kk",    "description": "Krásný světlý byt v centru města",    "project": "507f1f77bcf86cd799439012",    "building": "507f1f77bcf86cd799439013",    "buildingCode": "A1",    "buildingName": "Rezidence Central",    "buildingDetails": {      "_id": "507f1f77bcf86cd799439013",      "code": "A1",      "name": "Rezidence Central"    },    "categories": ["507f1f77bcf86cd799439014", "507f1f77bcf86cd799439015"],    "categoryDetails": [      {        "_id": "507f1f77bcf86cd799439014",        "name": "Byty",        "slug": "byty"      }    ],    "mainImageUrl": "https://example.com/image.jpg",    "galleryUrls": ["https://example.com/gallery1.jpg"],    "price": 4500000,    "status": "available",    "visibility": "public",    "usable_area": 65.5,    "floor_area": 70.2,    "addons": ["balkon", "sklep"],    "rooms": "2+kk",    "visualizations": [      {        "name": "3D Model",        "url": "https://example.com/3d-model"      }    ],    "floor": 3,    "location": {      "address": "Náměstí Míru 123",      "city": "Praha",      "coordinates": [14.4378, 50.0755]    },    "createdAt": "2024-01-15T10:30:00Z",    "updatedAt": "2024-01-16T14:20:00Z"  }]
```

***

#### 2. Detail inzerátu

**Endpoint:** `GET /listings/detail`

**Popis:** Vrací detailní informace o konkrétním inzerátu včetně všech souvisejících dat.

**Query parametry:**

* `id` (string, required) - MongoDB ObjectId inzerátu

**Příklad requestu:**

```http
httpGET /api/listings/detail?id=507f1f77bcf86cd799439011
```

**Response:**

```json
json{  "_id": "507f1f77bcf86cd799439011",  "name": "Moderní byt 2+kk",  "description": "Krásný světlý byt v centru města s výhledem na park",  "project": "507f1f77bcf86cd799439012",  "building": "507f1f77bcf86cd799439013",  "buildingCode": "A1",  "buildingName": "Rezidence Central",  "buildingDetails": {    "_id": "507f1f77bcf86cd799439013",    "code": "A1",    "name": "Rezidence Central",    "address": "Náměstí Míru 123, Praha"  },  "categories": ["507f1f77bcf86cd799439014", "507f1f77bcf86cd799439015"],  "categoryDetails": [    {      "_id": "507f1f77bcf86cd799439014",      "name": "Byty",      "slug": "byty"    },    {      "_id": "507f1f77bcf86cd799439015",      "name": "2+kk",      "slug": "2kk"    }  ],  "mainImageUrl": "https://example.com/main-image.jpg",  "galleryUrls": [    "https://example.com/gallery1.jpg",    "https://example.com/gallery2.jpg"  ],  "price": 4500000,  "status": "available",  "visibility": "public",  "usable_area": 65.5,  "floor_area": 70.2,  "addons": ["balkon", "sklep", "garážové stání"],  "rooms": "2+kk",  "visualizations": [    {      "name": "3D Model",      "url": "https://example.com/3d-model",      "type": "3d"    },    {      "name": "Vizualizace obývacího pokoje",      "url": "https://example.com/visualization1.jpg",      "type": "image"    }  ],  "floor": 3,  "features": [    "klimatizace",    "podlahové topení",    "bezpečnostní dveře"  ],  "location": {    "address": "Náměstí Míru 123",    "city": "Praha",    "coordinates": [14.4378, 50.0755],    "district": "Vinohrady"  },  "energyLabel": "B",  "itemId": "UNIT-A1-03-12",  "createdAt": "2024-01-15T10:30:00Z",  "updatedAt": "2024-01-16T14:20:00Z"}
```

***

#### 3. Filtrované inzeráty podle kategorií (legacy)

**Endpoint:** `GET /listings`

**Popis:** Vrací inzeráty filtrované podle konkrétních kategorií (implementováno pro byty/1kk).

**Query parametry:** *Zatím hard-coded pro "byty" a "1kk" - doporučuje se rozšířit o flexibilní parametry*

**Příklad requestu:**

```http
httpGET /api/listings
```

**Response:**

```json
json[  {    "_id": "507f1f77bcf86cd799439011",    "name": "Garsonka v centru",    "description": "Kompaktní bydlení pro mladé",    "categories": ["507f1f77bcf86cd799439014", "507f1f77bcf86cd799439016"],    "price": 2800000,    "status": "available",    "rooms": "1+kk",    "usable_area": 28.5,    "createdAt": "2024-01-15T10:30:00Z"  }]
```

***

#### 4. Inzeráty podle kategorie (nový)

**Endpoint:** `GET /listings/category`

**Popis:** Vrací inzeráty filtrované podle slug kategorie s kompletními detaily.

**Query parametry:**

* `slug` (string, required) - Slug kategorie (např. "byty", "domy", "kancelare")

**Příklad requestu:**

```http
httpGET /api/listings/category?slug=byty
```

**Response:**

```json
json[  {    "_id": "507f1f77bcf86cd799439011",    "name": "Moderní byt 3+kk",    "description": "Prostorný byt s terasou",    "project": "507f1f77bcf86cd799439012",    "building": "507f1f77bcf86cd799439013",    "buildingCode": "B2",    "buildingName": "Rezidence Garden",    "buildingDetails": {      "_id": "507f1f77bcf86cd799439013",      "code": "B2",      "name": "Rezidence Garden"    },    "categories": ["507f1f77bcf86cd799439014"],    "categoryDetails": [      {        "_id": "507f1f77bcf86cd799439014",        "name": "Byty",        "slug": "byty"      }    ],    "mainImageUrl": "https://example.com/main-image.jpg",    "galleryUrls": ["https://example.com/gallery1.jpg"],    "price": 6200000,    "status": "available",    "visibility": "public",    "size": 85.5,    "rooms": "3+kk",    "floor": 5,    "createdAt": "2024-01-15T10:30:00Z",    "updatedAt": "2024-01-16T14:20:00Z"  }]
```

***

#### 5. Health check

**Endpoint:** `GET /health`

**Popis:** Kontrola stavu API a databázového připojení.

**Příklad requestu:**

```http
httpGET /api/health
```

**Response:**

```json
json{  "ok": true}
```

**Response při chybě:**

```json
json{  "ok": false,  "error": "Database connection failed"}
```

***

### Datové modely

#### Listing (Inzerát)

```typescript
typescriptinterface Listing {  _id: string;                    // MongoDB ObjectId  name: string;                   // Název inzerátu  description: string;            // Popis nemovitosti  project: string;                // ID projektu  building: string;               // ID budovy  buildingCode?: string;          // Kód budovy (z join)  buildingName?: string;          // Název budovy (z join)  buildingDetails?: Building;     // Detaily budovy  categories: string[];           // Pole ID kategorií  categoryDetails?: Category[];   // Detaily kategorií  mainImageUrl?: string;          // URL hlavního obrázku  galleryUrls?: string[];         // Pole URL obrázků  price: number;                  // Cena v Kč  status: 'available' | 'sold' | 'reserved';  visibility: 'public' | 'private';    // Plocha - různé implementace podle projektu  usable_area?: number;           // Užitná plocha (m²) - projekt 1  floor_area?: number;            // Podlahová plocha (m²) - projekt 1  size?: number;                  // Celková plocha (m²) - projekt 2    addons?: string[];              // Doplňky (balkon, sklep, atd.)  rooms: string;                  // Dispozice (2+kk, 3+1, atd.)  visualizations?: Visualization[];  floor?: number;                 // Patro  features?: string[];            // Vybavení  location?: Location;  energyLabel?: string;           // Energetický štítek  itemId?: string;                // Interní ID jednotky  createdAt: string;              // ISO datum vytvoření  updatedAt: string;              // ISO datum aktualizace}
```

#### Building (Budova)

```typescript
typescriptinterface Building {  _id: string;  code: string;                   // Kód budovy  name: string;                   // Název budovy  address?: string;               // Adresa}
```

#### Category (Kategorie)

```typescript
typescriptinterface Category {  _id: string;  name: string;                   // Název kategorie  slug: string;                   // URL slug}
```

#### Visualization (Vizualizace)

```typescript
typescriptinterface Visualization {  name: string;                   // Název vizualizace  url: string;                    // URL souboru  type?: string;                  // Typ (3d, image, video)}
```

#### Location (Lokace)

```typescript
typescriptinterface Location {  address: string;                // Adresa  city: string;                   // Město  coordinates?: [number, number]; // [longitude, latitude]  district?: string;              // Městská část}
```

***

### Chybové kódy

```
```

### Příklady chybových odpovědí

#### 400 - Chybí parametr

```json
json{  "error": "Missing \"id\" query parameter"}
```

#### 400 - Chybí slug parametr

```json
json{  "error": "Missing \"slug\" query parameter"}
```

#### 400 - Nevalidní formát ID

```json
json{  "error": "Invalid ID format"}
```

#### 404 - Inzerát nenalezen

```json
json{  "error": "Listing not found"}
```

#### 404 - Kategorie nenalezena

```json
json[]
```

*Poznámka: Endpoint `/api/listings/category` vrací prázdné pole místo error zprávy*

#### 500 - Serverová chyba

```json
json{  "error": "Database connection failed",  "stack": "Error stack trace..."}
```

#### 500 - Health check chyba

```json
json{  "ok": false,  "error": "Database connection failed"}
```

***

### Sjednocení API mezi projekty

#### Rozdíly mezi projekty

Na základě analýzy dvou projektů byly identifikovány tyto rozdíly:

```
```

#### Doporučení pro sjednocení

**1. Standardizace datových polí:**

```typescript
typescript// Doporučená struktura pro všechny projektyinterface StandardListing {  // Plocha - sjednotit na jeden způsob  usable_area: number;      // Užitná plocha  floor_area?: number;      // Podlahová plocha (volitelná)  total_area?: number;      // Celková plocha (volitelná)    // Nebo alternativně pouze  size: number;             // Hlavní plocha  size_type: 'usable' | 'floor' | 'total'; // Typ plochy}
```

**2. Sjednotit error handling:**

```json
json// Konzistentní formát pro všechny chyby{  "error": "Category not found",  "code": "CATEGORY_NOT_FOUND",  "status": 404}
```

**3. Univerzální kategorie endpoint:**

```http
httpGET /api/listings/filter?category=byty&subcategory=1kk&limit=50
```

**4. Standardní response formát:**

```json
json{  "data": [...],  "pagination": {    "page": 1,    "limit": 50,    "total": 125,    "pages": 3  },  "meta": {    "query_time": "23ms",    "total_found": 125  }}
```

***

### Plánovaná vylepšení

#### 1. Sjednocené filtrování (rozšíření stávajících)

```http
httpGET /api/listings/filter?category=byty&subcategory=2kk&price_min=3000000&price_max=5000000&location=praha&size_min=50
```

#### 2. Pokročilé vyhledávání

```http
httpGET /api/listings/search?q=moderní+byt&location=praha&category=byty
```

#### 3. Autentifikace a authorization

```http
httpAuthorization: Bearer YOUR_API_KEYX-Project-ID: project_abc123
```

#### 4. Pagination pro všechny endpointy

```http
httpGET /api/listings/all?page=2&limit=20GET /api/listings/category?slug=byty&page=1&limit=50
```

#### 5. Pokročilé sorting

```http
httpGET /api/listings/all?sort=price&order=desc&sort_secondary=size&order_secondary=asc
```

#### 6. Bulk operace

```http
httpGET /api/listings/bulk?ids=507f1f77bcf86cd799439011,507f1f77bcf86cd799439012
```

#### 7. Realtime notifikace

```http
httpGET /api/listings/subscribe?category=byty&price_max=5000000
```

***

### Typické workflow příklady

#### 1. Načtení inzerátů pro kategorii

```javascript
javascript// 1. Získat inzeráty podle kategorieconst response = await fetch('/api/listings/category?slug=byty');const apartments = await response.json();// 2. Zobrazit první stránku výsledkůapartments.slice(0, 20).forEach(listing => {  console.log(`${listing.name} - ${listing.price} Kč`);});
```

#### 2. Detail nemovitosti s kompletními informacemi

```javascript
javascript// 1. Získat detail konkrétního inzerátuconst response = await fetch('/api/listings/detail?id=507f1f77bcf86cd799439011');const listing = await response.json();// 2. Zobrazit galerii obrázkůlisting.galleryUrls?.forEach(url => {  console.log(`Image: ${url}`);});// 3. Zobrazit vizualizacelisting.visualizations?.forEach(viz => {  console.log(`${viz.name}: ${viz.url}`);});
```

#### 3. Filtrování podle ceny a velikosti

```javascript
javascript// 1. Získat všechny inzerátyconst response = await fetch('/api/listings/all?limit=1000');const allListings = await response.json();// 2. Filtrovat na frontend straně (nebo lépe implementovat v API)const filtered = allListings.filter(listing => {  const size = listing.usable_area || listing.size || 0;  return listing.price >= 3000000 &&          listing.price <= 6000000 &&          size >= 50;});
```
