# 馃摗 Documentaci贸n de API - Karibeo ## Base URL ``` https://karibeo.lesoluciones.net:8443/api/v1 ``` ## Autenticaci贸n Todos los endpoints protegidos requieren un token JWT en el header: ```http Authorization: Bearer ``` ### Obtener Token ```http POST /auth/login Content-Type: application/json { "email": "user@example.com", "password": "securepassword" } ``` **Respuesta**: ```json { "token": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "uuid", "email": "user@example.com", "name": "User Name", "role": "admin" } } ``` ### Refresh Token ```http POST /auth/refresh Content-Type: application/json { "refreshToken": "eyJhbGciOiJIUzI1NiIs..." } ``` ## Endpoints ### Autenticaci贸n #### POST /auth/register Registrar nuevo usuario **Body**: ```json { "name": "John Doe", "email": "john@example.com", "password": "SecurePass123!", "type": "tourist", "location": { "lat": 18.4861, "lng": -69.9312 }, "preferences": { "language": "es" } } ``` #### GET /auth/profile Obtener perfil del usuario autenticado **Respuesta**: ```json { "id": "uuid", "email": "john@example.com", "name": "John Doe", "role": "tourist", "avatar": "https://...", "wallet": { "balance": 150.50, "currency": "USD" } } ``` ### Usuarios (Admin) #### GET /admin/users Listar todos los usuarios **Query Parameters**: - `page` (int): N煤mero de p谩gina (default: 1) - `limit` (int): Items por p谩gina (default: 10) - `role` (string): Filtrar por rol **Respuesta**: ```json { "data": [ { "id": "uuid", "name": "User Name", "email": "user@example.com", "role": "tourist", "status": "active", "verified": true, "createdAt": "2024-01-15T10:30:00Z" } ], "pagination": { "total": 100, "page": 1, "pages": 10 } } ``` #### POST /admin/users Crear nuevo usuario #### PUT /admin/users/:id Actualizar usuario #### DELETE /admin/users/:id Eliminar usuario ### Establecimientos #### GET /establishments Listar establecimientos **Query Parameters**: - `type` (string): hotel, restaurant, commerce - `page` (int) - `limit` (int) - `latitude` (float): Para b煤squeda geogr谩fica - `longitude` (float) - `radius` (float): Radio en km **Respuesta**: ```json { "data": [ { "id": "uuid", "name": "Hotel Paradise", "type": "hotel", "rating": 4.5, "location": { "latitude": 18.4861, "longitude": -69.9312, "address": "Calle Principal #123" }, "amenities": ["wifi", "pool", "restaurant"], "priceRange": "$$", "verified": true } ] } ``` #### POST /establishments Crear nuevo establecimiento **Body**: ```json { "name": "My Hotel", "type": "hotel", "description": "Beautiful hotel...", "location": { "latitude": 18.4861, "longitude": -69.9312, "address": "Street 123" }, "amenities": ["wifi", "pool"], "priceRange": "$$", "images": ["url1", "url2"] } ``` #### GET /establishments/:id Obtener detalles de establecimiento #### PUT /establishments/:id Actualizar establecimiento #### DELETE /establishments/:id Eliminar establecimiento ### Reservas #### GET /reservations Listar reservas del usuario **Respuesta**: ```json { "data": [ { "id": "uuid", "establishmentId": "uuid", "type": "hotel", "checkInDate": "2024-03-15", "checkOutDate": "2024-03-20", "guestsCount": 2, "totalAmount": 500.00, "status": "confirmed", "createdAt": "2024-01-10T10:00:00Z" } ] } ``` #### POST /reservations Crear nueva reserva **Body**: ```json { "establishmentId": "uuid", "type": "hotel", "checkInDate": "2024-03-15", "checkOutDate": "2024-03-20", "guestsCount": 2, "specialRequests": "Late check-in", "contactInfo": { "phone": "+1234567890", "email": "guest@example.com" } } ``` #### PUT /reservations/:id Actualizar reserva #### DELETE /reservations/:id Cancelar reserva ### Rese帽as #### GET /reviews Obtener rese帽as **Query Parameters**: - `establishmentId` (string): Filtrar por establecimiento - `userId` (string): Filtrar por usuario - `rating` (int): Filtrar por calificaci贸n **Respuesta**: ```json { "data": [ { "id": "uuid", "establishmentId": "uuid", "userId": "uuid", "userName": "John Doe", "rating": 5, "comment": "Excellent service!", "images": ["url1", "url2"], "createdAt": "2024-01-15T10:00:00Z", "helpful": 12 } ], "stats": { "averageRating": 4.5, "totalReviews": 150 } } ``` #### POST /reviews Crear rese帽a **Body**: ```json { "establishmentId": "uuid", "rating": 5, "comment": "Great experience!", "images": ["url1", "url2"] } ``` ### Destinos #### GET /destinations Listar destinos tur铆sticos **Respuesta**: ```json { "data": [ { "id": "uuid", "name": "Punta Cana", "description": "Beautiful beaches...", "country": "Dominican Republic", "images": ["url1", "url2"], "highlights": ["beaches", "resorts", "nightlife"], "bestTimeToVisit": "December-April", "popularActivities": ["snorkeling", "golf"] } ] } ``` #### GET /destinations/:id Detalles de destino ### Lugares #### GET /places Listar lugares de inter茅s **Query Parameters**: - `destinationId` (string) - `category` (string): restaurant, attraction, shopping - `latitude`, `longitude`, `radius` **Respuesta**: ```json { "data": [ { "id": "uuid", "name": "Historic Site", "category": "attraction", "description": "...", "location": {...}, "openingHours": { "monday": "9:00-18:00", "tuesday": "9:00-18:00" }, "entryFee": 10.00, "rating": 4.5 } ] } ``` ### Emergencias (POLITUR) #### GET /emergency/incidents Listar incidentes **Requiere**: Rol de `politur`, `admin` o `super_admin` **Respuesta**: ```json { "incidents": [ { "id": "uuid", "type": "medical", "severity": "high", "location": {...}, "description": "...", "status": "active", "reportedBy": "uuid", "assignedOfficer": "uuid", "createdAt": "2024-01-15T10:00:00Z" } ] } ``` #### POST /emergency/incidents Reportar incidente #### GET /emergency/alerts Obtener alertas activas #### POST /emergency/panic-button Activar bot贸n de p谩nico **Body**: ```json { "location": { "latitude": 18.4861, "longitude": -69.9312 }, "details": "Emergency description" } ``` ### Channel Manager #### GET /channel-manager/channels Listar canales conectados **Respuesta**: ```json { "channels": [ { "id": "booking", "name": "Booking.com", "status": "active", "connected": true, "listingsCount": 5, "lastSync": "2024-01-15T10:00:00Z" } ] } ``` #### POST /channel-manager/sync Sincronizar con canales #### GET /channel-manager/listings Listar propiedades #### POST /channel-manager/listings Crear nueva propiedad ### Comisiones #### GET /commissions/rules Obtener reglas de comisiones **Respuesta**: ```json { "rules": [ { "id": "uuid", "type": "percentage", "value": 15, "entityType": "hotel", "conditions": { "minAmount": 100 }, "active": true } ] } ``` #### POST /commissions/rules Crear regla de comisi贸n #### GET /commissions/payments Historial de pagos de comisiones ### CRM #### GET /crm/contacts Listar contactos **Respuesta**: ```json { "contacts": [ { "id": "uuid", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+1234567890", "segment": "VIP Travelers", "tags": ["repeat_customer"], "lastInteraction": "2024-01-15T10:00:00Z", "totalSpent": 5000.00 } ] } ``` #### POST /crm/contacts Crear contacto #### GET /crm/campaigns Listar campa帽as #### POST /crm/campaigns Crear campa帽a de marketing ### Analytics #### GET /analytics/dashboard Obtener m茅tricas del dashboard **Respuesta**: ```json { "stats": { "totalUsers": 1500, "totalRevenue": 156750.50, "totalBookings": 892, "activeServices": 89, "monthlyGrowth": 8.5, "conversionRate": 3.2 }, "charts": { "revenueByMonth": [...], "bookingsByType": [...], "topDestinations": [...] } } ``` #### GET /analytics/reports Generar reportes personalizados **Query Parameters**: - `type` (string): revenue, bookings, users - `startDate` (date) - `endDate` (date) - `format` (string): json, csv, pdf ### Configuraci贸n #### GET /config/apis Obtener configuraci贸n de APIs externas #### PUT /config/apis Actualizar configuraci贸n de APIs #### GET /config/parameters Obtener par谩metros del sistema #### GET /config/integrations Listar integraciones activas ### Pagos #### POST /payments/create-intent Crear intenci贸n de pago **Body**: ```json { "amount": 100.00, "currency": "USD", "description": "Hotel booking", "metadata": { "bookingId": "uuid" } } ``` **Respuesta**: ```json { "clientSecret": "pi_xxx_secret_xxx", "paymentIntentId": "pi_xxx" } ``` #### POST /payments/confirm Confirmar pago #### GET /payments/history Historial de pagos ### Uploads #### POST /upload Subir archivo 煤nico **Form Data**: - `file`: Archivo binario - `folder`: Carpeta destino (opcional) **Respuesta**: ```json { "url": "https://cdn.karibeo.com/uploads/xxx.jpg", "fileName": "xxx.jpg", "size": 102400, "mimeType": "image/jpeg" } ``` #### POST /upload/multiple Subir m煤ltiples archivos ## C贸digos de Estado | C贸digo | Descripci贸n | |--------|-------------| | 200 | OK - Solicitud exitosa | | 201 | Created - Recurso creado | | 400 | Bad Request - Datos inv谩lidos | | 401 | Unauthorized - Token inv谩lido o expirado | | 403 | Forbidden - Sin permisos | | 404 | Not Found - Recurso no encontrado | | 409 | Conflict - Conflicto (ej: email duplicado) | | 422 | Unprocessable Entity - Validaci贸n fallida | | 429 | Too Many Requests - Rate limit excedido | | 500 | Internal Server Error - Error del servidor | ## Rate Limiting - **An贸nimos**: 100 requests / hora - **Autenticados**: 1000 requests / hora - **Admin**: 5000 requests / hora Headers de respuesta: ```http X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640000000 ``` ## Paginaci贸n Endpoints que retornan listas soportan paginaci贸n: **Query Parameters**: - `page`: N煤mero de p谩gina (default: 1) - `limit`: Items por p谩gina (default: 10, max: 100) **Respuesta**: ```json { "data": [...], "pagination": { "total": 250, "page": 1, "pages": 25, "limit": 10 } } ``` ## Filtros y Ordenamiento **Query Parameters**: - `sort`: Campo para ordenar - `order`: asc o desc - `filter[campo]`: Filtrar por campo Ejemplo: ``` GET /establishments?sort=rating&order=desc&filter[type]=hotel ``` ## Webhooks Para eventos en tiempo real, el sistema soporta webhooks: ```http POST /webhooks/configure Content-Type: application/json { "url": "https://your-domain.com/webhook", "events": ["booking.created", "payment.completed"], "secret": "your_webhook_secret" } ``` Eventos disponibles: - `booking.created` - `booking.confirmed` - `booking.cancelled` - `payment.completed` - `payment.failed` - `review.created` - `user.registered` ## SDKs y Libraries ### JavaScript/TypeScript ```bash npm install @karibeo/sdk ``` ```typescript import Karibeo from '@karibeo/sdk'; const client = new Karibeo({ apiKey: 'your_api_key', baseUrl: 'https://karibeo.lesoluciones.net:8443/api/v1' }); const bookings = await client.reservations.list(); ``` ### Python ```bash pip install karibeo ``` ```python from karibeo import Client client = Client(api_key='your_api_key') bookings = client.reservations.list() ``` ## Postman Collection Importar colecci贸n completa: ``` https://www.postman.com/karibeo/workspace/karibeo-api ``` ## Testing ### Credenciales de Testing ``` Email: test@karibeo.com Password: Test123! ``` ### Endpoints de Testing ``` https://karibeo-staging.lesoluciones.net:8443/api/v1 ``` --- **Soporte**: api-support@karibeo.com **脷ltima actualizaci贸n**: 2025-01-12