Receta: tu propio control de acceso

Si ya tienes tornos, lectores o un sistema de puerta, no hace falta que tu equipo cambie de herramienta: la API valida entradas de Tickeep desde el hardware que ya usas.

Lo que necesitas: una clave con tickets:validate —que ya incluye tickets:read—.

El circuito

GET /tickets?performanceId=…       → el padrón, antes de abrir
POST /tickets/{code}/check-in      → con dryRun: consultar sin consumir
POST /tickets/{code}/check-in      → sin dryRun: la persona pasa

1. Descargar el padrón

Antes de abrir puertas, tráete quién está previsto:

async function padron(performanceId: string) {
  const entradas = []
  let cursor: string | undefined
  do {
    const p = await tickeep.tickets({ performanceId, limit: 100, cursor })
    entradas.push(...p.data)
    cursor = p.nextCursor ?? undefined
  } while (cursor)
  return entradas
}

Sirve para dos cosas: saber cuánta gente esperas y tener una lista contra la que buscar por nombre cuando alguien llega sin el QR.

Refréscalo mientras la puerta está abierta si la venta sigue activa.

2. Validar

const { result, ticket } = await tickeep.checkIn(codigo, { performanceId })

switch (result) {
  case 'valid':             return abrirTorno(ticket)
  case 'alreadyUsed':       return rechazar(`Ya se usó a las ${hora(ticket.checkedInAt)}`)
  case 'void':              return rechazar('Entrada anulada')
  case 'wrongPerformance':  return rechazar('Es de otra fecha del mismo evento')
  case 'wrongEvent':        return rechazar('Es de otro evento')
  case 'invalidToken':      return rechazar('Código no válido')
  case 'notFound':          return rechazar('No existe')
  default:                  return rechazar('Resultado desconocido')
}

Ese default no es decorativo: pueden aparecer veredictos nuevos, y un lector que se cuelgue ante uno desconocido es peor que uno que lo rechace educadamente.

3. Manda siempre performanceId

Es un campo opcional en el contrato porque hay flujos donde no se sabe la fecha —comprobar un código por teléfono, por ejemplo—. En un lector de puerta, mándalo siempre.

4. Tornos: consultar y después abrir

Un torno que enseña la ficha del asistente antes de dejar pasar necesita las dos llamadas:

// El QR pasa por el lector
const previo = await tickeep.checkIn(codigo, { performanceId, dryRun: true })
if (previo.result !== 'valid') return mostrarRechazo(previo.result)

mostrarFicha(previo.ticket)   // nombre, tarifa, zona, consumiciones

// La persona empuja el torno
const definitivo = await tickeep.checkIn(codigo, { performanceId })
if (definitivo.result === 'valid') abrirTorno()

dryRun: true devuelve el veredicto sin consumir la entrada. Ojo con el hueco entre las dos llamadas: si el asistente se da la vuelta después de la consulta, la entrada sigue sin usar. Es correcto —no ha entrado nadie— pero tu interfaz debería dejarlo claro.

5. Varias puertas a la vez

No hace falta coordinarlas. La entrada se consume con una operación atómica: si dos lectores escanean el mismo código en el mismo instante, uno recibe valid y el otro alreadyUsed. Nunca pasan los dos.

Puedes poner cuatro puestos en paralelo sin ningún estado compartido entre ellos.

6. Si se cae la red

Es el escenario que hay que pensar antes, no durante.

Lo que sí puedes hacer:

• Reintentar con cortes cortos. Un timeout de 3 segundos y dos reintentos cubren la mayoría de microcortes sin que el operario note nada.
• Registrar los códigos que no pudiste validar y procesarlos cuando vuelva la conexión, sabiendo que algunos saldrán alreadyUsed.
• Usar la app de Tickeep para las puertas sin cobertura. Está hecha para eso: descarga el padrón con las firmas y valida en local, con su propio mecanismo de reconciliación. Ver escanear entradas.

7. Auditoría

Una validación hecha por API queda a nombre de la clave, no de una persona. En el panel se distingue de las que hace tu equipo con la app.

Si necesitas saber qué puerta validó qué, emite una clave por puesto y nómbralas claramente («Puerta principal», «Acceso VIP»). Es la única forma de reconstruirlo después.

Lo que no puedes hacer

• Generar tus propios QR. La firma que hace válida una entrada no se expone nunca, y ningún endpoint la devuelve. Se distribuyen los PDF y los QR que emite Tickeep.
• Deshacer un check-in. Si alguien se equivoca en la puerta, se corrige desde el panel.
• Anular una entrada. Desde el panel, o devolviendo el pedido.
• Consumir las consumiciones incluidas. El campo includes ya viene con su contador used, pero el consumo todavía no está expuesto por API.

Antes de la primera noche