VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Sessões ao vivo

Ciclo de vida da sessão

Inicia, encerra ou cancela uma sessão ao vivo.

Iniciar sessão

Muda a sessão de scheduled para live e grava started_at. A vitrine passa a mostrá-la como ao vivo e libera o chat e a pontuação por tempo assistido. Não precisa de corpo.

POST/api/v1/admin/live-sessions/{id}/startAdmin

Coloca a sessão no ar

Rota ligada ao módulo live-commerce: com o módulo desligado a resposta é 403. Exige token de administrador.

Parâmetros de caminho

iduuidobrigatório
Identificador da sessão.

Exemplo de requisição (Iniciar)

bash
curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/start" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Iniciar)

200Sessão no ar
json
{
  "id": "7ec34d19-64f7-4d36-92eb-dbb217448af7",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "title": "Lançamento da coleção de verão",
  "description": "Ao vivo com ofertas exclusivas",
  "scheduled_at": "2026-12-05T18:00:00Z",
  "embed_url": "https://www.youtube.com/watch?v=abc123",
  "replay_url": "",
  "status": "live",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T21:05:21.230055Z",
  "updated_at": "2026-10-11T21:05:21.230055Z",
  "started_at": "2026-12-05T18:00:12Z"
}

Campos da resposta

iduuid
Identificador da sessão.
vendor_iduuid
Seller que apresenta a sessão.
vendor_namestring
Nome do seller, para exibir.
titlestring
Título.
descriptionstring
Descrição.
scheduled_atstring
Data e hora prevista de início, RFC 3339.
started_atstring
Quando foi ao ar. Ausente antes de começar.
ended_atstring
Quando terminou ou foi cancelada. Ausente enquanto não terminou.
embed_urlstring
Endereço da transmissão (YouTube, Vimeo, Mux...) que a vitrine coloca num player.
replay_urlstring
Endereço da gravação, usado depois que a sessão termina. Vazio se não houver.
statusstring
scheduled, live, ended ou cancelled.
viewer_count_peakinteger
Maior número de espectadores simultâneos.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Iniciar)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um administrador.{"error":"insufficient permissions"}
403Módulo live-commerce desligado.{"error":"module_disabled","module":"live-commerce"}
404Não existe sessão com esse id, ou o id não é um UUID.{"error":"LIVE_SESSION_NOT_FOUND"}
409A sessão não está em scheduled.{"error":"LIVE_SESSION_NOT_SCHEDULED","detail":"live session is not in scheduled state"}

Encerrar sessão

Muda a sessão de live para ended e grava ended_at. Depois disso dá para informar replay_url e criar clipes. Não precisa de corpo.

POST/api/v1/admin/live-sessions/{id}/endAdmin

Tira a sessão do ar

Rota ligada ao módulo live-commerce: com o módulo desligado a resposta é 403. Exige token de administrador.

Parâmetros de caminho

iduuidobrigatório
Identificador da sessão.

Exemplo de requisição (Encerrar)

bash
curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/end" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Encerrar)

200Sessão encerrada
json
{
  "id": "7ec34d19-64f7-4d36-92eb-dbb217448af7",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "title": "Lançamento da coleção de verão",
  "description": "Ao vivo com ofertas exclusivas",
  "scheduled_at": "2026-12-05T18:00:00Z",
  "embed_url": "https://www.youtube.com/watch?v=abc123",
  "replay_url": "",
  "status": "ended",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T21:05:21.230055Z",
  "updated_at": "2026-10-11T21:05:21.230055Z",
  "started_at": "2026-12-05T18:00:12Z",
  "ended_at": "2026-12-05T19:02:40Z"
}

Campos da resposta

