Volver a proyectos
Caso de estudioEn producción

Vame Fútbol

Una tienda de camisetas de fútbol hecha para cómo compran sus clientes: desde el celular, pagando por transferencia o Mercado Pago.

Rol
Fullstack
Año
2026
Stack
  • React 19
  • TypeScript
  • Vite 6
  • React Router 7
  • Supabase
  • Vercel Functions
  • Mercado Pago
Ver la tienda en vivo

Contexto y problema

Vame Fútbol vende camisetas de fútbol retro y actuales. El punto de partida era un único HTML estático con 427 productos escritos a mano en el código.

La migración a React se hizo en 8 PRs encadenados, con un commit base para poder volver atrás en cualquier momento. Después, el catálogo pasó a vivir solo en Supabase, las fotos en Supabase Storage, y el stock empezó a sincronizarse por talle.

Al principio la venta se cerraba por WhatsApp: el carrito armaba un mensaje y el pedido se confirmaba a mano. Después llegó un checkout propio, con transferencia bancaria o Mercado Pago, reserva de stock y precios calculados en el servidor. WhatsApp quedó para lo que hace bien: mandar el comprobante y resolver dudas. En total, 260 commits entre julio y noviembre de 2026.

Arquitectura

El navegador solo lee: el catálogo sale de una vista de la app de inventario, y los pedidos se escriben desde funciones del servidor con la service role.

El inventario lo maneja otra aplicación, kitstock-pro, que es dueña de la vista storefront_products. La tienda la consulta con la anon key, que solo tiene permiso de select sobre esa vista.

Lo que escribe pasa por funciones de Vercel: crear un pedido, consultar su estado, recibir el webhook de Mercado Pago y vencer los impagos. Cada una llama a funciones SQL que validan y reservan stock de forma atómica, y los pedidos aparecen en kitstock-pro para confirmarlos.

Cada vez que el catálogo llega bien, se guarda en localStorage. Si Supabase falla, la tienda muestra esa última copia en lugar de una página vacía. Para el estado no hay librería: alcanzan dos contextos, CartProvider y CatalogFilterProvider.

Cuatro decisiones técnicas

  1. Stock por talle, sin que un agotado corte la venta

    Decisión
    Las columnas stock_s a stock_xxxl se convierten en un stockBySize, y cada producto tiene un stock_mode: inmediato o encargo. Un talle sin stock sigue siendo seleccionable: aparece la nota “se hace por encargo” y el botón pasa a “Realizar encargo”. Al entrar, queda elegido el primer talle con stock.
    Por qué
    Un talle agotado no es una venta perdida, es un encargo. En cambio, el filtro por talle responde otra pregunta, “qué puedo comprar ahora”, y solo muestra stock confirmado mayor a cero. Los productos con stock se ordenan primero con un sort estable, y cuando queda una sola unidad aparece el aviso “Última unidad”.
    Tradeoff
    El mapa por talle se arma solo si todas las columnas traen números. Si falta alguno, todos los talles se tratan como disponibles: prefiero no esconder un producto por un dato incompleto, aunque eso puede terminar en un encargo en vez de una entrega inmediata.
  2. El cliente nunca manda un precio

    Decisión
    El checkout en /checkout manda solo productos, talles, dorsales y datos de envío. api/orders/create, una función de Vercel, recalcula precio, recargo por dorsal, descuento de las Mystery Box, seña del 10% para los encargos y envío (gratis desde 3 prendas), y guarda el pedido con una función SQL atómica, place_storefront_order, que valida el stock y lo reserva en la misma transacción.
    Por qué
    Un precio que llega del navegador se puede editar. Y si dos personas compran el último talle a la vez, solo una transacción puede quedárselo: el stock de un pedido sin pagar queda reservado unas horas, y las unidades que ya no alcanzan pasan a encargo en vez de rechazar el pedido. Las reglas de seña y envío viven en un módulo compartido, así carrito, checkout y API nunca muestran montos distintos.
    Tradeoff
    Más reglas en la base: límite de 50 prendas por pedido, de dos pedidos pendientes por teléfono y un cron diario que vence los impagos. Cada regla nueva pide una migración revisada y su test contra SQL real.
  3. Mercado Pago: el webhook es la fuente de verdad

    Decisión
    Al elegir Mercado Pago, la API crea una preferencia de Checkout Pro por lo que se cobra ahora y el cliente paga en la página de Mercado Pago. El resultado no se toma de la vuelta del navegador: un webhook verifica la firma x-signature, consulta el pago a la API de Mercado Pago (nunca confía en el cuerpo de la notificación) y lo registra con record_storefront_mp_payment.
    Por qué
    La URL de retorno la puede abrir cualquiera; el webhook firmado no. Al volver, la página consulta el estado del pedido unos segundos hasta que llega el webhook y muestra “¡Recibimos tu pago!” o la opción de reintentar. Se excluyen efectivo y cajero para que el pago se resuelva dentro de la ventana de reserva, y las cuotas, hasta 12, llevan el interés de Mercado Pago a cargo del comprador.
    Tradeoff
    Un pago aprobado no cierra solo el pedido: se confirma a mano en kitstock-pro con “Marcar como pagada”, igual que una transferencia. Es un paso manual a propósito, para que caja y encargos se registren en un solo lugar.
  4. Imágenes pensadas para el celular

    Decisión
    Las URLs de Supabase Storage se reescriben de /object/ a /render/image/ con una caja cuadrada, resize=contain y quality=75. El componente KitImage carga en diferido por defecto; con priority pasa a eager con fetchPriority="high", y mientras tanto muestra un skeleton con shimmer. La imagen del hero se precarga en index.html con sustitución de variables de Vite, y las fuentes son propias y precargadas.
    Por qué
    Casi todo el tráfico llega desde el celular. Durante el desarrollo vi fotos de unos 6 MB bajar a menos de 150 KB con la transformación, y un LCP de más de 19 segundos que dejó de aparecer. Son observaciones hechas mientras desarrollaba, no un benchmark auditado.
    Tradeoff
    Las fotos pasan a depender del servicio de transformación de Supabase, y la caja cuadrada con contain fuerza un mismo formato para todas, aunque el original no sea cuadrado.

