Nvito Docs

1. Journey del Invitado

El invitado atraviesa múltiples etapas desde que recibe la invitación hasta después del evento.

2. Canales de Contacto

Nvito contacta a los invitados a traves de múltiples canales, priorizados por la configuración del organizador:

Canal	Servicio	Cuando se usa	Prerequisito
Email	Nodemailer (SMTP)	Invitación, confirmación, recordatorios	Email del invitado registrado
WhatsApp	Twilio Business API	Invitación, recordatorios, RSVP conversacional	Telefono del invitado registrado
SMS	Twilio SMS	Fallback cuando WhatsApp no disponible	Telefono del invitado registrado
Push	Firebase/Expo Push	Recordatorios, actualizaciones en tiempo real	App movil instalada con token registrado
Link directo	URL pública	Compartido manualmente por el organizador	Ninguno

2.1 Smart Routing

El sistema de comunicaciones incluye Smart Routing que selecciona automáticamente el mejor canal:

Si el invitado tiene WhatsApp verificado y el organizador tiene crédito → WhatsApp
Si tiene email → Email
Si tiene teléfono sin WhatsApp → SMS
Si tiene app instalada → Push notification como complemento

3. Visualización de la Invitación

Cuando el invitado abre el link de la invitación (https://nvito.mx/i/{slug} o https://nvito.mx/i/{slug}?t={shortCode}):

nvito-invitations (Next.js ISR) sirve la página estática
Si la URL incluye ?t={shortCode}, el JavaScript resuelve los datos del invitado via GET /invitations/public/guest/{shortCode}
Se muestra la pantalla de carga (loader) con el nombre personalizado del invitado (ej: "Bienvenido, Ing. Juan") o un texto generico si no hay shortCode
Se renderiza el HTML de la invitación con transiciones entre secciones
La sección RSVP muestra un saludo personalizado si hay shortCode (ej: "Ing. Juan, confirma tu asistencia")
El script de analiticas registra la visita (VIEW event)
Si es invitación interna, las secciones se navegan con transiciones fullpage
Si es invitación externa, se renderiza el HTML tal cual fue subido
Un botón flotante "Agendar" permite al invitado agregar el evento a su calendario

3.1 Tracking de Analiticas

Cada interacción del invitado se registra:

Evento	Cuando	Datos
`VIEW`	Al abrir la invitación	slug, userAgent, referrer, timestamp
`SECTION_VIEW`	Al navegar a una sección	sectionType, viewDuration
`RSVP_START`	Al iniciar el formulario RSVP	timestamp
`RSVP_COMPLETE`	Al enviar la respuesta	response, attendeesCount
`LINK_CLICK`	Al hacer clic en un enlace	linkType (map, gift, accommodation)

4. Flujo de RSVP

El RSVP (Repondez S'il Vous Plait) es el momento central de la interacción del invitado.

4.1 Diagrama de Flujo

Flujo de RSVP

Invitado

nvito-invitations

nvito-api

RsvpService

PostgreSQL

WorkflowEngine

Bull Queue

Abre invitacion (/i/slug)

Renderiza invitacion con seccion RSVP

Completa formulario RSVP

Selecciona asistentes, info dietetica, mensaje

POST /rsvp/public

Payload: slug, guestToken, response, attendees, message

respond(rsvpData)

Validar guestToken (identifica al invitado)

Validar attendeesCount no excede groupSize

alt[RSVP ya existe para (guest, invitation)]

Actualizar respuesta existente

else[Primer RSVP]

Crear nueva respuesta

Actualizar estado del invitado

PENDING -> CONFIRMED o DECLINED

Emitir RsvpRespondedEvent

alt[response === CONFIRMED]

Trigger RSVP_CONFIRMED

Encolar confirmacion (email/WhatsApp)

else[response === DECLINED]

Trigger RSVP_DECLINED

Encolar agradecimiento por responder

200 OK (respuesta registrada)

Muestra confirmacion visual

Invitado

nvito-invitations

nvito-api

RsvpService

PostgreSQL

WorkflowEngine

Bull Queue

4.2 Campos del RSVP

Campo	Tipo	Requerido	Descripción
`response`	`CONFIRMED` / `DECLINED`	Si	Respuestá del invitado
`attendeesCount`	number	Si (si CONFIRMED)	Numero de asistentes (incluye al invitado)
`attendeeNames`	string[]	No	Nombres de los acompanantes
`dietaryRestrictions`	string	No	Restricciones alimentarias
`message`	string	No	Mensaje para los anfitriones
`needsTransportation`	boolean	No	Si necesita transporte
`accommodationPreference`	string	No	Preferencia de hospedaje

4.3 Reglas de Negocio

Regla	Descripción
Un RSVP por par (guest, invitation)	Un invitado solo puede tener una respuesta por invitación
Actualizable	El invitado puede cambiar su respuesta múltiples veces antes del cierre
attendeesCount no excede groupSize	No puede confirmar más asistentes que el tamano de su grupo
groupSize	Definido por el organizador al crear el invitado (default: 1)
Invitación cerrada	No se aceptan respuestas si la invitación está en estado CLOSED

5. Estados del Invitado

Cada invitado tiene un estado que refleja su progreso en el flujo:

Estados del Invitado

PENDING

Agregado, sin respuesta

CONFIRMED

RSVP confirmado

DECLINED

RSVP rechazado

ATTENDED

Check-in exitoso

pending→confirmedRSVP confirmado

pending→declinedRSVP rechazado

confirmed→declinedCambia respuesta

declined→confirmedCambia respuesta

confirmed→attendedCheck-in exitoso

Estado	Descripción	Puede cambiar?
PENDING	Invitado agregado pero no ha respondido RSVP	Si (via RSVP)
CONFIRMED	El invitado confirmo asistencia	Si (puede cambiar a DECLINED antes del cierre)
DECLINED	El invitado rechazo la invitación	Si (puede cambiar a CONFIRMED antes del cierre)
ATTENDED	El invitado hizo check-in en el evento	No (estado final)

6. Check-in

El check-in se realiza el día del evento, cuando el invitado llega al venue.

6.1 Metodos de Check-in

Metodo	Descripción	Actor
QR Code	El host escanea el QR del invitado con la app movil	Host (via nvito-client o nvito-pwa)
Búsqueda manual	El host busca al invitado por nombre en la lista	Host (via nvito-client o nvito-pwa)
Auto check-in	El invitado escanea un QR del venue (si habilitado)	Invitado

6.2 Flujo de Check-in

Flujo de Check-in

Anfitrion

Invitado

nvito-client / nvito-pwa

nvito-api

PostgreSQL

Llega al venue

Abre scanner QR

alt[Check-in con QR]

Escanea QR del invitado

POST /mobile/events/:eventId/check-in (guestId)

else[Check-in manual]

Busca invitado por nombre

Selecciona de la lista

POST /mobile/events/:eventId/check-in (guestId)

Validar que el invitado pertenece al evento

Validar estado CONFIRMED

Actualizar estado a ATTENDED

Registrar checkedInAt, checkedInBy

200 OK (check-in exitoso)

Muestra confirmacion con datos del invitado

Actualiza contador en tiempo real

Si offline, encola y sincroniza despues

Anfitrion

Invitado

nvito-client / nvito-pwa

nvito-api

PostgreSQL

6.3 Check-in Offline

Para eventos en lugares con mala conectividad:

Los QR passes se pre-cargan en cache (staleTime: 10min, gcTime: 7 dias)
El check-in se registra localmente en la cola offline (AsyncStorage / IndexedDB)
Al recuperar conexión, useOfflineSync sincroniza automáticamente con el servidor
Se resuelven conflictos por timestamp (último check-in gana)

7. Acceso del Invitado a la App Movil

Los invitados pueden acceder a funcionalidades adicionales via la app movil o PWA:

7.1 Acceso via Deep Link

nvito://guest?token={accessToken}

El organizador comparte un link/QR con deep link
El invitado abre el link en su dispositivo
Si tiene la app: abre directamente con loginAsGuest(accessToken)
Si no tiene la app: redirige a la PWA o app store

7.2 Funcionalidades para Invitados

Funcionalidad	Pantalla	Descripción
Home	`home`	Vista general del evento con countdown
Itinerario	`itinerary-guest`	Programa del evento
Galería	`gallery-guest`	Fotos compartidas del evento
Interacción	`interact`	Mensajes, audio guestbook, encuestás
Mesa de regalos	`gift-registry-guest`	Ver y contribuir a la mesa de regalos
Compartir	`sharing-guest`	Compartir fotos y momentos
Hospedaje	`accommodation`	Opciones de hospedaje cercanas

8. Post-evento

Después del evento, el invitado puede seguir interactuando:

Acción	Canal	Trigger
Recibe agradecimiento	Email/WhatsApp	Workflow `POST_EVENT` (automático)
Ve galería compartida	App movil / PWA	Acceso persistente por 30 días
Deja mensaje en audio guestbook	App movil / PWA	Disponible durante y post-evento
Descarga fotos	App movil / PWA	Fotos del evento en alta resolución

9. Modelo de Datos del Invitado

Campo	Tipo	Descripción
`id`	UUID	Identificador único
`eventId`	UUID	Evento al que pertenece
`firstName`	string	Nombre
`lastName`	string	Apellido
`email`	string?	Email (opcional)
`phone`	string?	Telefono (opcional)
`groupSize`	number	Tamano del grupo (default: 1)
`status`	enum	PENDING, CONFIRMED, DECLINED, ATTENDED
`groupId`	UUID?	Grupo de invitados (familia, mesa)
`tableId`	UUID?	Mesa asignada
`accessToken`	string	Token único para acceso via deep link
`checkedInAt`	DateTime?	Timestamp del check-in
`checkedInBy`	UUID?	Quien realizo el check-in
`rsvpRespondedAt`	DateTime?	Timestamp de la última respuesta RSVP

10. Archivos Clave

Archivo	Ubicación	Responsabilidad
`rsvp.service.ts`	`src/modules/rsvp/`	Lógica de respuesta RSVP pública
`rsvp.controller.ts`	`src/modules/rsvp/`	Endpoints públicos de RSVP
`guests.service.ts`	`src/modules/guests/`	CRUD de invitados, estados, check-in
`guests.controller.ts`	`src/modules/guests/`	Endpoints REST de invitados
`guest-import.service.ts`	`src/modules/guests/services/`	Importacion masiva de invitados via Excel
`check-in.service.ts`	`src/modules/guests/services/`	Lógica de check-in (QR + manual + offline)

11. Relación con Otros Flujos

Flujo relacionado	Relación
Ciclo de Vida de la Invitación	El invitado solo puede ver/responder invitaciones PUBLISHED
Ciclo de Vida del Evento	El check-in solo funciona para eventos ACTIVE
Flujo de Comunicaciones	Los triggers RSVP_CONFIRMED y RSVP_DECLINED disparan workflows
Flujo de Pagos	El invitado puede contribuir a la mesa de regalos via PaymentLink