Resumen de la Referencia API

Documentación completa de referencia para la API de Partners de LosCenotes.

URL Base

Única URL para todos los ambientes:

https://service-gateway.loscenotes.com

Ambiente	Prefijo de API Key	Descripción
Sandbox	sk_test_	Datos de prueba, sin cargos reales
Producción	pk_live_	Datos reales, transacciones reales

IMPORTANTE: El sistema detecta automáticamente el ambiente basándose en el prefijo de tu API Key. No necesitas cambiar la URL.

Autenticación

Todas las peticiones API deben incluir tu API key en el encabezado X-API-Key:

X-API-Key: sk_live_tu_api_key

Para el ambiente sandbox:

X-API-Key: sk_test_tu_api_key

Formato de Petición

La API acepta peticiones en formato JSON con el encabezado Content-Type: application/json.

POST /api/partner/reservations
Content-Type: application/json
X-API-Key: sk_test_tu_api_key

{
  "cenoteId": "c3n0t3-1234-5678-90ab",
  "date": "2024-07-15T10:00:00Z",
  "visitors": 4,
  "email": "huésped@ejemplo.com"
}

Formato de Respuesta

Todas las respuestas de la API siguen una estructura consistente:

{
  "success": true,
  "message": "operation.success",
  "data": { /* datos de respuesta */ },
  "pagination": { /* info de paginación para endpoints de lista */ },
  "currency": { /* info de moneda para endpoints de precios */ }
}

Campos de Respuesta Exitosa

Campo	Tipo	Descripción
success	boolean	Siempre true para respuestas exitosas
message	string	Clave de mensaje i18n (ej., 'cenote.lista_recuperada_exitosamente')
data	object/array	Los datos principales de respuesta
pagination	object	Info de paginación (solo endpoints de lista)
currency	object	Info de cambio de moneda (solo endpoints de precios)

Formato de Respuesta de Error

{
  "success": false,
  "message": "validation.campo_requerido",
  "error": "Solicitud Incorrecta",
  "statusCode": 400,
  "code": "ERROR_VALIDACION",
  "timestamp": "2025-01-20T10:30:00.000Z",
  "path": "/api/partner/cenotes",
  "errors": {
    "messages": ["Nombre es requerido", "Email debe ser válido"],
    "fields": {
      "email": ["Formato de email inválido"],
      "name": ["Campo es requerido"]
    }
  }
}

Paginación

Los endpoints de lista usan paginación basada en desplazamiento:

Petición de Paginación

GET /api/partner/cenotes?page=1&perPage=20

Respuesta de Paginación

La respuesta incluye metadatos de paginación con EXACTAMENTE estos campos:

{
  "success": true,
  "data": [ /* array de cenotes */ ],
  "pagination": {
    "total": 150,
    "perPage": 20,
    "currentPage": 1,
    "lastPage": 8
  }
}

Campos de Paginación

Campo	Tipo	Descripción
total	number	Número total de elementos
perPage	number	Elementos por página
currentPage	number	Número de página actual
lastPage	number	Número de última página

Nota: La API NO incluye hasNextPage, hasPreviousPage, nextCursor, prevCursor, ni otros campos de paginación. Solo los 4 campos mostrados arriba.

Parámetros de Paginación

Parámetro	Tipo	Por Defecto	Máx	Descripción
page	entero	1	-	Número de página
perPage	entero	15	100	Número de elementos por página

Filtrado y Ordenamiento

Parámetros Comunes de Filtro

La mayoría de los endpoints de lista soportan estos filtros comunes:

Parámetro	Tipo	Descripción	Ejemplo
isActive	boolean	Filtrar por estado activo	?isActive=true
search	string	Búsqueda de texto en campos buscables	?search=dos ojos
createdAfter	string	Filtrar por fecha de creación (ISO 8601)	?createdAfter=2024-01-01T00:00:00Z
createdBefore	string	Filtrar por fecha de creación (ISO 8601)	?createdBefore=2024-12-31T23:59:59Z

Ordenamiento

Usa los parámetros sortBy y sortDirection:

GET /api/partner/cenotes?sortBy=name&sortDirection=asc

Parámetro	Tipo	Valores	Por Defecto	Descripción
sortBy	string	Varía por endpoint	createdAt	Campo por el cual ordenar
sortDirection	string	asc, desc	desc	Dirección de ordenamiento

Selección de Campos

Optimiza las respuestas solicitando solo los campos necesarios:

GET /api/partner/cenotes?fields=id,name,location,pricing

La respuesta solo incluirá los campos especificados:

{
  "success": true,
  "data": [
    {
      "id": "c3n0t3-1234",
      "name": "Cenote Dos Ojos",
      "location": {
        "latitude": 20.3274,
        "longitude": -87.3821
      },
      "pricing": {
        "adult": 350,
        "child": 200,
        "currency": "MXN"
      }
    }
  ]
}

Expansión

Incluye recursos relacionados en las respuestas:

