Saltar al contenido principal

API de Cenotes

Referencia completa para gestionar información de cenotes, disponibilidad y características.

Descripción General

La API de Cenotes te permite obtener información sobre cenotes en la Península de Yucatán, incluyendo sus ubicaciones, amenidades, precios y disponibilidad en tiempo real. Este es el recurso principal para la plataforma de turismo.

Endpoints

Listar Cenotes

Obtén una lista de cenotes con filtrado y paginación.

GET /api/partner/cenotes

Parámetros

ParámetroTipoRequeridoDescripciónEjemplo
pageintegerNoNúmero de página (por defecto: 1)?page=1
perPageintegerNoElementos por página (por defecto: 15, máx: 100)?perPage=20
cursorstringNoCursor para paginación basada en cursor?cursor=eyJpZCI6ImN0M3QzIn0
isActivebooleanNoFiltrar por estado activo?isActive=true
searchstringNoBuscar por nombre o descripción?search=dos ojos
location.statestringNoFiltrar por estado?location.state=Quintana Roo
location.municipalitystringNoFiltrar por municipio?location.municipality=Tulum
hasAmenitystringNoFiltrar por ID de amenidad?hasAmenity=snorkeling
priceRange.minnumberNoPrecio mínimo (MXN)?priceRange.min=200
priceRange.maxnumberNoPrecio máximo (MXN)?priceRange.max=500
rating.minnumberNoCalificación mínima (1-5)?rating.min=4
sortBystringNoCampo de ordenamiento?sortBy=name
sortDirectionstringNoDirección de ordenamiento (asc o desc)?sortDirection=asc
fieldsstringNoCampos separados por coma a incluir?fields=id,name,location,pricing
expandstringNoRecursos relacionados a incluir?expand=amenities,reviews

Campos de Ordenamiento

CampoDescripción
nameNombre del cenote (alfabético)
ratingCalificación promedio
pricing.adultPrecio para adultos
location.distanceDistancia desde coordenadas (requiere parámetro near)
createdAtFecha de creación
popularityPuntuación de popularidad basada en reservas

Ejemplo de Solicitud

curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes?isActive=true&search=dos&sortBy=rating&sortDirection=desc" \
-H "X-API-Key: sk_test_your_api_key" \
-H "Content-Type: application/json"

Ejemplo de Respuesta

{
"success": true,
"message": "cenotes.list_retrieved_successfully",
"data": [
{
"id": "c3n0t3-1234-5678-90ab",
"name": "Cenote Dos Ojos",
"slug": "cenote-dos-ojos",
"description": "Uno de los cenotes más famosos de la Riviera Maya, conocido por sus aguas cristalinas y extenso sistema de cuevas.",
"location": {
"latitude": 20.327423,
"longitude": -87.382118,
"address": "Carretera Tulum-Coba Km 5.5, Quintana Roo, México",
"state": "Quintana Roo",
"municipality": "Tulum",
"zipCode": "77780"
},
"pricing": {
"adult": 350,
"child": 200,
"senior": 250,
"currency": "MXN",
"includes": ["entrada", "chaleco_salvavidas", "equipo_basico_snorkel"]
},
"features": {
"type": "cave",
"depth": {
"min": 1,
"max": 10,
"unit": "meters"
},
"temperature": {
"avg": 24,
"unit": "celsius"
},
"visibility": {
"avg": 100,
"unit": "meters"
},
"difficulty": "beginner",
"accessibility": {
"wheelchairAccessible": false,
"stairsToWater": 15,
"platformAvailable": true
}
},
"amenities": [
{
"id": "parking",
"name": "Estacionamiento",
"category": "facilities",
"available": true,
"cost": 0
},
{
"id": "snorkeling",
"name": "Snorkel",
"category": "activities",
"available": true,
"cost": 0
},
{
"id": "diving",
"name": "Buceo en Cuevas",
"category": "activities",
"available": true,
"cost": 200,
"requirements": ["certification"]
},
{
"id": "restaurant",
"name": "Restaurante",
"category": "dining",
"available": true,
"hours": "08:00-17:00"
}
],
"capacity": {
"daily": 200,
"hourly": 25,
"current": 180
},
"schedule": {
"openTime": "08:00",
"closeTime": "17:00",
"timezone": "America/Cancun",
"daysOpen": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
]
},
"rating": {
"average": 4.7,
"count": 1247,
"breakdown": {
"5": 875,
"4": 280,
"3": 67,
"2": 18,
"1": 7
}
},
"images": [
{
"id": "img_001",
"url": "https://cdn.loscenotes.com/cenotes/dos-ojos/main.jpg",
"alt": "Aguas cristalinas del Cenote Dos Ojos",
"type": "main",
"order": 1
},
{
"id": "img_002",
"url": "https://cdn.loscenotes.com/cenotes/dos-ojos/underwater.jpg",
"alt": "Sistema de cuevas subacuáticas",
"type": "gallery",
"order": 2
}
],
"metadata": {
"featured": true,
"popularity": 95,
"lastUpdated": "2024-01-15T10:30:00Z",
"verifiedAt": "2024-01-10T14:20:00Z"
},
"isActive": true,
"createdAt": "2023-06-15T09:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"total": 89,
"perPage": 15,
"currentPage": 1,
"lastPage": 6,
"hasNextPage": true,
"hasPreviousPage": false
},
"currency": {
"base": "MXN",
"rates": {
"USD": 0.058,
"EUR": 0.054,
"CAD": 0.078
},
"lastUpdated": "2024-01-15T08:00:00Z"
}
}

