729 lines
12 KiB
Markdown
729 lines
12 KiB
Markdown
# 📡 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 <token>
|
|
```
|
|
|
|
### 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 |