Integraciones: email, WhatsApp y APIs externas

1.1. Anatomía de una llamada a API externa

Ya consumiste APIs sin notarlo: Supabase y Wompi lo son. El patrón general de cualquier integración desde el servidor:

// El esqueleto de TODA integración externa
async function llamarApiExterna() {
  const respuesta = await fetch("https://api.servicio.com/v1/recurso", {
    method: "POST",
    headers: {
      // 1. Autenticación: la API key SIEMPRE desde variables de entorno
      Authorization: `Bearer ${process.env.SERVICIO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ dato: "valor" }),
  });

  // 2. Manejo de errores: las APIs externas FALLAN — planéalo
  if (!respuesta.ok) {
    const error = await respuesta.text();
    console.error(`API servicio falló (${respuesta.status}):`, error);
    return null; // el negocio decide qué hacer con el fallo
  }

  return respuesta.json();
}

Un email transaccional responde a una acción del usuario: confirmación de cita, recibo de pago, recuperación de clave. Se envía con servicios especializados (Resend, SendGrid, Brevo) — nunca desde tu Gmail personal, que no está hecho para eso y termina en spam.

2.1. Configurar Resend

1. Crea la cuenta y la API key

   En resend.com el plan gratuito da 100 emails/día — suficiente para la barbería. Copia la API key a .env.local como RESEND_API_KEY.

2. Instala el SDK

   npm install resend

3. Verifica tu dominio (en producción)

   Para enviar desde citas@donbarbas.co agregarás 3 registros DNS (SPF, DKIM) en el módulo 6. Mientras tanto, Resend te presta un remitente de pruebas.

2.2. El email de confirmación de cita

// lib/notificaciones/email.ts
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

interface DatosConfirmacion {
  para: string;
  nombreCliente: string;
  servicio: string;
  barbero: string;
  fecha: string;   // ya formateada: "jueves 9 de julio, 3:00 pm"
}

export async function enviarConfirmacionCita(datos: DatosConfirmacion) {
  try {
    await resend.emails.send({
      from: "Don Barbas <citas@donbarbas.co>",
      to: datos.para,
      subject: `✂️ Cita confirmada: ${datos.servicio} — ${datos.fecha}`,
      html: `
        <div style="font-family: sans-serif; max-width: 480px; margin: 0 auto;">
          <h2>¡Listo, ${datos.nombreCliente}!</h2>
          <p>Tu cita en <strong>Don Barbas</strong> quedó confirmada:</p>
          <ul>
            <li><strong>Servicio:</strong> ${datos.servicio}</li>
            <li><strong>Barbero:</strong> ${datos.barbero}</li>
            <li><strong>Fecha:</strong> ${datos.fecha}</li>
            <li><strong>Dirección:</strong> Cra 35 #8A-15, Medellín</li>
          </ul>
          <p>Si no puedes asistir, cancela con 2 horas de anticipación
          para conservar tu anticipo.</p>
        </div>
      `,
    });
    return { ok: true };
  } catch (error) {
    // La cita NO se cae porque el email falle
    console.error("Fallo envío de confirmación:", error);
    return { ok: false };
  }
}

¿Y dónde se llama? En el webhook del módulo 4, justo después de confirmar la cita — el momento en que el negocio sabe que el pago es real:

// app/api/webhooks/wompi/route.ts (fragmento nuevo)
if (nuevoEstado === "APROBADO") {
  await supabaseAdmin.from("citas")
    .update({ estado: "confirmada" })
    .eq("id", pago.cita_id);

  // Integración: confirmar por email (sin bloquear la respuesta del webhook)
  const { data: detalle } = await supabaseAdmin
    .from("citas")
    .select("inicia_en, perfiles(nombre), servicios(nombre), barberos(nombre)")
    .eq("id", pago.cita_id)
    .single();

  if (detalle) {
    enviarConfirmacionCita({ /* ...mapear campos... */ }).catch(console.error);
  }
}

En Latinoamérica el email se ignora, pero WhatsApp se lee en minutos. La WhatsApp Business Platform (Cloud API de Meta) permite enviar mensajes desde código. Tiene reglas propias:

3.1. Enviar el recordatorio de cita

// lib/notificaciones/whatsapp.ts
// WhatsApp Cloud API de Meta — plantilla "recordatorio_cita" ya aprobada

export async function enviarRecordatorioWhatsApp(
  celular: string,      // formato internacional sin +: "573001234567"
  nombre: string,
  fecha: string,
  barbero: string
) {
  const url = `https://graph.facebook.com/v20.0/${process.env.WHATSAPP_PHONE_ID}/messages`;

  const respuesta = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      to: celular,
      type: "template",
      template: {
        name: "recordatorio_cita",       // plantilla aprobada en Meta
        language: { code: "es_CO" },
        components: [{
          type: "body",
          // Variables {{1}}, {{2}}, {{3}} de la plantilla
          parameters: [
            { type: "text", text: nombre },
            { type: "text", text: fecha },
            { type: "text", text: barbero },
          ],
        }],
      },
    }),
  });

  if (!respuesta.ok) {
    console.error("WhatsApp falló:", await respuesta.text());
    return { ok: false };
  }
  return { ok: true };
}

Dos reglas de negocio de ReservaYa no las dispara ningún usuario — las dispara el reloj:

• Recordatorio: 24 horas antes de cada cita confirmada, enviar WhatsApp.
• Liberación: las citas en pendiente_pago con más de 15 minutos se cancelan y el horario vuelve a estar disponible.

Para esto existen los cron jobs: tareas que corren en un horario fijo. En Vercel se declaran en vercel.json y llaman a una ruta de tu app:

// vercel.json — en la raíz del proyecto
{
  "crons": [
    { "path": "/api/cron/recordatorios", "schedule": "0 * * * *" },
    { "path": "/api/cron/liberar-citas", "schedule": "*/15 * * * *" }
  ]
}

// app/api/cron/recordatorios/route.ts
import { NextResponse } from "next/server";
import { createClient } from "@supabase/supabase-js";
import { enviarRecordatorioWhatsApp } from "@/lib/notificaciones/whatsapp";

const supabaseAdmin = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

export async function GET(request: Request) {
  // Solo Vercel Cron puede invocar esta ruta
  if (request.headers.get("authorization") !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: "no autorizado" }, { status: 401 });
  }

  // Citas confirmadas que empiezan entre 23 y 25 horas desde ahora
  // y que aún no tienen recordatorio enviado
  const en23h = new Date(Date.now() + 23 * 3600_000).toISOString();
  const en25h = new Date(Date.now() + 25 * 3600_000).toISOString();

  const { data: citas } = await supabaseAdmin
    .from("citas")
    .select("id, inicia_en, perfiles(nombre, telefono), barberos(nombre)")
    .eq("estado", "confirmada")
    .is("recordatorio_enviado_en", null)
    .gte("inicia_en", en23h)
    .lte("inicia_en", en25h);

  for (const cita of citas ?? []) {
    const perfil = cita.perfiles as any;
    if (!perfil?.telefono) continue;

    const { ok } = await enviarRecordatorioWhatsApp(
      `57${perfil.telefono}`,
      perfil.nombre,
      new Date(cita.inicia_en).toLocaleString("es-CO"),
      (cita.barberos as any)?.nombre ?? "tu barbero"
    );

    // Marcamos el envío: idempotencia también en los crons
    if (ok) {
      await supabaseAdmin.from("citas")
        .update({ recordatorio_enviado_en: new Date().toISOString() })
        .eq("id", cita.id);
    }
  }

  return NextResponse.json({ procesadas: citas?.length ?? 0 });
}

4.1. Mini-proyecto del módulo