Documentación
Manual operativo
de Kalok.
Guía completa para organizadores: panel, creación de eventos, gestión de tickets, promo codes, check-in, reembolsos, analytics. Si sos asistente, mejor visitá el Centro de ayuda.
Índice
01
El panel de organizador
Después del onboarding accedés a dashboard.kalokpass.com con tu cuenta de Kalok. El sidebar tiene 5 áreas principales:
Eventos
Lista de todos tus eventos (publicados, borradores, finalizados). Click en cualquiera para ver su dashboard interno con tabs: Settings, Tickets, Promo codes, Guest list, Check-in, Analytics.
Recintos
Lista de venues que creaste o tenés acceso. Cada uno con su info de capacidad, secciones, dirección. Podés crear venues nuevos para tus próximos eventos.
Tickets
Vista cross-event de todos los tickets vendidos. Búsqueda por email del comprador, número de orden, o estado (VALID, USED, REVOKED, TRANSFERRED). Útil para soporte.
Finanzas
Reporte de ingresos consolidado. Muestra ingresos por evento, comisiones cobradas, próxima liquidación, historial de transferencias.
Settings
Tu perfil de organizador, datos legales, datos bancarios para liquidación, contactos del equipo (si tenés más miembros).
02
Crear un evento (wizard de 5 pasos)
Click en "Crear nuevo evento" desde el panel principal. El wizard te guía:
Paso 1 — Tipo
Elegís la categoría: concierto, conferencia, festival, fiesta, deporte, exhibición, taller, etc. Esto define cómo se muestra el evento en kalokpass.com (filtros, secciones).
Paso 2 — Detalles
Título (ej: "Festival Neon Vol. 3"), descripción larga (markdown), poster (1:1, mín 1080×1080), banner (16:9, mín 1920×1080), thumbnail (16:9 chico). Los 3 archivos se suben a Cloudinary automáticamente.
Paso 3 — Lugar
Elegís un Venue existente o creás uno nuevo. Si lo creás, pedimos: nombre, dirección, ciudad, capacidad, descripción opcional, link a Google Maps (para que el comprador vea cómo llegar).
Paso 4 — Lineup
Opcional. Agregás artistas (existentes o nuevos). Cada artista tiene su perfil público y su set de seguidores; agregar artistas conocidos boostea las ventas porque sus fans reciben notif del evento.
Paso 5 — Entradas (PriceTier)
Definís los tipos de tickets: nombre (General, VIP, Palco), precio, moneda (CRC o USD), capacidad, fecha inicio + fin de venta, descripción. Al menos 1 tier es obligatorio. Para evento gratis: tier con precio 0.
03
Gestión de tickets
Una vez publicado, el panel de tu evento muestra el inventory en tiempo real:
Estados de orden (OrderStatus)
PENDING_PAYMENT (creada, esperando que Tilopay confirme), PAID (pago confirmado, tickets generados), EXPIRED (no se completó el pago a tiempo, libera capacidad), REFUNDED (reembolso total), PARTIALLY_REFUNDED (reembolso parcial), CANCELLED (cancelada manualmente sin reembolso).
Estados de ticket (TicketStatus)
VALID (no usado, listo para entrar), USED (escaneado al ingreso al evento), REVOKED (invalidado por organizador o cancelación), RESALE_LOCKED (en proceso de reventa, bloqueado temporalmente), TRANSFERRED (cedido a otro usuario, el original ya no vale).
Lista de tickets
En la pestaña "Tickets" del evento ves cada ticket individual con: nombre del comprador, email, tipo, estado, fecha de compra, número de orden. Filtrable y exportable a CSV.
Buscar un ticket específico
Si un comprador te escribe "no me llega", buscás por email en la pestaña Tickets. Si está VALID y vos no lo ves en su email, podés re-enviar el ticket desde el panel.
Revocar un ticket
Desde el detalle del ticket, opción "Revocar". Cambia el estado a REVOKED y el QR deja de funcionar. Útil para fraude detectado o disputas. La acción queda en AuditLog.
04
Códigos de descuento
En la pestaña "Promo Codes" de tu evento podés crear códigos para descuentos:
Configuración básica
Código (ej KALOK10 o auto-generado), tipo de descuento (porcentaje o monto fijo), valor, fecha inicio + fin de validez, cantidad máxima de usos totales.
Restringir a tipos de tickets (PromoCodeTier)
Por default un código aplica a todos los tickets del evento. Podés restringirlo a solo ciertos tiers (ej: solo VIP, solo General). El comprador ve el descuento solo si su carrito califica.
Allowlist por email (TierAllowlist)
Limitá quién puede usar el código a una lista específica de emails. Útil para sponsors, prensa, influencers. Si el email del comprador no está en la lista, el código no se aplica.
Tracking de uso (PromoCodeUsage)
Cada vez que se usa un código, queda registrado: timestamp, qué orden lo usó, qué descuento aplicó. Reporte exportable.
05
Check-in el día del evento
El scanner de QR es una web app — no necesitás instalar nada en el celular del staff:
Cómo abrir el scanner
Desde dashboard.kalokpass.com, andá a Eventos → tu evento → tab "Check-in". El navegador te pide permiso para usar la cámara. Aceptás y empezás a scanear.
Validación del QR
El scanner lee el código QR del ticket y consulta el backend. Si el ticket está en estado VALID y pertenece a este evento, lo marca como USED y muestra ✓ verde. Si está en otro estado, muestra alerta roja con el motivo.
Búsqueda manual
Si alguien perdió el QR, podés buscar por email o por nombre. El scanner muestra el ticket y permite marcarlo como USED manualmente (queda registrado quién lo validó).
Múltiples staff scaneando a la vez
Cualquier usuario con rol ORGANIZER (o miembros del team que invitaste) puede scanear simultáneamente. La validación es sincrónica con la DB — no hay riesgo de doble validación.
Modo offline (próximamente)
Estamos trabajando en un modo offline para venues con mala conexión: descarga la lista de tickets antes del evento y valida localmente, sincronizando cuando vuelve la red.
06
Reembolsos y cancelaciones
El sistema soporta cancelación total del evento o reembolsos individuales:
Cancelar el evento entero
Desde Settings del evento, opción "Cancelar evento". Esto dispara: email automático a todos los compradores, reembolso 100% (incluye comisiones Kalok + Tilopay), órdenes pasan a REFUNDED, tickets a REVOKED. Acción irreversible.
Reembolso individual
Desde la pestaña Tickets, click en el ticket → Reembolsar. Podés reembolsar el monto completo o parcial. La orden pasa a REFUNDED o PARTIALLY_REFUNDED. La comisión Kalok se reintegra solo en cancelaciones del evento, no en reembolsos individuales (cubrimos el costo del proceso).
Tiempo del reembolso
Tarjetas: 5-30 días hábiles según el banco emisor. Sinpe Móvil: 24-48h. Esto lo determina Tilopay y los bancos, Kalok solo dispara la orden de reembolso.
Disputas / chargebacks
Si un comprador disputa el cargo en su banco, te avisamos por email. Tenés ventana de 7 días para enviarnos evidencia (entrada usada, comunicación con el comprador). Kalok actúa de intermediario con Tilopay.
07
Transferencias entre usuarios
Tu comprador puede ceder su ticket a otra persona desde su cuenta:
Cómo se hace
El comprador va a "Mis Tickets" → click en el ticket → "Transferir" → ingresa el email del nuevo dueño. El ticket original pasa a estado TRANSFERRED y el nuevo dueño recibe un ticket fresco a su nombre con QR válido.
Restricciones (configurables por evento)
Por default las transferencias están permitidas. Como organizador podés deshabilitarlas (tickets nominales obligatorios) desde Settings → "Permitir transferencias". También podés cerrar la ventana de transferencia X horas antes del evento.
Tracking
Cada transferencia queda en AuditLog: quién la inició, a quién la cedió, timestamp. Si una persona te dice que su QR no funciona, podés ver si su ticket está en TRANSFERRED.
08
Analytics
En tiempo real, sin delay. Disponible desde la pestaña "Analytics" del evento:
Tickets vendidos
Gráfica por hora / día. Identificás picos de venta (lanzamiento, anuncios en redes, recordatorios pre-evento).
Ingresos por tipo
Breakdown por PriceTier. Te dice qué tipo de ticket tira más (ej: VIP vs General) para ajustar pricing.
Conversión
Visitas al page del evento ÷ tickets comprados. Si está baja, hay problema en el copy / arte / precio. Si está alta, hay problema de tráfico (no llega gente).
Fuentes de tráfico
Referrer agrupado por origen: directo, Instagram, Twitter, WhatsApp, email, otros. Te dice qué canal funciona mejor para tu audiencia.
Para developers
¿Necesitás integración via API?
El backend de Kalok corre sobre NestJS con endpoints REST. Si necesitás incrustar la compra de tickets en tu propia web, sincronizar tu base de fans, o exportar datos a tu CRM, escribinos a organizers@kalokpass.com con “API access” en el subject. Estamos abriendo acceso a la API pública con clientes seleccionados antes de la GA general.
¿Algo no quedó claro?
Esta documentación es viva. Si encontrás un caso que no cubrimos, escribinos y la actualizamos.