Descuentos y Cupones

Guía completa para la aplicación de descuentos automáticos y validación de cupones.

---

Vista General

El sistema de precios soporta dos tipos de descuentos:

1. Descuentos Automáticos: Aplicados según reglas (ej. temporada baja, residente local).
2. Cupones: Códigos ingresados por el usuario (ej. VERANO2025).

---

Descuentos Automáticos

POST /public/discount-rules/auto-apply

Obtener los descuentos automáticos aplicables para una solicitud dada.

curl -X POST "https://service-gateway.loscenotes.com/public/discount-rules/auto-apply" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_your_api_key" \
  -d '{
    "cenoteId": "cenote-uuid",
    "date": "2025-06-15",
    "totalPeople": 4,
    "residency": "quintana_roo"
  }'

Campos de Solicitud:

Campo	Tipo	Requerido	Descripción
cenoteId	UUID	✅	ID del cenote
date	string	✅	Fecha de visita (YYYY-MM-DD)
totalPeople	integer	✅	Total de visitantes
residency	string	❌	Residencia (quintana_roo, mexico, foreign)

Respuesta:

{
  "success": true,
  "message": "discounts.auto_applied_successfully",
  "data": {
    "appliedDiscounts": [
      {
        "id": "desc-local",
        "name": "Descuento Local",
        "type": "percentage",
        "value": 20,
        "amount": 7000,
        "description": "20% de descuento para residentes de Quintana Roo"
      },
      {
         "id": "desc-group",
         "name": "Descuento de Grupo",
         "type": "percentage",
         "value": 10,
         "amount": 3500,
         "description": "10% de descuento para grupos de 4 o más"
      }
    ],
    "totalDiscountAmount": 10500,
    "currency": "MXN"
  }
}

---

Validación de Cupones

POST /coupons/validate

Validar un código de cupón y obtener su valor de descuento.

curl -X POST "https://service-gateway.loscenotes.com/coupons/validate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_your_api_key" \
  -d '{
    "code": "VERANO2025",
    "cenoteId": "cenote-uuid",
    "subtotal": 140000
  }'

Respuesta:

{
  "success": true,
  "message": "coupon.valid",
  "data": {
    "isValid": true,
    "code": "VERANO2025",
    "discountType": "percentage",
    "discountValue": 15,
    "discountAmount": 21000,
    "finalPrice": 119000,
    "currency": "MXN",
    "description": "15% de descuento especial de verano"
  }
}

POST /coupons/check

Verificar solo si un cupón existe y está activo (sin calcular montos).

curl -X POST "https://service-gateway.loscenotes.com/coupons/check" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "TEST-CODE"
  }'

---

Tipos de Descuento

Tipo	Descripción	Ejemplo
percentage	Porcentaje del subtotal	10% off
fixed_amount	Monto fijo descontado	$100 MXN off
free_service	Servicio gratuito incluido	Equipo de snorkel gratis

---

Errores de Cupón

Código	Mensaje	Descripción
COUPON_NOT_FOUND	error.coupon.not_found	El cupón no existe
COUPON_EXPIRED	error.coupon.expired	El cupón ha expirado
COUPON_usage_LIMIT_REACHED	error.coupon.limit_reached	Límite de uso alcanzado
COUPON_MIN_SPEND_NOT_MET	error.coupon.min_spend	Mínimo de compra no alcanzado
COUPON_NOT_APPLICABLE	error.coupon.not_applicable	No aplicable a este cenote/fecha

Ejemplo de Error:

{
  "success": false,
  "error": {
    "code": "COUPON_EXPIRED",
    "message": "El cupón ha expirado",
    "details": {
      "expiresAt": "2024-12-31T23:59:59Z"
    }
  }
}