Preguntas frecuentes

Qué se puede hacer

¿Puedo crear eventos por API?

No. Ningún permiso concede administración: los eventos se crean en el panel.

Es una decisión, no una carencia pendiente. Una credencial que vive en el servidor de un tercero no debería poder reconfigurar tu negocio; si se filtra, el daño tiene que estar acotado a leer catálogo y mover ventas, no a montar eventos falsos.

¿Puedo emitir un reembolso por API?

No. Un reembolso mueve dinero real y se hace desde el panel, con una persona detrás. Ver devoluciones.

Sí puedes cancelar un pedido que todavía está pendiente, que es otra cosa: libera el stock de una reserva que nunca llegó a cobrarse.

¿Puedo cambiar precios o stock?

No. El catálogo es de solo lectura por API.

¿Puedo vender abonos?

Aparecen en el catálogo con scope: "pass", pero no se ofrecen en la disponibilidad de una fecha concreta, porque no pertenecen a una: dan acceso a varias. Venderlos por API no está soportado todavía.

¿Puedo generar mis propios códigos QR?

No. La firma que hace válida una entrada no se expone nunca, ni siquiera a una clave con todos los permisos: quien la tuviera junto al código podría fabricar QR que pasan el control. Lo que se distribuye son los PDF y los QR que emite Tickeep.

¿Puedo confirmar un pedido hecho desde la web de la sala?

No. /confirm y /cancel solo funcionan sobre pedidos creados por API (source: "api"). Cada canal tiene su circuito de cobro y su auditoría, y mezclarlos dejaría un rastro imposible de cuadrar. Recibirás 403 con details.reason: "notAnApiOrder".

Sobre las credenciales

¿Puedo llamar a la API desde el navegador?

No, y no es configurable. CORS está deshabilitado a propósito en /api/v1.

Si se pudiera, alguien acabaría poniendo su clave en el JavaScript de su web, y esa clave sería pública desde el primer minuto. Llama desde tu backend. Ver vender desde tu web.

He perdido el secreto de mi clave. ¿Me lo podéis recuperar?

No podemos: la clave no se guarda en claro en ningún sitio, ni siquiera el equipo de soporte tiene acceso.

Es a propósito, y es lo que hace que un incidente en nuestros sistemas no entregue las credenciales de nadie. Emite una clave nueva y revoca la vieja — son dos minutos.

¿Cuántas claves puedo tener?

Las que necesites. Lo recomendable es una por integración: tu web, tu control de acceso, tu sincronización con el CRM. Así el límite de uso no se comparte, la auditoría distingue quién hizo qué y revocar una no tumba las demás.

¿Cómo roto una clave sin cortar el servicio?

Emite la nueva, despliégala, comprueba que el tráfico entra por ella y pon fecha de caducidad a la vieja. Puedes tener dos activas a la vez. Ver autenticación.

¿Hay entorno de pruebas?

Existen claves tk_test_ que se distinguen por el prefijo, pero operan sobre los mismos datos. Un pedido creado con una clave de pruebas es un pedido de verdad en tu organización.

Mientras no haya un sandbox completo, lo que recomendamos es crear una sala de pruebas y acotar la clave de test a esa sala.

Sobre la venta

¿Qué pasa si dos clientes compran la última entrada a la vez?

Uno recibe su pedido y el otro un 409 sold_out. La reserva es atómica: no hay ningún caso en el que los dos se lleven la misma entrada.

La disponibilidad decía que quedaban y la venta ha fallado. ¿Es un error?

No. /availability es una foto del momento; la verdad la fija POST /orders. Entre las dos llamadas, otro comprador puede haberse llevado las últimas. Enséñale al comprador un mensaje decente y vuelve a pedir disponibilidad.

¿Cuánto dura una reserva?

30 minutos. Después se cancela sola y el stock vuelve a estar libre. El instante exacto viene en reservationExpiresAt.

Si el comprador abandona antes, cancela explícitamente: si no, esas entradas siguen bloqueadas media hora y no se le pueden vender a nadie.

¿Por qué no puedo mandar el precio?

Porque un cliente que pudiera fijar el precio podría venderse entradas a cero euros. El precio, el IVA y los gastos de gestión los calcula el servidor contra su base de datos. Tú mandas ticketTypeId y quantity.

