Administración

Locales y salas

El panel de tu empresa vive en empresa.pov.uy. No hace falta ser técnico: se opera con formularios, y lo que cargás acá es lo que muestra el widget.

La estructura es Empresa → Local → Sala. Un cine con tres complejos tiene un local por complejo, y las salas cuelgan de cada uno.

Crear una sala (Salas → Nueva) pide tipo (cine / teatro / auditorio), medidas, filas y butacas por fila, precio base, pendiente del piso, un sector VIP opcional (las últimas N filas con su propio precio) y las butacas accesibles. POV genera el plano completo, con sus butacas numeradas.

También podés partir de una foto de la sala («Crear con IA»): POV estima filas, butacas, VIP y pendiente, y te deja el plano listo para ajustar en el editor antes de guardar. La foto no se guarda. Está disponible en las cuentas con generación de salas por IA habilitada.

El editor de sala (Salas → la sala → Editor) es un plano interactivo que podés mover y girar. Ahí se mueve, rota, agrega y numera butacas; se definen sectores con su color, nombre y precio; se ajustan pasillos, escalones, la inclinación del piso y la distancia a la primera fila. También se ubica la pantalla o el escenario y el foco de cámara —desde dónde arranca el visor—, y se puede importar o exportar un modelo GLB propio para usar la sala real en 3D.

Interruptores por sala que conviene conocer:

Cada butaca que definís alimenta a la vez el mapa 2D, la escena 3D, el inventario, el bloqueo y la reserva. No hay dos mapas que sincronizar: cargás la sala una vez y todo queda consistente.

Contenido y programación

Contenido es lo que se proyecta o se presenta: película, obra, concierto. Trae buscador de películas (título, póster, duración, calificación) y acepta un video propio que se reproduce en la pantalla de la sala 3D.

Programación es cada función: contenido + sala + día y hora. Desde ahí podés crear una función —sola o importando un CSV, con archivo de ejemplo—, marcarla de prueba (se puede cambiar después, mientras no haya vendido), fijarle un precio propio, copiar el código de integración de esa función con tu clave real adentro, y asignar butacas a mano (invitados, prensa, protocolo) y liberarlas.

La hora que cargás es la de tu cuenta, no la del servidor ni UTC: si tu empresa está configurada en otra zona, «20:00» son las 20:00 de tu reloj. Lo mismo vale para el CSV.

Precios y reglas

El precio se define en tres niveles, del más general al más específico:

1. Sector de la sala — «la platea vale 320, el balcón 520». Es la base. 2. Precio de esta función — Programación → la función → «Precio de esta función»: un estreno, una matinée, una función especial. 3. Reglas por día — «los viernes la platea vale 30 % más».

Los precios se guardan como enteros en centavos (32000 = $ 320,00) y el importe de cada compra lo recalcula POV en el servidor con el precio vigente de cada butaca. El navegador nunca fija el total.

Por eso cambiar una regla no mueve lo que ya está a la venta — el precio de una función publicada no puede cambiar solo. Para propagarla hay un botón explícito, «Aplicar a las funciones futuras», y al aplicarla sólo se tocan las butacas libres o bloqueadas: la vendida se cerró a su precio y la que está en un bloqueo tiene un total ya cotizado.

Una regla puede acotarse a una sala, a un sector, y a una franja horaria (matinée, trasnoche). La franja puede cruzar la medianoche (22:00 → 02:00).

Dos cosas que se miden distinto de lo que uno espera, y están bien así: el día sale de la fecha comercial, no de la hora de inicio —la trasnoche del viernes a la 01:30 es viernes y se cobra como viernes—; y la hora es la de tu cuenta, no UTC, porque medirla en UTC correría todas las franjas.

Precedencia: sala + sector → sala → sector → general. Dentro de cada nivel, la regla con franja le gana a la que no la tiene: así se escribe «los domingos +30 %, salvo la matinée».

Lo que se rechaza al crear una regla es lo ambiguo, no lo superpuesto: chocan dos franjas que se pisan, o dos reglas sin franja para el mismo alcance. «Todo el día» conviviendo con una franja no es ambiguo — lo resuelve la precedencia.

Las reglas se aplican por igual en los tres caminos de alta (panel/CSV, programación por referencia y alta automática al embeber): una regla que valiera en uno solo cobraría distinto el mismo viernes según por dónde entró la función.

Tipos de entrada

Jubilado, estudiante, menor, escuela… los que quieras, con el precio que quieras. Se crean en Tipos de entrada, y el espectador elige el de cada butaca en el widget.

El precio se escribe en relación al del sector y por eso no hay que cargarlo sector por sector: si la platea vale $ 320 y el balcón $ 520, «30 % menos» da $ 224 y $ 364 sin tocar nada más, y si movés el precio del sector los tipos lo siguen solos. Las tres formas son:

Cuando una función necesita un número exacto —un estreno, una matinée— se carga en Programación → la función → Precio de esta función, y ese número le gana al cálculo del tipo.

