ellecio2/karibeo_backend_admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
karibeo_backend_admin/docs/API.md
gpt-engineer-app[bot] bdb8b2d7e2 Refactor: Analyze project documentation
2025-10-12 01:00:32 +00:00

12 KiB
Raw Permalink Blame History

📡 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:

Authorization: Bearer <token>

Obtener Token

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

Respuesta:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name",
    "role": "admin"
  }
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Endpoints

Autenticación

POST /auth/register

Registrar nuevo usuario

Body:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "establishmentId": "uuid",
  "rating": 5,
  "comment": "Great experience!",
  "images": ["url1", "url2"]
}

Destinos

GET /destinations

Listar destinos turísticos

Respuesta:

{
  "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:

{
  "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:

{
  "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:

{
  "location": {
    "latitude": 18.4861,
    "longitude": -69.9312
  },
  "details": "Emergency description"
}

Channel Manager

GET /channel-manager/channels

Listar canales conectados

Respuesta:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "amount": 100.00,
  "currency": "USD",
  "description": "Hotel booking",
  "metadata": {
    "bookingId": "uuid"
  }
}

Respuesta:

{
  "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:

{
  "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:

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:

{
  "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:

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

npm install @karibeo/sdk

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

pip install karibeo

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