Problemas difíciles

  • Notificaciones que llegan desordenadas

    Mercado Pago puede avisar un pending después de un approved. Una vez cobrado, un estado anterior se ignora; refunded y charged_back son finales, y un cobro por otro monto queda como approved_amount_mismatch: no cuenta como pagado, pero el pedido nunca vence.

  • Un redirect que se comía los webhooks

    El dominio sin www redirige con un 308, y Mercado Pago no sigue redirects: los avisos se perdían en silencio. Ahora SITE_URL es obligatorio, apunta al host canónico y nunca se toma del request.

  • Dos líneas de la misma camiseta se pisaban

    Cantidad y borrar usaban solo el producto. Cada línea del carrito pasó a identificarse por key|size|dorsalName|dorsalNumber.

  • Supabase no adivina la otra dimensión

    Al transformar una imagen, Supabase no infiere la dimensión que falta. Pedir solo un ancho no alcanzaba: la solución fue una caja cuadrada explícita con resize=contain.

  • Rutas del cliente en Vercel

    En una SPA, el router vive en el navegador. Sin un rewrite hacia la app en Vercel, abrir un link directo a una página interna no encontraba nada que servir.

  • Una anon key que solo puede leer una vista

    Un incidente previo de RLS con la anon key en el mismo proyecto de Supabase dejó una regla: la anon key solo tiene select sobre storefront_products, y lo que escribe usa la service role desde el servidor.

Cómo se testea

599tests

599 tests con Vitest, jsdom y React Testing Library, repartidos en 38 archivos: componentes, reglas de carrito y envío, endpoints de la API y el webhook de Mercado Pago.

Las funciones SQL de los pedidos corren sobre PGlite, un Postgres en memoria: reservar stock, pasar unidades a encargo o registrar un pago se prueban contra SQL real, no contra un mock.

Arriba de eso, Playwright recorre la tienda contra el build de producción, no contra el servidor de desarrollo. Por ahora se ejecuta de forma local; todavía no hay CI.

Resultados

visitantes
5.800+
páginas vistas
19.000
tráfico mobile
97%

Son los números del primer mes. El 97% de tráfico mobile confirma lo que guió el diseño: una tienda que tiene que ser liviana y cómoda en el celular, también a la hora de pagar.

Checkout online y lo que sigue

El checkout empezó en una rama aparte y salió a producción cuando estuvo listo. Hoy la tienda cobra sola: por transferencia, con los datos y botones para copiarlos, o con Mercado Pago, que devuelve al cliente al sitio con el resultado de su pago.

En producción

  • Checkout propio con transferencia bancaria o Mercado Pago
  • Hasta 12 cuotas con tarjeta vía Checkout Pro
  • Reserva de stock mientras el pedido espera el pago
  • Seña del 10% para los talles por encargo
  • Envío por Correo Argentino o moto, con entrega al día hábil siguiente
  • Pedidos impagos que vencen con un cron protegido por CRON_SECRET

Lo que sigue

  • Badge “Pagado por MP” en kitstock-pro
  • Correr los tests en CI

¿Querés verla funcionando?

Vame está en producción. También podés volver a los demás proyectos.