Obtener Detalles del Cenote

Obtén información detallada sobre un cenote específico.

GET /api/partner/cenotes

Parámetros

ParámetroTipoRequeridoDescripción
idstringID del cenote (formato UUID)
expandstringNoRecursos relacionados a incluir
fieldsstringNoCampos específicos a incluir

Opciones de Expansión

ValorDescripciónDatos Adicionales
amenitiesIncluir información detallada de amenidadesObjetos completos de amenidades con descripciones
reviewsIncluir reseñas recientesÚltimas 10 reseñas con calificaciones
availabilityIncluir disponibilidad actualInformación de capacidad en tiempo real
nearbyIncluir cenotes cercanos5 cenotes más cercanos dentro de 50km
toursIncluir tours disponiblesPaquetes de tours que incluyen este cenote

Ejemplo de Solicitud

curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes/c3n0t3-1234-5678-90ab?expand=amenities,reviews" \
-H "X-API-Key: sk_test_your_api_key" \
-H "Content-Type: application/json"

Ejemplo de Respuesta

{
"success": true,
"message": "cenote.retrieved_successfully",
"data": {
"id": "c3n0t3-1234-5678-90ab",
"name": "Cenote Dos Ojos",
"slug": "cenote-dos-ojos",
"description": "Uno de los cenotes más famosos de la Riviera Maya...",
"longDescription": "Cenote Dos Ojos es un sistema de cuevas inundadas ubicado al norte de Tulum...",
"location": {
"latitude": 20.327423,
"longitude": -87.382118,
"address": "Carretera Tulum-Coba Km 5.5, Quintana Roo, México",
"state": "Quintana Roo",
"municipality": "Tulum",
"zipCode": "77780",
"directions": "Desde Tulum, toma la Carretera 109 hacia Cobá. El cenote está a 5.5km a tu derecha.",
"landmarks": [
"Zona Arqueológica de Tulum",
"Gran Cenote",
"Cenote Calavera"
]
},
"contact": {
"phone": "+52 984 123 4567",
"email": "info@cenotedosojos.com",
"website": "https://cenotedosojos.com",
"social": {
"facebook": "@CenoteDosOjos",
"instagram": "@cenotedosojos",
"tripadvisor": "attraction-dos-ojos"
}
},
"pricing": {
"adult": 350,
"child": 200,
"senior": 250,
"currency": "MXN",
"includes": ["entrada", "chaleco_salvavidas", "equipo_basico_snorkel"],
"excludes": ["transporte", "equipo_buceo", "servicio_guia"],
"groupDiscounts": [
{
"minSize": 10,
"discount": 0.1
},
{
"minSize": 20,
"discount": 0.15
}
]
},
"amenities": [
{
"id": "parking",
"name": "Estacionamiento",
"description": "Estacionamiento gratuito disponible para autos y autobuses",
"category": "facilities",
"icon": "parking",
"available": true,
"cost": 0,
"capacity": 50,
"features": ["gratis", "pavimentado", "con_sombra"]
},
{
"id": "restaurant",
"name": "Restaurante",
"description": "Cocina tradicional mexicana y refrescos",
"category": "dining",
"icon": "restaurant",
"available": true,
"hours": "08:00-17:00",
"menu": [
{
"item": "Tacos",
"price": 80,
"description": "Tacos frescos de pescado o pollo"
},
{
"item": "Fruta Fresca",
"price": 50,
"description": "Frutas tropicales de temporada"
}
]
}
],
"reviews": [
{
"id": "rev_001",
"rating": 5,
"title": "¡Absolutamente impresionante!",
"content": "El agua es increíblemente clara y las formaciones de las cuevas son impresionantes...",
"author": "Sarah M.",
"location": "Toronto, Canadá",
"date": "2024-01-10T15:30:00Z",
"verified": true,
"helpful": 15,
"photos": [
{
"url": "https://cdn.loscenotes.com/reviews/rev_001_1.jpg",
"caption": "Agua cristalina"
}
]
}
],
"guidelines": {
"beforeVisit": [
"Llega temprano para evitar multitudes",
"Trae solo protector solar biodegradable",
"Se prefiere pago en efectivo"
],
"duringVisit": [
"No tocar estalactitas o estalagmitas",
"Mantenerse en áreas designadas",
"Respetar la vida silvestre y vegetación"
],
"safety": [
"Los no nadadores deben usar chalecos salvavidas",
"No saltar o bucear sin supervisión",
"Seguir las instrucciones del guía en todo momento"
]
},
"weather": {
"bestVisitingMonths": [
"november",
"december",
"january",
"february",
"march",
"april"
],
"rainySeasonImpact": "minimal",
"temperature": {
"water": {
"avg": 24,
"unit": "celsius"
},
"air": {
"min": 18,
"max": 32,
"unit": "celsius"
}
}
},
"conservation": {
"status": "protected",
"protectedBy": "CONANP",
"conservation_efforts": [
"Monitoreo de calidad del agua",
"Límites de capacidad de visitantes",
"Requisitos de productos biodegradables"
],
"impact": {
"environmental": "low",
"community": "high",
"economic": "high"
}
},
"certifications": [
{
"name": "Bandera Azul",
"issuer": "Fundación para la Educación Ambiental",
"validUntil": "2024-12-31",
"criteria": ["calidad_agua", "gestion_ambiental", "seguridad"]
}
]
}
}