Ocultar saca el tipo del widget sin borrar nada, y lo ya vendido con él sigue diciendo con qué se vendió. Un tipo oculto tampoco se puede comprar por API: responde 422 en vez de cobrar el general en silencio.

Sin ningún tipo creado, cada butaca se vende al precio de su sector — que es exactamente como funcionaba antes de que existieran.

Descuentos

Códigos que el espectador escribe en el widget. Pueden ser porcentaje o monto fijo, acotarse a una función y/o a un sector, tener vencimiento y un tope de usos, y activarse o desactivarse cuando quieras.

Igual que los precios, el descuento se valida y se calcula en el servidor al crear el bloqueo: el navegador no puede inventarse un importe con descuento.

Items (confitería)

Pop, gaseosas, combos. Se habilita por cuenta, y entonces el widget suma un segundo paso después de elegir butacas.

Van en el mismo pago, con el mismo impuesto, y viajan en pov:hold bajo concessions. Es venta libre: no llevan inventario ni stock.

Reservas y reportes

Al gestionar una función ves su mapa de butacas con el estado de cada una, y podés asignar butacas a mano y liberarlas después. Desde ese mapa sólo se sueltan asignaciones manuales: una butaca vendida no se libera ahí, para eso está Deshacer.

Reservas lista las ventas, con filtros por fecha comercial, sala y estado, y búsqueda por compra o por QR. Desde ahí se deshace una venta (mismo efecto que la API) y se anonimiza al comprador de una reserva o de todas: se borran nombre y contacto y se conservan importes, butacas y estado, que es lo que hace falta para la contabilidad.

Reportes agrupa por fecha comercial y exporta a CSV. Las funciones de prueba no entran: el sandbox no ensucia los números.

Ingreso (check-in)

Consola de puerta que funciona con cualquier lector USB. Escanea el QR de una entrada (qr_…) o el de la compra entera (rsv_…) y marca las entradas como usadas.

Cuando hay más de una entrada sin usar en la misma compra, pregunta cuáles habilitar: eso es lo que evita que el primero de un grupo queme las entradas de todos. Cuando no hay nada que decidir —una entrada suelta, o una compra con una sola sin usar— valida derecho, porque una puerta necesita velocidad. Antes de decidir se puede mirar sin consumir.

La misma operación está en la API si preferís tu propio scanner.

Equipo y permisos

Tres niveles: owner de la plataforma (nosotros) → administrador de la empresa → colaboradores.

Un colaborador se define con permisos finos: salas · programación · pagos · integración. Soporte e Ingreso no exigen permiso: los usa cualquiera del equipo. Gestionar colaboradores es sólo del administrador de la empresa.

Verificación en dos pasos. Es obligatoria a los 10 días del alta de la cuenta. No se pide en el primer login —enrolarse necesita el teléfono a mano y nadie quiere descubrir eso en el mostrador— pero después sí: una cuenta del panel administra dinero, datos de compradores y claves de API, y una contraseña filtrada alcanzaría para todo eso. Se puede entrar también con Google, y el segundo factor se exige igual. Hay códigos de recuperación de un solo uso, que se muestran una vez.

Claves, orígenes y webhooks

Claves. Se crean por tipo (pública / secreta) y por modo (live / prueba). La secreta se muestra una sola vez: se guarda hasheada y no se puede recuperar. Para rotar, creá la nueva y revocá la vieja después.

Orígenes permitidos. Los dominios desde los que tu sitio puede llamar a la API con la pk_. Webhooks. URL https://, secreto, activar/desactivar, rotar sin corte y borrar.

Facturación

Tu suscripción a POV, tus facturas (descargables en PDF) y el cambio de plan o de período.

El anual son doce meses con 5 % de descuento (US$ 912/año = US$ 76 por mes).

La baja se pide desde el panel y no corta en el acto: el período ya está pagado, así que la cuenta sigue funcionando hasta el final. Se puede dar marcha atrás en cualquier momento antes de esa fecha.

Si un cobro falla la cuenta pasa a en mora y te avisamos, pero no se cierra el panel ni se corta la venta: que rebote una tarjeta significa que seguimos intentando cobrarte, no que te fuiste. En esa situación el botón principal es «Actualizar la tarjeta».

Si la suscripción termina, el widget sigue vendiendo 30 días más y te avisamos con la fecha exacta. Un cine publica su programación con semanas de anticipación: cortar el mismo día dejaría sin butacas funciones ya anunciadas, y el espectador no tiene nada que ver con el vínculo comercial. Pasado ese plazo, la pk_ deja de autenticar y el widget deja de servirse. La sk_ no se corta: las entradas ya vendidas se siguen validando en la puerta.

Pasarela POV

El plan donde el espectador paga dentro del widget y POV te liquida, reteniendo su comisión (5 % por entrada, por defecto).

La pasarela de POV es Stripe. El espectador paga con tarjeta y el cobro lo procesa Stripe; POV administra el inventario, emite las entradas y te liquida. Vale saberlo de antemano porque decide dos cosas prácticas: cómo cobrás (hay que conectar una cuenta de cobro, o que POV cobre y te transfiera) y cómo devolvés —el reembolso se hace en Stripe—.

