Skip to content

Integración: tickets de Catena

Esta página es para el desarrollador de una tienda o sistema de facturación — el lugar donde usted vende el acceso. En lugar de responder a un callback por cada espectador, usted crea la sesión por adelantado y le entrega al espectador un ticket. El streamer admite el ticket por sí mismo: comprueba la firma, la caducidad y el alcance localmente, sin llamar a sus sistemas en la ruta de reproducción.

La recompensa: la reproducción ya no depende de la velocidad ni la disponibilidad de su tienda, los canales arrancan y cambian al instante, y no hay un callback por espectador que escalar. Sus sistemas hacen falta en el momento en que vende el acceso — no mientras el espectador mira.

Crear una concesión

Cuando venda acceso, llame al management API para crear una concesión (grant). Catena firma un ticket (un JWT) y lo devuelve — el token se entrega solo en la creación; el registro guarda la concesión, no el ticket.

Autentique la llamada como autentica cualquier petición al management API — con el login y la contraseña de administrador. Para que su tienda nunca tenga que guardar credenciales de administrador completas, puede en su lugar configurar en central una clave de emisor (issuer key) dedicada — un token bearer cuyo único poder es emitir y gestionar concesiones — y enviarlo como Authorization: Bearer <issuer-key>.

POST /play-sessions/grants

{
  "streams": ["news", "arena"],
  "user_id": "subscriber-4821",
  "ttl_secs": 14400,
  "max_concurrent": 2,
  "bind_ip": "203.0.113.0/24",
  "note": "family plan"
}
Campo Significado
streams Qué canales puede reproducir el ticket — su alcance
user_id La cuenta a la que pertenece el ticket; agrupa las pantallas del espectador
ttl_secs Vida del ticket; por defecto 4 horas. exp es un fin fijo — una sesión no puede sobrevivirle (los reproductores no refrescan el token)
max_concurrent Pantallas simultáneas; por defecto 1, null para ilimitado
bind_ip IP o CIDR opcional fuera del cual el ticket es inútil
note Etiqueta de texto libre opcional

La respuesta lleva la concesión y el token. Entregue ese token al reproductor, que lo presenta en la URL de reproducción como ?token=<jwt> (o en una cabecera Authorization: Bearer). Nada más se le pide al espectador — el streamer se encarga del resto.

Pantallas

max_concurrent limita cuántas pantallas consumen activamente el ticket a la vez — un hogar con dos televisores, por ejemplo. Al pasar el límite se corta la pantalla más antigua; gana la más nueva. Puede cambiar el límite después sin reemitir el ticket, porque vive en el registro, no en el token firmado:

PATCH /play-sessions/grants/{jti}
{ "max_concurrent": 3 }

Revocar

Cancele una concesión y cada streamer suelta a sus espectadores en segundos y rechaza el ticket a partir de entonces — la cancelación viaja a los streamers por un feed de revocación, no esperando a que el ticket caduque. No hay reautorización para las sesiones de ticket; la revocación es el único canal que las termina antes de tiempo.

Roaming

Un espectador cuya dirección cambia — un teléfono que deja el Wi-Fi por los datos móviles — se admite de nuevo en la nueva dirección, sin conexión, mientras la sesión vieja muere por inactividad. Cuenta como un solo recorrido, no como un cargo nuevo, agrupado por la concesión. Si fija bind_ip, el roaming se queda dentro de ese rango.

Listado y estado

GET /play-sessions/grants lista las concesiones y su estado — issued (entregada, aún no reproducida), played (usada al menos una vez), revoked, expired —, filtrable por user_id y estado. Es el registro de lo que vendió y de si se usó.

Migre a su ritmo

Los tickets y un backend existente corren en paralelo — tickets para unos espectadores, el callback para otros — así que puede mover audiencia por audiencia. El estado final es el interruptor opaque_tokens: false en la política de autorización: una vez fijado, cualquier token que no sea un ticket se rechaza de plano, sin consultar listas ni un backend, y la vía del callback queda cerrada para siempre.

Siguientes pasos