Lives de vendas

Uma live (sessão de live commerce) é uma transmissão de vídeo organizada por um seller (lojista) ou pela própria loja, com produtos em destaque que o cliente compra sem sair da página. Estas rotas são o lado do espectador: descobrir lives no ar, abrir uma, conversar no chat e, quando o organizador liga a gamificação, ganhar pontos por tempo assistido, responder a quizzes e resgatar um voucher relâmpago.

Criar, iniciar e encerrar a live é feito no painel do administrador ou do seller, e não faz parte desta seção.

Como funciona

O organizador agenda a live, inicia a transmissão e a encerra. Uma live também pode ser cancelada. O chat fica aberto enquanto a live não estiver encerrada nem cancelada.

Um espectador típico segue este caminho:

1. Descobrir
   Chame Lives no ar e detalhe para listar as lives em andamento e as próximas, e abra a que interessa.
2. Assistir
   Use embed_url do detalhe para exibir o player. Os produtos em destaque vêm em featured_products.
3. Conversar
   Carregue o histórico e envie mensagens em Chat.
4. Ser premiado
   Com o cliente logado, envie o heartbeat a cada 30 segundos, responda quizzes, acompanhe o ranking e resgate o voucher relâmpago.

Conceitos principais

Eventos em tempo real

Além das rotas REST, a plataforma publica eventos da live por WebSocket, só para clientes logados. Conecte em /ws e, em até 5 segundos, envie {"type":"auth","token":"<access_token>"}. Depois envie {"action":"subscribe","topic":"live:<id da live>"}. Só o tópico live:<uuid> é aceito. Os eventos são live.chat.message (nova mensagem), quiz.open (um quiz abriu), quiz.closed (o quiz fechou, já com a resposta certa) e flash_voucher.revealed (o voucher foi revelado). Visitante sem login não consegue conectar e depende do polling.

O quiz_id que a rota de resposta pede só chega pelo evento quiz.open. Não existe rota REST que liste quizzes.

Gamificação

Cada live pode ter configuração própria: pontos por minuto assistido, teto de pontos por live, um voucher relâmpago e o tempo de visualização que o destrava. Se o organizador não configurou nada, o heartbeat responde zerado e o ranking fica vazio.

Quem é o espectador

Visitante sem login pode ler e conversar no chat (com guest_name). Para pontuar, o cliente precisa estar logado, porque os pontos entram no programa de recompensas da conta.

Endpoints

Erros comuns

• Esperar 404 com id malformado em todas as rotas. Só a leitura (detalhe e histórico do chat) devolve 404 LIVE_SESSION_NOT_FOUND para um id que não é UUID. Enviar mensagem a uma live inexistente devolve 400, não 404.
• Procurar o quiz_id por REST. Ele vem apenas no evento quiz.open do WebSocket.
• Mandar seconds no heartbeat. O corpo é ignorado. O servidor soma 30 segundos por chamada aceita e, no máximo, o tempo que a live já durou.
• Chamar o heartbeat com menos de 25 segundos de intervalo. A chamada responde 200, mas não soma nada.
• Tratar 403 como falta de permissão do cliente. Aqui ele costuma ser module_disabled (módulo desligado) ou, no voucher, not_unlocked e flash_unavailable.
• Guardar a lista em cache. O estado muda a cada transição da live; respeite no-store.

Próximos passos