Sessões ao vivo
Live commerce: agendar transmissões ao vivo, destacar produtos, premiar espectadores e criar clipes da reprise.
Live commerce é a venda por transmissão ao vivo: um seller apresenta produtos em vídeo e o cliente compra enquanto assiste. A plataforma não transmite vídeo; ela guarda o endereço da transmissão (YouTube, Vimeo, Mux...), controla o ciclo da sessão, mostra a vitrine de produtos ao lado do player, hospeda o chat e premia quem assiste. Esta seção é a API administrativa, que enxerga as sessões de todos os sellers.
Como funciona
O ciclo de uma sessão: o seller (ou o administrador) agenda; nos minutos antes, cadastra os produtos em destaque; na hora, start coloca no ar; durante a live, o administrador pode abrir e fechar quizzes e revelar o voucher relâmpago; ao fim, end tira do ar. Depois, informar replay_url libera a reprise e permite criar clipes dos produtos.
| Estado | Significado | Como entra | Como sai |
|---|---|---|---|
scheduled | Agendada. | Criação. | start ou cancel. |
live | No ar. | start. | end ou cancel. |
ended | Terminou. Estado final. | end. | Nenhuma. |
cancelled | Cancelada. Estado final. | cancel. | Nenhuma. |
Códigos de erro de transição (HTTP 409): LIVE_SESSION_NOT_SCHEDULED (só scheduled inicia), LIVE_SESSION_NOT_LIVE (só live encerra), LIVE_SESSION_ALREADY_TERMINAL (encerrada ou cancelada não cancela de novo).
Conceitos importantes
Transmissão e reprise
embed_url é o endereço do vídeo ao vivo; replay_url é a gravação, para quando a sessão acaba. A plataforma não valida se o endereço funciona.
Vitrine de produtos
Os produtos em destaque aparecem ao lado do player com botão de compra. Cada produto entra no fim da lista e a vitrine mostra o mais recente primeiro.
Gamificação
Quem assiste ganha pontos de fidelidade por tempo assistido: o app do cliente manda sinais de presença; cada sinal vale 30 segundos de tempo assistido (sinais com menos de 25 segundos de intervalo não contam, para evitar fraude), e a cada minuto inteiro o cliente ganha points_per_minute, até o teto da sessão. O administrador pode ainda abrir quizzes (pergunta com 2 a 4 alternativas e prêmio em pontos ou voucher) e liberar um voucher relâmpago para quem assistiu tempo suficiente.
Clipes
Depois da sessão, trechos da gravação podem ser anexados aos produtos apresentados, para aparecerem na galeria de vídeos da página do produto.
Chat
O chat da sessão é usado pelos espectadores na vitrine e não faz parte desta API administrativa.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/admin/live-sessions | Lista as sessões ao vivo de todos os sellers | admin |
| GET | /api/v1/admin/live-sessions/{id} | Devolve uma sessão com a vitrine de produtos | admin |
| POST | /api/v1/admin/live-sessions | Agenda uma sessão ao vivo para um seller | admin |
| PUT | /api/v1/admin/live-sessions/{id} | Altera título, horário e endereços de uma sessão | admin |
| DELETE | /api/v1/admin/live-sessions/{id} | Apaga uma sessão | admin |
| POST | /api/v1/admin/live-sessions/{id}/start | Coloca a sessão no ar | admin |
| POST | /api/v1/admin/live-sessions/{id}/end | Tira a sessão do ar | admin |
| POST | /api/v1/admin/live-sessions/{id}/cancel | Cancela uma sessão agendada ou no ar | admin |
| POST | /api/v1/admin/live-sessions/{id}/featured-products | Coloca um produto na vitrine da sessão | admin |
| DELETE | /api/v1/admin/live-sessions/{id}/featured-products/{productId} | Tira um produto da vitrine da sessão | admin |
| POST | /api/v1/admin/live-sessions/{id}/clips | Anexa um trecho da reprise a um produto | admin |
| GET | /api/v1/admin/live-sessions/{id}/gamification | Devolve a configuração de pontos e voucher relâmpago | admin |
| PUT | /api/v1/admin/live-sessions/{id}/gamification | Define pontos por minuto e o voucher relâmpago | admin |
| GET | /api/v1/admin/live-sessions/{id}/gamification/report | Devolve as métricas de engajamento da sessão | admin |
| POST | /api/v1/admin/live-sessions/{id}/quizzes | Cria uma pergunta de múltipla escolha em rascunho | admin |
| POST | /api/v1/admin/live-sessions/{id}/quizzes/{quizId}/open | Libera o quiz para os espectadores responderem | admin |
| POST | /api/v1/admin/live-sessions/{id}/quizzes/{quizId}/close | Encerra o quiz e paga os prêmios | admin |
| POST | /api/v1/admin/live-sessions/{id}/flash-voucher/reveal | Libera o voucher relâmpago configurado para a sessão | admin |
Erros comuns
- Tentar mudar o estado com
PUT{"status": "live"}: recusado com 409LIVE_SESSION_STATUS_NOT_UPDATABLE. - Criar uma sessão com
scheduled_atno passado (além de 5 minutos): recusado comSCHEDULED_AT_IN_PAST. - Enviar
positionao adicionar produto: é ignorado, o produto vai para o fim. - Criar clipe antes de encerrar a sessão ou sem
replay_url: recusado com 422. - Abrir um quiz duas vezes ou fechar um quiz já fechado: responde 500
quiz not found or ..., não 409. - Esperar
correct_indexna resposta do quiz quando ele vale 0: o campo é omitido.