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

Listar, consultar e criar sessões

Lista as sessões ao vivo, consulta uma com a vitrine de produtos e agenda uma nova.

Listar sessões ao vivo

Devolve as sessões de live commerce (transmissões ao vivo com venda de produtos) de todos os sellers, com filtro por seller e por estado. A lista não traz a vitrine de produtos de cada sessão; para isso consulte uma sessão.

GET/api/v1/admin/live-sessionsAdmin

Lista as sessões ao vivo de todos os sellers

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

Parâmetros de consulta

vendor_iduuid
Só sessões desse seller.
statusstring
scheduledliveendedcancelled
Só sessões nesse estado.
limitintegerpadrão: 50
Itens por chamada.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição (Listar sessões)

bash
curl "$BASE_URL/api/v1/admin/live-sessions?status=scheduled&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar sessões)

200Sessões
json
{
  "sessions": [
    {
      "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": "scheduled",
      "viewer_count_peak": 0,
      "created_at": "2026-10-11T21:05:21.230055Z",
      "updated_at": "2026-10-11T21:05:21.230055Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Sessões da consulta.

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.
totalinteger
Total que atende ao filtro (não só os devolvidos).

Erros (Listar sessões)

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"}
500Falha de banco.{"error":"LIVE_SESSIONS_LIST_FAILED","detail":"..."}

Consultar sessão ao vivo

Devolve a sessão completa, incluindo featured_products.

GET/api/v1/admin/live-sessions/{id}Admin

Devolve uma sessão com a vitrine de produtos

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 (Consultar sessão)

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

Resposta (Consultar sessão)

200Sessão
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": "scheduled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T21:05:21.230055Z",
  "updated_at": "2026-10-11T21:05:21.230055Z",
  "featured_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "position": 1,
      "name": "Camiseta Azul",
      "sku": "CAM-AZ-01",
      "price_cents": 7990,
      "image_url": "/uploads/camiseta.png",
      "slug": "camiseta-azul"
    }
  ]
}

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.
featured_productsarray
Vitrine de produtos da sessão. Só aparece na consulta de uma sessão, não na lista. Cada item tem product_id, position, name, sku, price_cents (centavos), image_url e slug.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Consultar sessão)

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"}

Criar sessão ao vivo

Cria a sessão no estado scheduled. A transmissão em si acontece num serviço externo (YouTube, Vimeo, Mux...): a plataforma só guarda o endereço em embed_url, que a vitrine coloca num player. Depois de criar, cadastre os produtos em destaque e, na hora, chame start.

POST/api/v1/admin/live-sessionsAdmin

Agenda uma sessão ao vivo para um seller

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

Corpo da requisição

vendor_iduuidobrigatório
Seller que apresenta a sessão.
titlestringobrigatório
Título. Não pode ficar vazio.
scheduled_atstringobrigatório
Início previsto, RFC 3339. Não pode estar no passado (a tolerância é de 5 minutos para diferença de relógio).
descriptionstring
Descrição.
embed_urlstring
Endereço da transmissão.
replay_urlstring
Endereço da gravação, se já existir.

Exemplo de requisição (Criar sessão)

bash
curl -X POST "$BASE_URL/api/v1/admin/live-sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "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"
}'

Resposta (Criar sessão)

201Sessão criada
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": "scheduled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T21:05:21.230055Z",
  "updated_at": "2026-10-11T21:05:21.230055Z"
}

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 (Criar sessão)

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"}
400Corpo inválido, title, vendor_id ou scheduled_at ausentes, ou scheduled_at no passado (código SCHEDULED_AT_IN_PAST). A maioria das validações responde LIVE_SESSION_CREATE_FAILED com o motivo em detail.{"error":"LIVE_SESSION_CREATE_FAILED","detail":"vendor_id is required"}

Veja também

  • Alterar e apagar sessão
  • Ciclo de vida
Anterior
Sessões ao vivo
Próxima
Alterar e apagar sessão
Nesta página
  • Listar sessões ao vivo
  • Exemplo de requisição (Listar sessões)
  • Resposta (Listar sessões)
  • Erros (Listar sessões)
  • Consultar sessão ao vivo
  • Exemplo de requisição (Consultar sessão)
  • Resposta (Consultar sessão)
  • Erros (Consultar sessão)
  • Criar sessão ao vivo
  • Exemplo de requisição (Criar sessão)
  • Resposta (Criar sessão)
  • Erros (Criar sessão)
  • Veja também