Al arrancar el cobro el bloqueo se extiende: el 3-D Secure puede tardar varios minutos y las butacas no se pueden liberar con el pago en curso.

Se administra en la sección Checkout del panel:

Mail — el correo de entrada que recibe el comprador: remitente, dirección de respuesta, asunto y mensaje, con vista previa. Configuración — activar el cobro (requiere tus datos bancarios) y conectar la cuenta de cobro. Resumen — lo cobrado, los compradores y las liquidaciones, exportables a CSV y Excel.

Hay dos modos de liquidación: automática (el neto va directo a tu cuenta conectada) o manual (POV cobra y te transfiere). El dinero se libera después de un plazo configurable, y la liquidación del neto puede tomar hasta 60 días corridos según el medio de pago del espectador y sus tiempos de acreditación y contracargo (Términos, cláusula 2.3). Si necesitás liquidez inmediata, el plan Autogestionado te la da: ahí cobrás vos.

En este plan el reembolso se hace en Stripe, y POV deshace la venta al recibir el aviso. /reservations/{id}/refund responde 409: una sola forma de devolver cada peso.

Dos cosas que están así a propósito. El cobro no se simula: POST /holds/{token}/pay con clave de prueba responde 409, porque POV tiene una sola cuenta de cobro y un pago «de prueba» sería plata real. Y el espectador no paga tu problema comercial: con la cuenta en mora, o con la suscripción terminada dentro del plazo de gracia, bloquear butacas y cobrar siguen funcionando.

Tu cuenta y soporte

En Mi cuenta cambiás tu foto, tu nombre y tu contraseña, vinculás tu cuenta de Google para entrar con un clic, administrás la verificación en dos pasos y ves tus sesiones abiertas, con la posibilidad de cerrar una sola —la del teléfono que perdiste— sin echarte a vos mismo.

En Soporte abrís tickets con el equipo de POV y seguís la conversación desde el panel, con capturas adjuntas si hacen falta. El ticket queda en el hilo: no hace falta buscar un correo viejo.

Problemas frecuentes

«Origen no autorizado» — INVALID_ORIGIN (403)

El dominio desde el que corre tu página no está en tus orígenes permitidos. Agregalo exacto, con protocolo, en Integración → Orígenes. Los tres tropiezos habituales: http en vez de https, el www. que sobra o falta, y un subdominio distinto al declarado.

Si el error aparece en un POST /holds desde tu propio servidor, la causa es otra: esa ruta exige una cabecera Origin, y un script no la manda. Los bloqueos se crean desde el navegador.

«Clave inválida» — INVALID_KEY (401)

La pk_ está mal copiada, revocada, es de otra cuenta, o la cuenta no tiene plan vigente. Copiala de nuevo desde Integración. Y verificá el modo: una pk_test_ sobre una función real responde como si la función no existiera. En el navegador va la pk_, nunca la sk_.

«No existe» — NOT_FOUND (404)

Casi siempre es un cruce de modo o de cuenta: el recurso existe pero no para esa clave. POV responde «no existe» a propósito, para no delatar qué hay del otro lado.

El bloqueo venció — HOLD_EXPIRED (410)

Confirmá igual, siempre: si el bloqueo venció hace poco y las butacas siguen libres, la venta se rescata sola. Si aun así recibís 410, el rescate ya se intentó y no fue posible: es la señal de reembolsar, y details.unavailableSeats te dice qué butacas se perdieron. Nunca vuelvas a cobrar sobre ese bloqueo.

Con la Pasarela POV esto casi no ocurre: al arrancar el cobro el bloqueo se extiende.

«Demasiadas peticiones» — RATE_LIMITED (429)

Esperá lo que dice Retry-After. Si te pasa seguido con GET /venues/{id}/layout, estás pidiendo el plano más de una vez: pedilo una y cacheálo. Si te pasa con disponibilidad, sacá el setInterval y consultá al abrir la función y antes de reservar, con If-None-Match.

El widget no carga nada

Por orden de probabilidad: la cuenta está suspendida o sin plan vigente · falta la clave pública del modo de esa función · el data-showtime no es de tu cuenta · la referencia (data-ref) todavía no está programada y la sala no tiene la programación desde tu web activada.

La sala 3D no aparece

La sala puede estar marcada solo-2D en el panel, o el navegador no tener WebGL. En los dos casos se vende igual con el mapa 2D: es a propósito.

# Números que conviene recordar
Duración de un bloqueo                       10 minutos
Rescate de un pago tardío                    hasta 10 minutos después de vencido
Butacas por bloqueo                          10
Bloqueos vivos por llamante                  5
Reintentos de webhook                        3 (0,5 s y 2 s), 5 s de timeout
Venta después de vencida la suscripción      30 días
Límite más bajo de la API                    GET /venues/{id}/layout, 30/min