Skip to content

Integração: tickets do Catena

Esta página é para o desenvolvedor de uma vitrine ou sistema de cobrança — o lugar onde você vende o acesso. Em vez de responder a um callback por cada espectador, você cria a sessão com antecedência e entrega ao espectador um ticket. O streamer admite o ticket por conta própria: verifica a assinatura, a validade e o escopo localmente, sem chamar os seus sistemas no caminho de reprodução.

A recompensa: a reprodução não depende mais da velocidade nem da disponibilidade da sua vitrine, os canais arrancam e trocam na hora, e não há um callback por espectador para escalar. Os seus sistemas são necessários no momento em que você vende o acesso — não enquanto o espectador assiste.

Criar uma concessão

Ao vender acesso, chame o management API para criar uma concessão (grant). O Catena assina um ticket (um JWT) e o devolve — o token é entregue apenas na criação; o registro guarda a concessão, não o ticket.

Autentique a chamada como você autentica qualquer requisição ao management API — com o login e a senha de administrador. Para que a sua vitrine nunca precise guardar credenciais de administrador completas, você pode em vez disso configurar no central uma chave de emissor (issuer key) dedicada — um token bearer cujo único poder é emitir e gerir concessões — e enviá-lo 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 Quais canais o ticket pode reproduzir — o seu escopo
user_id A conta a que o ticket pertence; agrupa as telas do espectador
ttl_secs Vida do ticket; padrão 4 horas. exp é um fim fixo — uma sessão não pode sobreviver a ele (os reprodutores não renovam o token)
max_concurrent Telas simultâneas; padrão 1, null para ilimitado
bind_ip IP ou CIDR opcional fora do qual o ticket é inútil
note Rótulo de texto livre opcional

A resposta carrega a concessão e o token. Entregue esse token ao reprodutor, que o apresenta na URL de reprodução como ?token=<jwt> (ou num cabeçalho Authorization: Bearer). Nada mais é pedido ao espectador — o streamer cuida do resto.

Telas

max_concurrent limita quantas telas consomem ativamente o ticket ao mesmo tempo — uma casa com dois televisores, por exemplo. Passe do limite e a tela mais antiga é cortada; a mais nova vence. Você pode mudar o limite depois sem reemitir o ticket, porque ele vive no registro, não no token assinado:

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

Revogar

Cancele uma concessão e cada streamer solta os seus espectadores em segundos e recusa o ticket dali em diante — o cancelamento viaja aos streamers por um feed de revogação, não esperando o ticket expirar. Não há reautorização para as sessões de ticket; a revogação é o único canal que as termina antes do tempo.

Roaming

Um espectador cujo endereço muda — um telefone que sai do Wi-Fi para os dados móveis — é admitido de novo no novo endereço, offline, enquanto a sessão antiga morre por inatividade. Conta como um único percurso, não como uma nova cobrança, agrupado pela concessão. Se você definir bind_ip, o roaming fica dentro dessa faixa.

Listagem e status

GET /play-sessions/grants lista as concessões e o seu status — issued (entregue, ainda não reproduzida), played (usada ao menos uma vez), revoked, expired —, filtrável por user_id e status. É o registro do que você vendeu e se foi usado.

Migre no seu ritmo

Os tickets e um backend existente correm lado a lado — tickets para uns espectadores, o callback para outros — então você pode mover audiência por audiência. O estado final é o interruptor opaque_tokens: false na política de autorização: uma vez definido, qualquer token que não seja um ticket é recusado de imediato, sem consultar listas nem um backend, e a via do callback fica fechada de vez.

Próximos passos