GET /api/partner/reservations/res_1234?expand=cenote

La respuesta incluye recursos expandidos:

{
  "success": true,
  "data": {
    "id": "res_1234",
    "status": "confirmada",
    "cenote": {
      "id": "c3n0t3-1234",
      "name": "Cenote Dos Ojos",
      "location": { /* ... */ }
    },
    "guest": {
      "id": "guest_5678",
      "name": "Juan Pérez",
      "email": "juan@ejemplo.com"
    }
  }
}

Localización

La API soporta múltiples idiomas mediante el encabezado Accept-Language:

Accept-Language: es-MX

Idiomas soportados:

Código	Idioma	Región
en	Inglés	Por defecto
es	Español	Global
es-MX	Español	México

Los mensajes de respuesta y algunos campos de datos serán localizados:

{
  "success": true,
  "message": "cenotes.lista_recuperada_exitosamente",
  "data": [
    {
      "id": "c3n0t3-1234",
      "name": "Cenote Dos Ojos",
      "description": "Un hermoso cenote con aguas cristalinas...",
      "amenities": [
        {
          "id": "snorkeling",
          "name": "Snorkel",
          "description": "Equipo de snorkel disponible"
        }
      ]
    }
  ]
}

Límites de Tasa

Las respuestas de la API incluyen encabezados de límite de tasa:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642261200
X-RateLimit-Window: 3600

Ver Límites de Tasa para información detallada.

Modo Sandbox

Las respuestas del sandbox incluyen un campo _sandbox:

{
  "success": true,
  "message": "cenotes.lista_recuperada_exitosamente",
  "data": [ /* datos de prueba */ ],
  "_sandbox": true
}

Endpoints de la API

Recursos Principales

Cenotes

Gestiona información y disponibilidad de cenotes.

• GET /api/partner/cenotes - Listar cenotes disponibles
• GET /api/partner/availability/{cenoteId} - Verificar disponibilidad del cenote

Reservaciones

Gestiona reservaciones y bookings de cenotes.

• GET /api/partner/reservations - Listar reservaciones del partner
• POST /api/partner/reservations - Crear nueva reservación
• GET /api/partner/reservations/{id} - Obtener detalles de reservación
• POST /api/partner/reservations/{id}/cancel - Cancelar reservación

Endpoints de Utilidad

Autenticación

• GET /api/auth/verify - Verificar API key
• POST /api/auth/refresh - Refrescar autenticación

Sistema

• GET /api/system/health - Verificación de salud del sistema
• GET /api/system/status - Estado del servicio

Geografía

• GET /api/locations/states - Listar estados
• GET /api/locations/municipalities - Listar municipios

Precios

• POST /api/pricing/calculate - Calcular precios
• GET /api/currencies - Obtener información de monedas

Endpoints de Configuración

Patrones Comunes

Operaciones en Lote

Algunos endpoints soportan operaciones en lote:

POST /api/partner/reservations/bulk
Content-Type: application/json

{
  "reservations": [
    {
      "cenoteId": "c3n0t3-1234",
      "date": "2024-07-15T10:00:00Z",
      "visitors": 4
    },
    {
      "cenoteId": "c3n0t3-5678",
      "date": "2024-07-16T14:00:00Z",
      "visitors": 2
    }
  ]
}

Peticiones Condicionales

Usa ETags para peticiones condicionales:

GET /api/partner/cenotes/c3n0t3-1234
If-None-Match: "33a64df551425fcc"

Actualizaciones Parciales

Usa PATCH para actualizaciones parciales de recursos:

PATCH /api/partner/reservations/res_1234
Content-Type: application/json

{
  "visitors": 6,
  "specialRequests": "Almuerzo vegetariano requerido"
}

Manejo de Errores

La API usa códigos de estado HTTP estándar y proporciona información detallada de errores:

Código de Estado	Descripción
200	OK - Petición exitosa
201	Creado - Recurso creado
204	Sin Contenido - Éxito sin cuerpo de respuesta
400	Petición Incorrecta - Petición inválida
401	No Autorizado - API key inválida
403	Prohibido - Permisos insuficientes
404	No Encontrado - Recurso no encontrado
409	Conflicto - Conflicto de recurso
422	Entidad No Procesable - Validación fallida
429	Demasiadas Peticiones - Límite de tasa excedido
500	Error Interno del Servidor - Error del servidor
503	Servicio No Disponible - Servicio temporalmente no disponible

Ver Manejo de Errores para información detallada de errores.

Obtener Ayuda

• 📧 Email: partners@loscenotes.com
• 📊 Estado de API: Verificar estado del servicio
• 🐛 GitHub Issues: Reportar bugs

Registro de Cambios de la API

Rastrea cambios y actualizaciones de la API:

Próximos Pasos

• API de Cenotes - Documentación detallada del endpoint de cenotes
• API de Reservaciones - Referencia completa de la API de reservaciones
• SDKs - Bibliotecas cliente específicas por lenguaje