Lives (Live Commerce)

Agende transmissões ao vivo, coloque-as no ar, encerre e destaque produtos durante a venda.

Live Commerce é a venda por transmissão ao vivo: o seller (lojista) agenda uma sessão, a vitrine mostra o player incorporado (um iframe do YouTube, Vimeo, Mux ou similar) com os produtos em destaque ao lado, e os clientes compram sem sair da página. Estas rotas, em /api/v1/vendor/live-sessions, gerenciam apenas as sessões do próprio seller. A plataforma não transmite vídeo: ela guarda a URL do player que você já tem.

Como funciona

scheduled→live→ended

`status`	Significado	Como chega aqui
`scheduled`	Agendada. Aparece como "em breve" na vitrine.	Criação.
`live`	No ar. `started_at` é gravado.	`POST .../start`
`ended`	Encerrada. `ended_at` é gravado.	`POST .../end` (só de `live`)
`cancelled`	Cancelada. `ended_at` também é gravado.	`POST .../cancel` (de `scheduled` ou `live`)

Agendar
Criar sessão com título, horário e a URL do player.
Escolher a vitrine
Produtos em destaque escolhe o que aparece ao lado do vídeo.
Ir ao ar e encerrar
Ciclo de vida: start na hora da transmissão, end no final.
Publicar a gravação
Alterar sessão com replay_url.

Conceitos-chave

Quem vê o quê

O seller só lista e altera as suas sessões. Pedir a sessão de outro seller responde 403 SESSION_OWNERSHIP_REQUIRED. O administrador da loja gerencia as sessões de todos os sellers por /api/v1/admin/live-sessions. Os clientes assistem pelas rotas públicas da vitrine.

Privilégios

Ler, criar, alterar, apagar e mudar o estado exigem um privilégio do grupo configurações do seller (por exemplo vendor_settings). Adicionar e remover produtos em destaque exigem um privilégio do grupo catálogo (por exemplo vendor_catalog). O dono da loja tem todos.

Datas

Todas as datas são RFC 3339. Envie scheduled_at com fuso (2026-10-20T19:00:00-03:00) ou em UTC (...Z); a resposta sai em UTC.

Endpoints

Método	Caminho	Para que serve	Autenticação
GET	`/api/v1/vendor/live-sessions`	Lista as sessões do seller.	vendor
GET	`/api/v1/vendor/live-sessions/{id}`	Devolve uma sessão com os destaques.	vendor
POST	`/api/v1/vendor/live-sessions`	Cria uma sessão agendada.	vendor
PUT	`/api/v1/vendor/live-sessions/{id}`	Altera campos da sessão.	vendor
DELETE	`/api/v1/vendor/live-sessions/{id}`	Apaga a sessão.	vendor
POST	`/api/v1/vendor/live-sessions/{id}/start`	Coloca no ar.	vendor
POST	`/api/v1/vendor/live-sessions/{id}/end`	Encerra a transmissão.	vendor
POST	`/api/v1/vendor/live-sessions/{id}/cancel`	Cancela a sessão.	vendor
POST	`/api/v1/vendor/live-sessions/{id}/featured-products`	Destaca um produto.	vendor
DELETE	`/api/v1/vendor/live-sessions/{id}/featured-products/{productId}`	Remove um destaque.	vendor

Erros comuns

Agendar no passado. 400 SCHEDULED_AT_IN_PAST. A tolerância é de 5 minutos.
Mudar o estado com PUT. 409 LIVE_SESSION_STATUS_NOT_UPDATABLE; use start, end ou cancel.
Encerrar uma sessão que não foi iniciada. end só vale para live; de scheduled use cancel.
Achar que position ordena os destaques. O campo é aceito e ignorado: cada produto novo entra no fim e a vitrine mostra o mais novo primeiro.
Esperar featured_products na lista. Só a leitura de uma sessão traz os destaques.
Apagar uma sessão ao vivo. DELETE não confere o estado: a sessão some, com o chat.

Próximos passos

Criar sessão

Agende a primeira live.

Ciclo de vida

Iniciar, encerrar e cancelar.

Produtos em destaque

A vitrine ao lado do vídeo.