TenerifeProp/docs/API.md

# TenerifeProp API Documentation

## Base URL

```
Development: http://localhost:8080
Production: https://api.tenerifeprop.com
```

## Authentication

The API uses session-based authentication with HTTP-only cookies.

### Login

```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@tenerifeprop.com",
  "password": "admin123"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "user-001",
    "email": "admin@tenerifeprop.com",
    "name": "Admin",
    "role": "admin",
    "language": "es"
  }
}
```

### Logout

```http
POST /api/auth/logout
```

### Get Current User

```http
GET /api/auth/me
Cookie: session=<session-id>
```

---

## Public Endpoints

### Properties

#### List Properties

```http
GET /api/properties?type=urban&city=Adeje&minPrice=100000&maxPrice=500000&lang=es&limit=20&offset=0
```

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| type | string | Filter by type: `urban`, `agricultural`, `house`, `apartment` |
| city | string | Filter by city (partial match) |
| minPrice | number | Minimum price in EUR |
| maxPrice | number | Maximum price in EUR |
| lang | string | Language for translations: `es`, `ru`, `en` |
| limit | number | Results per page (default: 20) |
| offset | number | Pagination offset (default: 0) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "prop-001",
      "slug": "terreno-urbano-adeje",
      "reference": "TP-001",
      "type": "urban",
      "status": "active",
      "title": "Terreno Urbano en Adeje",
      "description": "...",
      "price": 385000,
      "area": 2500,
      "city": "Adeje",
      ...
    }
  ],
  "total": 42
}
```

#### Get Property by Slug

```http
GET /api/properties/:slug?lang=es
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "prop-001",
    "slug": "terreno-urbano-adeje",
    "title": "Terreno Urbano en Adeje",
    ...
  }
}
```

#### Get Featured Properties

```http
GET /api/properties/featured?lang=es
```

---

### Leads

#### Create Lead

```http
POST /api/leads
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+34 600 123 456",
  "message": "I'm interested in this property",
  "property_id": "prop-001",
  "language": "en"
}
```

**Validation:**
- `name`: required, 2-100 characters
- `email`: required, valid email format
- `phone`: required, 6-20 characters
- `message`: optional, max 2000 characters
- `property_id`: optional, valid UUID
- `language`: optional, one of `es`, `ru`, `en`

---

### Testimonials

#### List Approved Testimonials

```http
GET /api/testimonials?lang=es
```

---

### FAQ

#### List Active FAQ

```http
GET /api/faq?lang=es
```

---

### Services

#### List Active Services

```http
GET /api/services?lang=es
```

---

### Settings

#### Get Site Settings

```http
GET /api/settings
```

**Response:**
```json
{
  "success": true,
  "data": {
    "site_name": "TenerifeProp",
    "phone": "+34 922 123 456",
    "whatsapp": "+34 600 123 456",
    "email": "info@tenerifeprop.com",
    "default_map_center": { "lat": 28.1227, "lng": -16.6942 },
    "default_map_zoom": 11
  }
}
```

---

### Cities

#### List All Cities

```http
GET /api/cities
```

---

### Stats

#### Get Public Stats

```http
GET /api/stats
```

**Response:**
```json
{
  "success": true,
  "data": {
    "totalViews": 12345,
    "totalLeads": 42,
    "activeProperties": 15
  }
}
```

---

## Admin Endpoints

All admin endpoints require authentication with admin or agent role.

### Properties

#### Create Property

```http
POST /api/admin/properties
Cookie: session=<session-id>
Content-Type: application/json

{
  "type": "urban",
  "status": "active",
  "land_type": "urban",
  "title_es": "Terreno en Adeje",
  "title_ru": "Участок в Адехе",
  "description_es": "Descripción completa...",
  "description_ru": "Полное описание...",
  "address": "Avda. de la Constitución",
  "city": "Adeje",
  "postal_code": "38670",
  "lat": 28.1227,
  "lng": -16.6942,
  "area": 2500,
  "price": 385000,
  "water": "available",
  "electricity": "available",
  "orientation": "south",
  "views_sea": true,
  "has_license": true,
  "is_buildable": true,
  "images": ["https://..."],
  "is_featured": false,
  "is_exclusive": true
}
```

#### Update Property

```http
PUT /api/admin/properties/:id
Cookie: session=<session-id>
Content-Type: application/json

{
  "price": 375000,
  "status": "reserved"
}
```

#### Delete Property

```http
DELETE /api/admin/properties/:id
Cookie: session=<session-id>
```

---

### Leads

#### Update Lead

```http
PUT /api/admin/leads/:id
Cookie: session=<session-id>
Content-Type: application/json