iduuid
Identificador da sessão.
vendor_iduuid
Seller que apresenta a sessão.
vendor_namestring
Nome do seller, para exibir.
titlestring
Título.
descriptionstring
Descrição.
scheduled_atstring
Data e hora prevista de início, RFC 3339.
started_atstring
Quando foi ao ar. Ausente antes de começar.
ended_atstring
Quando terminou ou foi cancelada. Ausente enquanto não terminou.
embed_urlstring
Endereço da transmissão (YouTube, Vimeo, Mux...) que a vitrine coloca num player.
replay_urlstring
Endereço da gravação, usado depois que a sessão termina. Vazio se não houver.
statusstring
scheduled, live, ended ou cancelled.
viewer_count_peakinteger
Maior número de espectadores simultâneos.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Encerrar)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um administrador.{"error":"insufficient permissions"}
403Módulo live-commerce desligado.{"error":"module_disabled","module":"live-commerce"}
404Não existe sessão com esse id, ou o id não é um UUID.{"error":"LIVE_SESSION_NOT_FOUND"}
409A sessão não está em live.{"error":"LIVE_SESSION_NOT_LIVE","detail":"live session is not in live state"}

Cancelar sessão

Muda a sessão para cancelled. Diferente de end, funciona também em uma sessão que ainda não começou. Uma sessão já encerrada ou cancelada não pode ser cancelada. Não precisa de corpo.

POST/api/v1/admin/live-sessions/{id}/cancelAdmin

Cancela uma sessão agendada ou no ar

Rota ligada ao módulo live-commerce: com o módulo desligado a resposta é 403. Exige token de administrador.

Parâmetros de caminho

iduuidobrigatório
Identificador da sessão.

Exemplo de requisição (Cancelar)

bash
curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Cancelar)

200Sessão cancelada
json
{
  "id": "7ec34d19-64f7-4d36-92eb-dbb217448af7",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "title": "Lançamento da coleção de verão",
  "description": "Ao vivo com ofertas exclusivas",
  "scheduled_at": "2026-12-05T18:00:00Z",
  "embed_url": "https://www.youtube.com/watch?v=abc123",
  "replay_url": "",
  "status": "cancelled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T21:05:21.230055Z",
  "updated_at": "2026-10-11T21:05:21.230055Z",
  "ended_at": "2026-12-04T10:00:00Z"
}

Campos da resposta

iduuid
Identificador da sessão.
vendor_iduuid
Seller que apresenta a sessão.
vendor_namestring
Nome do seller, para exibir.
titlestring
Título.
descriptionstring
Descrição.
scheduled_atstring
Data e hora prevista de início, RFC 3339.
started_atstring
Quando foi ao ar. Ausente antes de começar.
ended_atstring
Quando terminou ou foi cancelada. Ausente enquanto não terminou.
embed_urlstring
Endereço da transmissão (YouTube, Vimeo, Mux...) que a vitrine coloca num player.
replay_urlstring
Endereço da gravação, usado depois que a sessão termina. Vazio se não houver.
statusstring
scheduled, live, ended ou cancelled.
viewer_count_peakinteger
Maior número de espectadores simultâneos.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Cancelar)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um administrador.{"error":"insufficient permissions"}
403Módulo live-commerce desligado.{"error":"module_disabled","module":"live-commerce"}
404Não existe sessão com esse id, ou o id não é um UUID.{"error":"LIVE_SESSION_NOT_FOUND"}
409A sessão já está ended ou cancelled.{"error":"LIVE_SESSION_ALREADY_TERMINAL","detail":"live session is already ended or cancelled"}

Veja também

  • Produtos em destaque
  • Clipes da reprise
Anterior
Alterar e apagar sessão
Próxima
Produtos em destaque
Nesta página
  • Iniciar sessão
  • Exemplo de requisição (Iniciar)
  • Resposta (Iniciar)
  • Erros (Iniciar)
  • Encerrar sessão
  • Exemplo de requisição (Encerrar)
  • Resposta (Encerrar)
  • Erros (Encerrar)
  • Cancelar sessão
  • Exemplo de requisição (Cancelar)
  • Resposta (Cancelar)
  • Erros (Cancelar)
  • Veja também