Verificar Disponibilidad

Verifica la disponibilidad en tiempo real para un cenote específico y rango de fechas.

GET /api/partner/cenotes/availability

Parámetros

ParámetroTipoRequeridoDescripciónEjemplo
idstringID del cenote-
startDatestringFecha de inicio (ISO 8601)2024-07-15
endDatestringNoFecha de fin (ISO 8601, máx 30 días)2024-07-20
visitorsintegerNoNúmero de visitantes4
timestringNoHorario específico10:00

Ejemplo de Solicitud

curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes/c3n0t3-1234/availability?startDate=2024-07-15&endDate=2024-07-20&visitors=4" \
-H "X-API-Key: sk_test_your_api_key"

Ejemplo de Respuesta

{
"success": true,
"message": "availability.retrieved_successfully",
"data": {
"cenoteId": "c3n0t3-1234-5678-90ab",
"dateRange": {
"start": "2024-07-15",
"end": "2024-07-20"
},
"requestedVisitors": 4,
"availability": [
{
"date": "2024-07-15",
"available": true,
"capacity": {
"total": 200,
"booked": 45,
"remaining": 155
},
"timeSlots": [
{
"time": "08:00",
"available": true,
"capacity": 25,
"booked": 5,
"remaining": 20
},
{
"time": "10:00",
"available": true,
"capacity": 25,
"booked": 12,
"remaining": 13
},
{
"time": "14:00",
"available": false,
"capacity": 25,
"booked": 25,
"remaining": 0,
"waitlist": true
}
],
"pricing": {
"adult": 350,
"child": 200,
"currency": "MXN"
}
},
{
"date": "2024-07-16",
"available": false,
"reason": "maintenance",
"nextAvailable": "2024-07-17"
}
],
"restrictions": [
{
"type": "weather",
"message": "La lluvia fuerte puede causar cierres temporales",
"datesAffected": ["2024-07-16"]
}
],
"recommendations": [
{
"date": "2024-07-15",
"time": "08:00",
"reason": "Mejor visibilidad y menos multitudes"
}
]
}
}

