docs: add comprehensive API documentation
- Document all public and admin endpoints - Include request/response examples - Add validation rules reference - Document authentication flow
This commit is contained in:
TenerifeProp Dev
567
docs/API.md
Normal file
567
docs/API.md
Normal file
@@ -0,0 +1,567 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user