Refactor: Analyze project documentation
This commit is contained in:
gpt-engineer-app[bot]
729
docs/API.md
Normal file
729
docs/API.md
Normal file
@@ -0,0 +1,729 @@
|
||||
# 📡 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
|
||||
Reference in New Issue
Block a user