API atual/Referência completa/Lives de vendas

Lives no ar e detalhe

Lista as lives no ar e as próximas, e abre uma live com os produtos em destaque.

Use a lista para montar a vitrine de lives (um carrossel "ao vivo agora") e o detalhe para abrir a página da transmissão. A lista traz o resumo de cada live; o detalhe acrescenta os produtos em destaque, aqueles que o organizador fixou para comprar durante a live.

GET/api/v1/storefront/live-sessions/activePública

Listar lives no ar e próximas

Parâmetros de consulta

limitintegerpadrão: 24

Máximo de lives devolvidas, de 1 a 100. Valor fora dessa faixa ou que não seja número é ignorado e vale 24.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/live-sessions/active?limit=10"

Resposta

200Lives encontradas

json

{
  "sessions": [
    {
      "id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Casa do Café",
      "title": "Lançamento da linha de cafés especiais",
      "description": "Degustação e ofertas exclusivas para quem assiste.",
      "scheduled_at": "2026-10-11T19:00:00Z",
      "started_at": "2026-10-11T19:02:10Z",
      "embed_url": "https://www.youtube.com/embed/abc123",
      "replay_url": "",
      "status": "live",
      "viewer_count_peak": 128,
      "created_at": "2026-10-08T14:20:00Z",
      "updated_at": "2026-10-11T19:02:10Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Lives encontradas. Lista vazia ([]) quando não há nenhuma.

sessions[].iduuid

Id da live.

sessions[].vendor_iduuid

Seller dono da live.

sessions[].vendor_namestring

Nome fantasia do seller. Some quando o seller não existe mais.

sessions[].titlestring

Título da live.

sessions[].descriptionstring

Descrição. Pode ser vazia.

sessions[].scheduled_atstring

Quando a live foi agendada (RFC 3339).

sessions[].started_atstring

Quando começou. Só existe depois que o organizador inicia.

sessions[].ended_atstring

Quando terminou. Só existe em lives encerradas.

sessions[].embed_urlstring

URL do player incorporável. Pode ser vazia.

sessions[].replay_urlstring

URL da gravação. Costuma ser preenchida depois que a live termina.

sessions[].statusstring

scheduledliveendedcancelled

Estado da live. Na lista, só live ou scheduled.

sessions[].viewer_count_peakinteger

Maior número de espectadores simultâneos registrado.

sessions[].created_atstring

Criação do registro (RFC 3339).

sessions[].updated_atstring

Última alteração (RFC 3339).

totalinteger

Quantidade de lives nesta resposta (não é o total da loja).

Erros

Status	Quando	Corpo
403	O módulo `live-commerce` está desligado na loja.	`{"error":"module_disabled","module":"live-commerce"}`
500	Falha ao consultar as lives.	`{"error":"LIVE_SESSIONS_LIST_FAILED","detail":"..."}`

GET/api/v1/storefront/live-sessions/{id}Pública

Detalhar uma live

Parâmetros de caminho

iduuidobrigatório

Id da live (sessions[].id).

bash

curl "$BASE_URL/api/v1/storefront/live-sessions/$SESSION_ID"

200Live encontrada

json

{
  "id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Casa do Café",
  "title": "Lançamento da linha de cafés especiais",
  "description": "Degustação e ofertas exclusivas para quem assiste.",
  "scheduled_at": "2026-10-11T19:00:00Z",
  "started_at": "2026-10-11T19:02:10Z",
  "embed_url": "https://www.youtube.com/embed/abc123",
  "replay_url": "",
  "status": "live",
  "viewer_count_peak": 128,
  "created_at": "2026-10-08T14:20:00Z",
  "updated_at": "2026-10-11T19:02:10Z",
  "featured_products": [
    {
      "product_id": "0f6c3b0a-6a52-4c53-8d2c-0e1a1d7a9b21",
      "position": 0,
      "name": "Café Especial 250 g",
      "sku": "CAFE-250",
      "price_cents": 4990,
      "image_url": "/uploads/produtos/cafe-250.jpg",
      "slug": "cafe-especial-250g"
    }
  ]
}

Campos da resposta

(campos da live)object

Os mesmos campos da lista.

featured_productsarray

Produtos em destaque, do maior position para o menor. Ausente quando a live não fixou nenhum, ou quando a leitura dos destaques falha (nesse caso a live vem sem eles, sem erro).

featured_products[].product_iduuid

Id do produto no catálogo.

featured_products[].positioninteger

Posição definida pelo organizador. A lista vem ordenada do maior para o menor valor.

featured_products[].namestring

Nome do produto.

featured_products[].skustring

SKU do produto.

featured_products[].price_centsinteger

Preço em centavos (4990 = R$ 49,90).

featured_products[].image_urlstring

Imagem principal. Pode ser vazia.

featured_products[].slugstring

Slug para montar o link do produto na vitrine.

Erros

Status	Quando	Corpo
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
404	O id não é um UUID ou não existe.	`{"error":"LIVE_SESSION_NOT_FOUND"}`
500	Falha ao ler a live.	`{"error":"LIVE_SESSION_GET_FAILED","detail":"..."}`

Veja também

Lives no ar e detalhe

Lista as lives no ar e as próximas, e abre uma live com os produtos em destaque.

GET/api/v1/storefront/live-sessions/activePública

Listar lives no ar e próximas

Parâmetros de consulta

limitintegerpadrão: 24

Máximo de lives devolvidas, de 1 a 100. Valor fora dessa faixa ou que não seja número é ignorado e vale 24.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/live-sessions/active?limit=10"

Resposta

200Lives encontradas

json

{
  "sessions": [
    {
      "id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Casa do Café",
      "title": "Lançamento da linha de cafés especiais",
      "description": "Degustação e ofertas exclusivas para quem assiste.",
      "scheduled_at": "2026-10-11T19:00:00Z",
      "started_at": "2026-10-11T19:02:10Z",
      "embed_url": "https://www.youtube.com/embed/abc123",
      "replay_url": "",
      "status": "live",
      "viewer_count_peak": 128,
      "created_at": "2026-10-08T14:20:00Z",
      "updated_at": "2026-10-11T19:02:10Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Lives encontradas. Lista vazia ([]) quando não há nenhuma.

sessions[].iduuid

Id da live.

sessions[].vendor_iduuid

Seller dono da live.

sessions[].vendor_namestring

Nome fantasia do seller. Some quando o seller não existe mais.

sessions[].titlestring

Título da live.

sessions[].descriptionstring

Descrição. Pode ser vazia.

sessions[].scheduled_atstring

Quando a live foi agendada (RFC 3339).

sessions[].started_atstring

Quando começou. Só existe depois que o organizador inicia.

sessions[].ended_atstring

Quando terminou. Só existe em lives encerradas.

sessions[].embed_urlstring

URL do player incorporável. Pode ser vazia.

sessions[].replay_urlstring

URL da gravação. Costuma ser preenchida depois que a live termina.

sessions[].statusstring

scheduledliveendedcancelled

Estado da live. Na lista, só live ou scheduled.

sessions[].viewer_count_peakinteger

Maior número de espectadores simultâneos registrado.

sessions[].created_atstring

Criação do registro (RFC 3339).

sessions[].updated_atstring

Última alteração (RFC 3339).

totalinteger

Quantidade de lives nesta resposta (não é o total da loja).

Erros

Status	Quando	Corpo
403	O módulo `live-commerce` está desligado na loja.	`{"error":"module_disabled","module":"live-commerce"}`
500	Falha ao consultar as lives.	`{"error":"LIVE_SESSIONS_LIST_FAILED","detail":"..."}`

GET/api/v1/storefront/live-sessions/{id}Pública

Detalhar uma live

Parâmetros de caminho

iduuidobrigatório

Id da live (sessions[].id).

bash

curl "$BASE_URL/api/v1/storefront/live-sessions/$SESSION_ID"

200Live encontrada

json

{
  "id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Casa do Café",
  "title": "Lançamento da linha de cafés especiais",
  "description": "Degustação e ofertas exclusivas para quem assiste.",
  "scheduled_at": "2026-10-11T19:00:00Z",
  "started_at": "2026-10-11T19:02:10Z",
  "embed_url": "https://www.youtube.com/embed/abc123",
  "replay_url": "",
  "status": "live",
  "viewer_count_peak": 128,
  "created_at": "2026-10-08T14:20:00Z",
  "updated_at": "2026-10-11T19:02:10Z",
  "featured_products": [
    {
      "product_id": "0f6c3b0a-6a52-4c53-8d2c-0e1a1d7a9b21",
      "position": 0,
      "name": "Café Especial 250 g",
      "sku": "CAFE-250",
      "price_cents": 4990,
      "image_url": "/uploads/produtos/cafe-250.jpg",
      "slug": "cafe-especial-250g"
    }
  ]
}

Campos da resposta

(campos da live)object

Os mesmos campos da lista.

featured_productsarray

Produtos em destaque, do maior position para o menor. Ausente quando a live não fixou nenhum, ou quando a leitura dos destaques falha (nesse caso a live vem sem eles, sem erro).

featured_products[].product_iduuid

Id do produto no catálogo.

featured_products[].positioninteger

Posição definida pelo organizador. A lista vem ordenada do maior para o menor valor.

featured_products[].namestring

Nome do produto.

featured_products[].skustring

SKU do produto.

featured_products[].price_centsinteger

Preço em centavos (4990 = R$ 49,90).

featured_products[].image_urlstring

Imagem principal. Pode ser vazia.

featured_products[].slugstring

Slug para montar o link do produto na vitrine.

Erros

Status	Quando	Corpo
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
404	O id não é um UUID ou não existe.	`{"error":"LIVE_SESSION_NOT_FOUND"}`
500	Falha ao ler a live.	`{"error":"LIVE_SESSION_GET_FAILED","detail":"..."}`