{
  "status": "contacted",
  "priority": "high",
  "notes": "Called client, very interested"
}
```

#### Delete Lead

```http
DELETE /api/admin/leads/:id
Cookie: session=<session-id>
```

---

### Testimonials

#### Create Testimonial

```http
POST /api/admin/testimonials
Cookie: session=<session-id>
Content-Type: application/json

{
  "name": "John Smith",
  "avatar": "https://...",
  "location": "London, UK",
  "rating": 5,
  "text_es": "Excelente servicio!",
  "text_ru": "Отличный сервис!",
  "is_approved": true,
  "is_featured": false
}
```

#### Update Testimonial

```http
PUT /api/admin/testimonials/:id
Cookie: session=<session-id>
```

#### Delete Testimonial

```http
DELETE /api/admin/testimonials/:id
Cookie: session=<session-id>
```

---

### FAQ

#### Create FAQ

```http
POST /api/admin/faq
Cookie: session=<session-id>
Content-Type: application/json

{
  "question_es": "¿Qué documentos necesito?",
  "question_ru": "Какие документы нужны?",
  "answer_es": "Necesita NIE y cuenta bancaria.",
  "answer_ru": "Нужен NIE и банковский счет.",
  "category": "general",
  "order_num": 1,
  "is_active": true
}
```

#### Update FAQ

```http
PUT /api/admin/faq/:id
Cookie: session=<session-id>
```

#### Delete FAQ

```http
DELETE /api/admin/faq/:id
Cookie: session=<session-id>
```

---

### Services

#### Create Service

```http
POST /api/admin/services
Cookie: session=<session-id>
Content-Type: application/json

{
  "icon": "bi-shield-check",
  "title_es": "Legalidad Garantizada",
  "title_ru": "Гарантия законности",
  "description_es": "Verificación completa...",
  "description_ru": "Полная проверка...",
  "order_num": 1,
  "is_active": true
}
```

#### Update Service

```http
PUT /api/admin/services/:id
Cookie: session=<session-id>
```

#### Delete Service

```http
DELETE /api/admin/services/:id
Cookie: session=<session-id>
```

---

### Settings

#### Update Settings

```http
PUT /api/admin/settings
Cookie: session=<session-id>
Content-Type: application/json

{
  "site_name": "TenerifeProp",
  "phone": "+34 922 123 456",
  "whatsapp": "+34 600 123 456",
  "email": "info@tenerifeprop.com"
}
```

---

### Stats

#### Get Admin Stats

```http
GET /api/admin/stats
Cookie: session=<session-id>
```

**Response:**
```json
{
  "success": true,
  "data": {
    "properties": {
      "total": 20,
      "active": 15,
      "reserved": 3,
      "sold": 2
    },
    "leads": {
      "total": 42,
      "new": 10,
      "contacted": 15,
      "qualified": 12,
      "closed": 5
    },
    "analytics": {
      "views": 12345,
      "favorites": 234,
      "inquiries": 67
    },
    "averages": {
      "price": 285000,
      "area": 1800,
      "pricePerM2": 158
    }
  }
}
```

---

## Error Responses

All endpoints return errors in a consistent format:

```json
{
  "success": false,
  "error": "Error message describing what went wrong"
}
```

### HTTP Status Codes

| Status | Description |
|--------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Authentication required |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found |
| 500 | Internal Server Error |

---

## Validation Rules

### Property Types
- `type`: `urban`, `agricultural`, `house`, `apartment`
- `status`: `active`, `reserved`, `sold`, `inactive`
- `land_type`: `urban`, `agricultural`, `residential`
- `water`, `electricity`, `phone`, `drainage`: `available`, `nearby`, `unavailable`
- `road`: `asphalt`, `paved`, `dirt`
- `gas`: `available`, `nearby`, `unavailable`, `planned`
- `orientation`: `north`, `south`, `east`, `west`, `northeast`, `northwest`, `southeast`, `southwest`
- `topography`: `flat`, `slope`, `steep`

### Testimonial
- `rating`: 1-5 (integer)

### Lead
- `name`: 2-100 characters
- `email`: valid email format
- `phone`: 6-20 characters
- `message`: max 2000 characters

---

## Rate Limiting

Public endpoints: 100 requests per minute
Admin endpoints: 1000 requests per minute

---

## CORS

Allowed origins:
- `http://localhost:3000` (development)
- `https://tenerifeprop.com` (production)
- `https://www.tenerifeprop.com` (production)

---

## Language Support

All localized endpoints accept a `lang` query parameter:
- `es` - Spanish (default)
- `ru` - Russian
- `en` - English