He confirmado un pedido y ticketsStatus dice pending. ¿Ha fallado algo?

No. Significa que el proceso de fondo ganó la carrera y está emitiendo las entradas; estarán en segundos. El pedido está cobrado igualmente. Vuelve a consultarlo con GET /orders/{reference}.

¿Cómo sé que el comprador ha pagado con el enlace de pago?

Con el webhook order.paid. Es la única forma: no preguntes en bucle. Ver webhooks.

Sobre los webhooks

La firma no me cuadra

Es casi seguro que estás firmando el cuerpo reserializado en vez del crudo. En Express hace falta express.raw(), no express.json(); en Next.js, await req.text() antes de cualquier JSON.parse.

Los otros dos sospechosos: no estás comprobando el timestamp, o estás comparando con ===. Los tres están explicados en webhooks.

Me llega el mismo evento dos veces

Es el comportamiento esperado: se garantiza al menos una entrega, no exactamente una. Un reintento lleva el mismo id de evento. Deduplica por ese id antes de actuar.

Mi endpoint se ha desactivado solo

Tras 20 fallos consecutivos la suscripción se apaga. El contador se pone a cero con cada entrega correcta, así que esto solo pasa cuando un endpoint lleva mucho rato roto.

Arréglalo, reactívalo desde el panel y reenvía las entregas perdidas: quedan todas registradas.

Ten en cuenta que hoy la desactivación no manda ningún aviso: queda reflejada en el panel. Monta tú una alarma si tu receptor deja de recibir eventos.

¿Puedo apuntar un webhook a mi localhost para desarrollar?

No desde producción: se bloquean las direcciones internas y el loopback. Usa un túnel que te dé una URL pública con HTTPS.

Sobre los datos

¿Por qué el dinero viene en céntimos?

Porque en coma flotante 12,50 € no se representa de forma exacta, y sumar cien líneas de pedido acumula deriva. Guárdalo en céntimos y divide por 100 solo al pintar. Ver convenciones.

¿Por qué las fechas están en UTC?

Para que no haya ambigüedad. Cada sala trae su timezone en GET /venues: úsala para formatear. Una función que empieza a las 22:00 en Madrid es una hora UTC distinta en verano y en invierno.

El nombre del evento en un pedido no coincide con el del catálogo

Correcto y deliberado. lines[].eventName guarda lo que se llamaba el día de la venta. Si la sala lo renombra después, el pedido sigue diciendo lo que el comprador compró — que es lo que tiene que decir una factura.

¿Por qué unas cosas se filtran por sala y los asistentes no?

Quien compra en dos salas de tu organización es una sola persona, con un historial que suma las dos. Trocearlo por sala daría una foto falsa. Por eso /attendees es por organización y necesita su propio permiso, customers:read.

¿Puedo pedir 500 elementos de golpe?

No: el máximo es 100 y un valor mayor se recorta en silencio. Sin ese tope, un limit grande convierte cualquier listado en una descarga de la colección entera.

¿Por qué cursores y no números de página?

Porque estos listados crecen mientras los recorres, y con offset una venta nueva desplaza la ventana y te saltas filas sin enterarte. El ejemplo concreto está en paginación.

Cuando algo va mal

Recibo 404 y estoy seguro de que el id existe

Casi siempre es el ámbito de salas de la clave. Un recurso de una sala fuera de su ámbito responde 404, igual que uno inexistente: distinguirlos convertiría la API en un detector de identificadores ajenos.

Comprueba qué salas alcanza tu clave con GET /venues.

Recibo 429 y creo que no llamo tanto

Revisa cuatro cosas, por este orden: estás pidiendo páginas de 25 en vez de 100; estás releyendo el catálogo entero en vez de usar updatedSince; estás preguntando en bucle en vez de escuchar webhooks; o estás llamando a la API en cada visita de tu web en vez de cachear. Ver límites de uso.

¿Qué mando en un ticket de soporte?

El X-Request-Id de la respuesta que falló, el endpoint y la hora aproximada. Con eso encontramos la petición exacta en segundos. Sin eso, hay que adivinar.

Regístralo desde el primer día, aunque solo sea para los 5xx.

Necesito algo que la API no hace

Escríbenos. Las decisiones sobre qué exponer salen de lo que nos piden las salas que ya usan Tickeep, y saber para qué lo quieres cambia el orden en que lo construimos.