Cuerpo de la Solicitud

{
"date": "2024-07-15",
"timeSlots": [
{
"time": "08:00",
"capacity": 25,
"available": true
},
{
"time": "10:00",
"capacity": 25,
"available": false,
"reason": "maintenance"
}
],
"specialEvents": [
{
"name": "Taller de Fotografía",
"startTime": "14:00",
"endTime": "16:00",
"capacity": 10
}
]
}

Buscar Cenotes por Ubicación

Busca cenotes cerca de coordenadas específicas.

GET /api/partner/cenotes/search/nearby

Parámetros

ParámetroTipoRequeridoDescripciónEjemplo
latitudenumberCoordenada de latitud20.327423
longitudenumberCoordenada de longitud-87.382118
radiusnumberNoRadio de búsqueda en km (por defecto: 50, máx: 200)25
limitintegerNoMáx resultados (por defecto: 10, máx: 50)15

Ejemplo de Solicitud

curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes/search/nearby?latitude=20.327423&longitude=-87.382118&radius=25&limit=10" \
-H "X-API-Key: sk_test_your_api_key"

Ejemplo de Respuesta

{
"success": true,
"message": "cenotes.nearby_retrieved_successfully",
"data": [
{
"id": "c3n0t3-1234",
"name": "Cenote Dos Ojos",
"location": {
"latitude": 20.327423,
"longitude": -87.382118
},
"distance": {
"km": 0.0,
"miles": 0.0
},
"rating": 4.7,
"pricing": {
"adult": 350,
"currency": "MXN"
},
"available": true
},
{
"id": "c3n0t3-5678",
"name": "Gran Cenote",
"location": {
"latitude": 20.238942,
"longitude": -87.377892
},
"distance": {
"km": 9.8,
"miles": 6.1
},
"rating": 4.5,
"pricing": {
"adult": 300,
"currency": "MXN"
},
"available": true
}
],
"searchCriteria": {
"center": {
"latitude": 20.327423,
"longitude": -87.382118
},
"radius": 25,
"resultsFound": 2,
"searchTime": "2024-01-15T10:30:00Z"
}
}

Modelos de Datos

Objeto Cenote

interface Cenote {
id: string; // Identificador UUID
name: string; // Nombre para mostrar
slug: string; // Identificador amigable para URL
description: string; // Descripción corta
longDescription?: string; // Descripción detallada
location: Location; // Información geográfica
contact?: Contact; // Información de contacto
pricing: Pricing; // Estructura de precios
features: Features; // Características físicas
amenities: Amenity[]; // Instalaciones disponibles
capacity: Capacity; // Límites de visitantes
schedule: Schedule; // Horarios de operación
rating: Rating; // Calificaciones de reseñas
images: Image[]; // Galería de fotos
guidelines?: Guidelines; // Pautas para visitantes
weather?: WeatherInfo; // Información climática
conservation?: Conservation; // Información ambiental
certifications?: Certification[]; // Certificaciones de calidad
metadata: Metadata; // Metadatos del sistema
isActive: boolean; // Estado activo
createdAt: string; // Marca de tiempo de creación
updatedAt: string; // Marca de tiempo de última actualización
}

Objeto Location

interface Location {
latitude: number; // Grados decimales
longitude: number; // Grados decimales
address: string; // Dirección completa
state: string; // Estado/provincia
municipality: string; // Ciudad/municipio
zipCode?: string; // Código postal
directions?: string; // Direcciones de manejo
landmarks?: string[]; // Puntos de referencia cercanos
}

Objeto Pricing

interface Pricing {
adult: number; // Precio para adultos
child: number; // Precio para niños (típicamente 4-12 años)
senior?: number; // Precio para adultos mayores (65+ años)
currency: string; // Código de moneda ISO
includes: string[]; // Lo que está incluido
excludes?: string[]; // Lo que no está incluido
groupDiscounts?: GroupDiscount[]; // Precios de grupo
}

interface GroupDiscount {
minSize: number; // Tamaño mínimo del grupo
discount: number; // Porcentaje de descuento (0-1)
}

