Resumen de la API

PiSA API gestiona eventos corporativos de punta a punta: el padrón de asistentes, el salón (mesas y sillas), las reservas de lugares, los boletos QR y el check-in en puerta — con auditoría de cada operación y correos transaccionales por el camino.

Todo se expone como REST + JSON en una sola API. Este manual explica los flujos paso a paso y la referencia de endpoints detalla cada operación con ejemplos ejecutables.

Ciclo de vida de un evento

borrador ──publicar──▶ publicado ──iniciar──▶ en_curso ──cerrar──▶ cerrado

Mientras vive, el evento concentra su salón, su padrón, sus reservas y sus escaneos; al cerrar, queda como reporte histórico con su bitácora.

El dominio, concepto a concepto

Concepto	Qué es
Evento	Unidad de trabajo: zonas corporativas, plano SVG versionado, salón y padrón propios.
Salón	Mesas con sillas (lugares). Cada lugar vive en libre, apartado, confirmado o bloqueado; el estado lo deriva un trigger desde las reservas.
Participante	Fila del padrón de un evento: precargado → registrado → asistio. Se carga masivamente (hasta 10.000 filas) o manualmente.
Reserva	Aparta un lugar para un participante: apartada → confirmada, o expirada / cancelada / liberada_admin. Solo hay una vigente por participante y una por lugar (las carreras se resuelven con 409).
Boleto QR	Se emite solo al confirmar la reserva: código opaco + firma HMAC. Se verifica en puerta, se descarga en PNG/PDF y se puede revocar.
Check-in	Escaneo en un punto/puerta: valido, duplicado, revocado o no_encontrado — siempre 200 ante escaneos, con bitácora de intentos e incidencias.
Notificación	Cola de correos (encolado → enviado / fallido / rebotado): QR emitido, recordatorios y verificación de email.
Auditoría	Bitácora inmutable de toda mutación, con hash encadenado y verificación de integridad.

Quién usa la API

Actor	Autenticación	Alcance
Participante	Token propio (12 h)	Consulta y cancela su reserva, descarga su boleto, ve sus zonas.
Admin	Token propio (8 h)	Roles: superadmin (todo), operador (reservas, salón, check-in, notificaciones), checador (solo escaneo e incidencias), lectura.
Sistemas	Secretos de header	Jobs (x-cron-secret) y webhook del proveedor de correo (x-webhook-secret).

Los detalles de tokens, refresh y roles están en Autenticación y roles.

El recorrido completo de un evento

1. El admin crea el evento, define zonas, sube el plano SVG y monta el salón (mesas y sillas).
2. Se carga el padrón por importación masiva o alta manual.
3. Los participantes inician sesión y apartan lugares; el job de expiración libera los apartados vencidos.
4. Al confirmar una reserva se emite el boleto QR y llega por correo.
5. En la puerta se escanea el QR: validez, duplicados y revocaciones quedan registrados.
6. Todo queda en la auditoría; al cerrar el evento, el reporte es la bitácora.

Cada paso tiene su página en Flujos.

Transversal a todo

• Errores con contrato: todo error responde { "error": "…" } con su status (Errores y códigos).
• Rate limit por IP: general (300/min) y de autenticación (30/min).
• Jobs programados in-process, con endpoints HTTP equivalentes para disparo manual (Jobs programados).
• Una sola API sirve todo: el manual en / y la referencia OpenAPI en /openapi.

Stack

Bun · Elysia · Drizzle ORM · PostgreSQL. La suite combina unitarios, HTTP sin base de datos y e2e con Eden Treaty (Tests).

Siguiente paso

Instalación

Lleva el servidor de cero a respondiendo en localhost:5000. Instalación

Autenticación

Cómo obtener un token y qué puede cada rol. Autenticación y roles

Referencia API

Los 73 endpoints, operación por operación. Scalar