From a341850bc5ae533daad5d048a78e853a4f9e0fa2 Mon Sep 17 00:00:00 2001 From: TenerifeProp Dev Date: Sun, 5 Apr 2026 00:06:34 +0100 Subject: [PATCH] docs: add comprehensive API documentation - Document all public and admin endpoints - Include request/response examples - Add validation rules reference - Document authentication flow --- docs/API.md | 567 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 567 insertions(+) create mode 100644 docs/API.md diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..8c96c23 --- /dev/null +++ b/docs/API.md @@ -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= +``` + +--- + +## 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= +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= +Content-Type: application/json + +{ + "price": 375000, + "status": "reserved" +} +``` + +#### Delete Property + +```http +DELETE /api/admin/properties/:id +Cookie: session= +``` + +--- + +### Leads + +#### Update Lead + +```http +PUT /api/admin/leads/:id +Cookie: session= +Content-Type: application/json + +{ + "status": "contacted", + "priority": "high", + "notes": "Called client, very interested" +} +``` + +#### Delete Lead + +```http +DELETE /api/admin/leads/:id +Cookie: session= +``` + +--- + +### Testimonials + +#### Create Testimonial + +```http +POST /api/admin/testimonials +Cookie: session= +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= +``` + +#### Delete Testimonial + +```http +DELETE /api/admin/testimonials/:id +Cookie: session= +``` + +--- + +### FAQ + +#### Create FAQ + +```http +POST /api/admin/faq +Cookie: session= +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= +``` + +#### Delete FAQ + +```http +DELETE /api/admin/faq/:id +Cookie: session= +``` + +--- + +### Services + +#### Create Service + +```http +POST /api/admin/services +Cookie: session= +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= +``` + +#### Delete Service + +```http +DELETE /api/admin/services/:id +Cookie: session= +``` + +--- + +### Settings + +#### Update Settings + +```http +PUT /api/admin/settings +Cookie: session= +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= +``` + +**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 \ No newline at end of file