Backend Integration — Workflow para ruta-araucaria

🔴 Admin (requieren JWT authAdmin)

Estado actual de integración

✅ Ya integrados en ruta-araucaria

❌ Pendientes de integrar

• Envío de reserva (/enviar-reserva-express)
• Retorno de pago desde Flow (/api/payment-status polling)
• Retorno de pago desde MercadoPago
• Destinos dinámicos desde DB (/api/destinos)
• Validación de código de descuento (/api/codigos/:codigo)
• Búsqueda de reserva por código

Procedimiento estándar de integración

1. Identificar qué falta

Leer src/components/BookingForm.tsx, src/hooks/useCotizacion.ts y src/lib/backend.ts para entender qué ya existe.

2. Nunca hardcodear la URL

// ✅ Correcto
const resp = await fetch(`${getBackendUrl()}/endpoint`, { ... });

// ❌ Incorrecto
const resp = await fetch("https://transportes-araucaria.onrender.com/endpoint");

3. Patrón de llamada a la API

// Patrón básico con AbortController y manejo de errores
const controller = new AbortController();
try {
  const resp = await fetch(`${getBackendUrl()}/api/endpoint`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const data = await resp.json();
  // usar data
} catch (err) {
  if (err instanceof Error && err.name === "AbortError") return;
  // manejar error real
}

4. Patrón de hook personalizado

Sigue el modelo de useCotizacion.ts:

• Estado: useState para resultado, cargando, error
• Debounce con useRef<ReturnType<typeof setTimeout>>
• Cancelación con AbortController
• Limpieza en useEffect return

Flujo de reserva express

BookingForm (paso 0: ruta) → paso 1: datos personales + pasarela
  ↓
POST /enviar-reserva-express
  Body: { nombre, email, telefono, origen, destino, fecha, hora,
          pasajeros, idaVuelta, fechaRegreso, horaRegreso, upgradeVan,
          precio, totalConDescuento, abono, saldoPendiente,
          descuentoBase, descuentoRoundTrip, descuentoOnline,
          source: "web", estadoPago: "pendiente" }
  Response: { success, reservaId, codigoReserva }
  ↓
POST /create-payment
  Body: { gateway: "flow"|"mercadopago", amount, description,
          email, reservaId, codigoReserva, tipoPago: "total"|"abono",
          paymentOrigin: "reserva_express" }
  Response: { url }  ← redirigir al usuario

Flujo de pago Flow

Usuario → create-payment → Flow checkout
  ↓ (Flow redirige por POST)
Backend /api/payment-result → redirige a frontend /flow-return?token=...&status=...&amount=...
  ↓
Frontend polling: GET /api/payment-status?token=TOKEN o ?reserva_id=ID
  Response: { pagado: bool, status: "pagado"|"pendiente"|"rechazado", monto }

En ruta-araucaria: escuchar el retorno

// Al regresar desde Flow (detectar query params en la URL)
const params = new URLSearchParams(window.location.search);
const flowToken = params.get("token");
const flowStatus = params.get("status");
const amount = params.get("amount");
const reservaId = params.get("reserva_id");

if (flowToken && flowStatus === "success") {
  // Mostrar resumen del pago exitoso
} else if (flowStatus === "pending") {
  // Hacer polling a /api/payment-status
}

Flujo de pago MercadoPago

Usuario → /api/create-payment-mp → MP Checkout Pro init_point
  ↓ (MP redirige por GET)
Frontend /mp-return?status=success|pending|error&amount=...&reserva_id=...
  ↓
Webhook automático: POST /api/mp-confirmation (server-to-server, no requiere acción frontend)

Validar código de descuento

// GET /api/codigos/:codigo → valida si el código es aplicable
const resp = await fetch(`${getBackendUrl()}/api/codigos/${encodeURIComponent(codigo)}`);
const data = await resp.json();
// data: { descuento, tipo, descripcion, activo, limiteUsos, usosActuales, ... }

// Para incluir el descuento en la cotización, pasarlo a useCotizacion:
useCotizacion({ ..., codigoDescuento: codigo })

Destinos dinámicos desde DB

// GET /api/destinos?activos=true
const resp = await fetch(`${getBackendUrl()}/api/destinos?activos=true`);
const { destinos } = await resp.json();
// Cada destino: { id, nombre, precioIda, precioVuelta, precioIdaVuelta, activo, orden }

// IMPORTANTE: los destinos en src/data/destinos.ts son la fuente estática de verdad
// para minHorasAnticipacion, duracionIdaMinutos, maxPasajeros.
// Fusionar con los datos dinámicos de precios del backend.

Cuerpo de /api/cotizar

{
  origen: string,          // requerido
  destino: string,         // requerido
  pasajeros: number,       // requerido, 1-10
  fecha: string,           // requerido, YYYY-MM-DD
  hora?: string,           // HH:MM
  idaVuelta?: boolean,
  fechaRegreso?: string,   // requerido si idaVuelta=true
  horaRegreso?: string,
  upgradeVan?: boolean,
  codigoDescuento?: string,
  sillaInfantil?: boolean,
  cantidadSillas?: number,
}
// Respuesta: { precioBase, totalNormal, totalConDescuento, abono,
//             saldoPendiente, vehiculo, descuentos: { online, idaVuelta, total } }

Seguridad: checklist antes de integrar un endpoint

• Nunca enviar datos de tarjeta al frontend; la URL de pago la devuelve el backend
• Validar formato de email antes de enviar (regex ^[^\s@]+@[^\s@]+\.[^\s@]+$)
• Sanitizar inputs de texto (trim, eliminar caracteres peligrosos)
• No exponer tokens JWT en localStorage si hay datos sensibles; usar httpOnly cookies cuando sea posible
• Usar AbortController para cancelar fetches al desmontar componentes
• Verificar resp.ok antes de parsear JSON
• El monto de pago debe venir siempre del backend (cotización), nunca calcularse solo en el frontend

Errores comunes y soluciones

Verificación final

Después de integrar un endpoint, verificar:

• El componente no crashea si el backend no responde (timeouts de Render.com por cold start ~30s)
• El estado de cargando está reflejado en la UI (spinner o disabled button)
• Los errores del backend se muestran al usuario con mensajes legibles en español
• No hay fetch sin cleanup (AbortController o clearTimeout en el return del useEffect)
• TypeScript sin errores: npx tsc --noEmit