Objeto Features

interface Features {
type: "open" | "semi-open" | "cave" | "underground"; // Tipo de cenote
depth: {
min: number; // Profundidad mínima
max: number; // Profundidad máxima
unit: "meters" | "feet"; // Unidad de profundidad
};
temperature: {
avg: number; // Temperatura promedio
unit: "celsius" | "fahrenheit"; // Unidad de temperatura
};
visibility?: {
avg: number; // Visibilidad promedio
unit: "meters" | "feet"; // Unidad de visibilidad
};
difficulty: "beginner" | "intermediate" | "advanced"; // Nivel de dificultad
accessibility: Accessibility; // Características de accesibilidad
}

interface Accessibility {
wheelchairAccessible: boolean; // Accesible en silla de ruedas
stairsToWater?: number; // Número de escalones
platformAvailable: boolean; // Plataforma para entrada
}

Respuestas de Error

Cenote No Encontrado

{
"success": false,
"error": {
"code": "CENOTE_NOT_FOUND",
"message": "El cenote solicitado no fue encontrado",
"status": 404,
"details": {
"cenoteId": "invalid-id"
}
}
}

Parámetros de Ubicación Inválidos

{
"success": false,
"error": {
"code": "INVALID_COORDINATES",
"message": "Coordenadas de latitud o longitud inválidas",
"status": 400,
"details": {
"latitude": "debe estar entre -90 y 90",
"longitude": "debe estar entre -180 y 180"
}
}
}

Verificación de Disponibilidad Fallida

{
"success": false,
"error": {
"code": "AVAILABILITY_CHECK_FAILED",
"message": "No se pudo verificar la disponibilidad para las fechas especificadas",
"status": 422,
"details": {
"dateRange": "La fecha de fin debe ser posterior a la fecha de inicio",
"maxRange": "El rango de fechas no puede exceder 30 días"
}
}
}

Ejemplos de SDK

SDK de TypeScript

import { LosCenotesClient } from "@loscenotes/partner-sdk";

const client = new LosCenotesClient({
apiKey: "sk_test_your_api_key",
environment: "sandbox",
});

// Listar cenotes con filtros
const cenotes = await client.cenotes.list({
isActive: true,
search: "dos ojos",
sortBy: "rating",
sortDirection: "desc",
expand: ["amenities"],
});

// Obtener cenote específico
const cenote = await client.cenotes.get("c3n0t3-1234", {
expand: ["reviews", "nearby"],
});

// Verificar disponibilidad
const availability = await client.cenotes.checkAvailability("c3n0t3-1234", {
startDate: "2024-07-15",
endDate: "2024-07-20",
visitors: 4,
});

// Buscar por ubicación
const nearby = await client.cenotes.searchNearby({
latitude: 20.327423,
longitude: -87.382118,
radius: 25,
limit: 10,
});

SDK de Python

from loscenotes import LosCenotesClient

client = LosCenotesClient(
api_key='sk_test_your_api_key',
environment='sandbox'
)

# Listar cenotes
cenotes = client.cenotes.list(
is_active=True,
search='dos ojos',
sort_by='rating',
sort_direction='desc'
)

# Obtener cenote específico
cenote = client.cenotes.get(
'c3n0t3-1234',
expand=['reviews', 'nearby']
)

# Verificar disponibilidad
availability = client.cenotes.check_availability(
'c3n0t3-1234',
start_date='2024-07-15',
end_date='2024-07-20',
visitors=4
)

SDK de PHP

<?php
use LosCenotes\LosCenotesClient;

$client = new LosCenotesClient([
'apiKey' => 'sk_test_your_api_key',
'environment' => 'sandbox'
]);

// Listar cenotes
$cenotes = $client->cenotes->getList([
'isActive' => true,
'search' => 'dos ojos',
'sortBy' => 'rating',
'sortDirection' => 'desc'
]);

// Obtener cenote específico
$cenote = $client->cenotes->get('c3n0t3-1234', [
'expand' => ['reviews', 'nearby']
]);

// Verificar disponibilidad
$availability = $client->cenotes->checkAvailability('c3n0t3-1234', [
'startDate' => '2024-07-15',
'endDate' => '2024-07-20',
'visitors' => 4
]);
?>

Próximos Pasos