# Sellito

> Pasaportes digitales, sellos QR/NFC y rewards para explorar ciudades de México y Latinoamérica.

Sellito es una app web/PWA (con versión iOS y Android via Capacitor) que conecta viajeros, comercios locales y ciudades a través de pasaportes digitales. Los usuarios acumulan sellos al visitar lugares físicos, completan rutas temáticas, descubren eventos secretos por proximidad GPS y desbloquean rewards en comercios aliados.

El modelo es gratuito para viajeros. Los comercios se registran como partners y pueden ofrecer tarjetas de sellos (tipo loyalty card) con rewards desbloqueables por ciclos de visitas.

## Producto

- [App principal](https://sellito.app/rutas): PWA con mapa, explorador de rutas, pasaporte digital y modo comercio integrado.
- [Explorar rutas](https://sellito.app/explorar/rutas): Catálogo público de todas las rutas activas. Sin login.
- [Explorar lugares](https://sellito.app/explorar/lugares): Directorio y mapa de todos los lugares disponibles. Sin login.
- [Pasaporte gratis](https://sellito.app/pasaporte-gratis): Crea un pasaporte digital con nombre y email. Autenticación por OTP.
- [Tarjetas metálicas](https://sellito.app/tarjetas-metalicas): Tarjetas físicas QR/NFC opcionales que se vinculan al pasaporte digital.
- [Perfil gratis para comercios](https://sellito.app/gratis): Registro de partner/comercio con perfil público, rewards y portal de sellos.

## Cómo funciona

Los viajeros se registran con nombre y email; reciben un código OTP por correo para verificar su cuenta. El pasaporte digital guarda sellos, puntos, historial de rutas y rewards. Las tarjetas físicas metálicas con QR/NFC son opcionales y se vinculan al mismo pasaporte.

Los sellos se obtienen de tres formas:
1. Check-in GPS en lugares físicos (validado por radio en el servidor).
2. Escanear la tarjeta NFC del comercio (el comercio otorga el sello).
3. Escanear el QR dinámico del comercio (rota cada 60 segundos, firmado con HMAC).

Los comercios pueden sellar visitas escaneando el QR del pasaporte del cliente desde su portal. Cada comercio define cuántas visitas desbloquean un reward (sistema de ciclos tipo Starbucks).

## API pública

- `POST /api/auth/request-otp` — Solicita código OTP al email.
- `POST /api/auth/verify-otp` — Verifica OTP y devuelve token Bearer + datos del pasaporte.
- `GET  /api/auth/me` — Sesión activa (requiere token).
- `GET  /api/explore` — Lugares, rutas y pins del mapa público.
- `GET  /api/routes/{route}` — Detalle de ruta con paradas y progreso.
- `POST /api/checkins/place` — Registra check-in GPS en un lugar (requiere token).
- `GET  /api/secret-events/nearby` — Eventos secretos cercanos por lat/lng.
- `POST /api/secret-events/claim` — Reclama un evento secreto (requiere token).
- `GET  /api/hunts/nearby` — Treasure hunts cercanos.
- `GET  /api/hunts/{hunt}` — Estado y pistas de un treasure hunt (requiere token).
- `POST /api/hunt-clues/{clue}/attempt` — Intenta resolver una pista (requiere token).
- `POST /api/stamps/nfc` — Registra sello NFC de comercio (requiere token).
- `POST /api/stamps/dynamic-qr` — Valida y registra sello QR dinámico de comercio.
- `POST /api/partners/register` — Registra un nuevo comercio/partner.
- `GET  /api/partners/{partner}/dynamic-qr` — QR dinámico firmado del comercio.

## Páginas públicas indexables

- [/](https://sellito.app/) — Landing principal.
- [/explorar/rutas](https://sellito.app/explorar/rutas) — Listado de rutas.
- [/explorar/lugares](https://sellito.app/explorar/lugares) — Mapa y directorio de lugares.
- [/explorar/lugares/{slug}](https://sellito.app/explorar/lugares/) — Ficha de lugar.
- [/rutas/{slug}](https://sellito.app/rutas/) — Detalle de ruta con paradas.
- [/u/{publicKey}](https://sellito.app/u/) — Vitrina pública de pasaporte.
- [/comercios/{slug}](https://sellito.app/comercios/) — Perfil público de comercio aliado con horarios, reward, sellos y rutas donde aparece.
- [/privacidad](https://sellito.app/privacidad) — Aviso de privacidad.

## Stack técnico

- Backend: Laravel 13 + PHP 8.3.
- Admin: Filament 5.
- Base de datos: MySQL/MariaDB en producción (SQLite en desarrollo).
- Frontend: Vite + Tailwind CSS 4, Vanilla JS.
- Mapas: Leaflet + OpenStreetMap (sin API keys externas).
- App móvil: Capacitor (iOS + Android, mismo bundle).
- QR: generación local en servidor (sin APIs externas).
- Auth: OTP por email + sesiones Bearer.
- Antifraude: validación GPS por radio, cooldown por usuario/comercio, auditoría de eventos de fraude.

## Contexto geográfico

Opera principalmente en México (Guadalajara, Ciudad de México, Oaxaca, San Cristóbal de las Casas y más de 50 ciudades) con contenido en ciudades de Latinoamérica (Buenos Aires, Lima, Cusco, Río de Janeiro, Ciudad de Panamá, entre otras).

## Contacto

- Sitio: https://sellito.app
- Email: hola@sellito.app
- Aviso de privacidad: https://sellito.app/privacidad