Skip to main content

API Reference Overview

Complete reference documentation for the LosCenotes Partner API.

Base URL​

Única URL para todos los ambientes:

https://service-gateway.loscenotes.com
EnvironmentAPI Key PrefixDescripción
Sandboxsk_test_Datos de prueba, sin cargos reales
Productionpk_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.

Authentication​

All API requests must include your API key in the X-API-Key header:

X-API-Key: sk_live_your_api_key

For sandbox environment:

X-API-Key: sk_test_your_api_key

Request Format​

The API accepts JSON-formatted requests with the Content-Type: application/json header.

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

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

Response Format​

All API responses follow a consistent structure:

{
  "success": true,
  "message": "operation.success",
  "data": { /* response data */ },
  "pagination": { /* pagination info for list endpoints */ },
  "currency": { /* currency info for pricing endpoints */ }
}

Success Response Fields​

FieldTypeDescription
successbooleanAlways true for successful responses
messagestringi18n message key (e.g., 'cenote.list_retrieved_successfully')
dataobject/arrayThe main response data
paginationobjectPagination info (list endpoints only)
currencyobjectCurrency exchange info (pricing endpoints only)

Error Response Format​

{
  "success": false,
  "message": "validation.required_field",
  "error": "Bad Request",
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-20T10:30:00.000Z",
  "path": "/api/partner/cenotes",
  "errors": {
    "messages": ["Name is required", "Email must be valid"],
    "fields": {
      "email": ["Invalid email format"],
      "name": ["Field is required"]
    }
  }
}

Pagination​

List endpoints use offset-based pagination:

Pagination Request​

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

Pagination Response​

Response includes pagination metadata with EXACTLY these fields:

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

Pagination Fields​

FieldTypeDescription
totalnumberTotal number of items
perPagenumberItems per page
currentPagenumberCurrent page number
lastPagenumberLast page number

Note: The API does NOT include hasNextPage, hasPreviousPage, nextCursor, prevCursor, or any other pagination fields. Only the 4 fields shown above.

Pagination Parameters​

ParameterTypeDefaultMaxDescription
pageinteger1-Page number
perPageinteger15100Number of items per page

Filtering and Sorting​

Common Filter Parameters​

Most list endpoints support these common filters:

ParameterTypeDescriptionExample
isActivebooleanFilter by active status?isActive=true
searchstringText search across searchable fields?search=dos ojos
createdAfterstringFilter by creation date (ISO 8601)?createdAfter=2024-01-01T00:00:00Z
createdBeforestringFilter by creation date (ISO 8601)?createdBefore=2024-12-31T23:59:59Z

Sorting​

Use the sortBy and sortDirection parameters:

GET /api/partner/cenotes?sortBy=name&sortDirection=asc
ParameterTypeValuesDefaultDescription
sortBystringVaries by endpointcreatedAtField to sort by
sortDirectionstringasc, descdescSort direction

Field Selection​

Optimize responses by requesting only needed fields:

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

Response will only include the specified fields:

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

Expansion​

Include related resources in responses:

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

Response includes expanded resources:

{
  "success": true,
  "data": {
    "id": "res_1234",
    "status": "confirmed",
    "cenote": {
      "id": "c3n0t3-1234",
      "name": "Cenote Dos Ojos",
      "location": { /* ... */ }
    },
    "guest": {
      "id": "guest_5678",
      "name": "John Smith",
      "email": "john@example.com"
    }
  }
}

Localization​

The API supports multiple languages via the Accept-Language header:

Accept-Language: es-MX

Supported languages:

CodeLanguageRegion
enEnglishDefault
esSpanishGlobal
es-MXSpanishMexico

Response messages and some data fields will be localized:

{
  "success": true,
  "message": "cenotes.list_retrieved_successfully",
  "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"
        }
      ]
    }
  ]
}

Rate Limiting​

API responses include rate limiting headers:

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

See Rate Limits for detailed information.

Sandbox Mode​

Sandbox responses include a _sandbox field:

{
  "success": true,
  "message": "cenotes.list_retrieved_successfully",
  "data": [ /* test data */ ],
  "_sandbox": true
}

API Endpoints​

Core Resources​

Cenotes​

Manage cenote information and availability.

  • GET /api/partner/cenotes - List available cenotes
  • GET /api/partner/availability/{cenoteId} - Check cenote availability

Reservations​

Manage cenote reservations and bookings.

  • GET /api/partner/reservations - List partner reservations
  • POST /api/partner/reservations - Create new reservation
  • GET /api/partner/reservations/{id} - Get reservation details
  • POST /api/partner/reservations/{id}/cancel - Cancel reservation

Utility Endpoints​

Authentication​

  • GET /api/auth/verify - Verify API key
  • POST /api/auth/refresh - Refresh authentication

System​

  • GET /api/system/health - System health check
  • GET /api/system/status - Service status

Geography​

  • GET /api/locations/states - List states
  • GET /api/locations/municipalities - List municipalities

Pricing​

  • POST /api/pricing/calculate - Calculate pricing
  • GET /api/currencies - Get currency information

Configuration Endpoints​

Common Patterns​

Bulk Operations​

Some endpoints support bulk operations:

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
    }
  ]
}

Conditional Requests​

Use ETags for conditional requests:

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

Partial Updates​

Use PATCH for partial resource updates:

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

{
  "visitors": 6,
  "specialRequests": "Vegetarian lunch required"
}

Error Handling​

The API uses standard HTTP status codes and provides detailed error information:

Status CodeDescription
200OK - Request successful
201Created - Resource created
204No Content - Success with no response body
400Bad Request - Invalid request
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource not found
409Conflict - Resource conflict
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error
503Service Unavailable - Service temporarily unavailable

See Error Handling for detailed error information.

Getting Help​

API Changelog​

Track API changes and updates:

Next Steps​