API atual/Referência completa/Lives (Live Commerce)

Listar e consultar lives

Lista as sessões do seller e devolve uma sessão com os produtos em destaque.

A lista serve para a tela de gerenciamento; a leitura de uma sessão serve para a edição, porque só ela traz os produtos em destaque.

Listar sessões

GET/api/v1/vendor/live-sessionsSeller

Lista as sessões do seller

Devolve no máximo as 100 primeiras sessões, da mais recente para a mais antiga pelo horário agendado. Não há paginação; use status para reduzir.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de consulta

statusstring

scheduledliveendedcancelled

Filtra por estado. Um valor desconhecido devolve lista vazia, não erro.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/live-sessions?status=scheduled" \
  -H "Authorization: Bearer $TOKEN"

200Sessões

json

{
  "sessions": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "title": "Lançamento da coleção de verão",
      "description": "Mostramos as novidades e respondemos perguntas ao vivo.",
      "scheduled_at": "2026-10-20T19:00:00Z",
      "embed_url": "https://www.youtube.com/embed/EXEMPLO",
      "replay_url": "",
      "status": "scheduled",
      "viewer_count_peak": 0,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Sessões, sem featured_products.

iduuid

Id da sessão.

vendor_iduuid

Seller dono da sessão.

vendor_namestring

Nome do seller. Ausente se vazio.

titlestring

Título.

descriptionstring

Descrição.

scheduled_atstring

Horário agendado (RFC 3339, UTC).

started_atstring

Quando foi ao ar. Ausente até iniciar.

ended_atstring

Quando saiu do ar, ou quando foi cancelada. Ausente antes disso.

embed_urlstring

URL do player que a vitrine mostra num iframe. A plataforma grava o texto como veio.

replay_urlstring

URL da gravação, para trocar o player depois que a sessão termina.

statusstring

scheduledliveendedcancelled

Estado: scheduled, live, ended ou cancelled.

viewer_count_peakinteger

Pico de espectadores simultâneos.

created_atstring

Criação (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

Total de sessões que atendem ao filtro. Pode ser maior que 100.

Consultar uma sessão

GET/api/v1/vendor/live-sessions/{id}Seller

Devolve uma sessão

Inclui featured_products. Só aparecem os produtos ativos e visíveis na vitrine: um produto desativado, apagado, de seller inativo ou sem estoque (quando a loja esconde esgotados) não é listado, mesmo ainda ligado à sessão.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

200Sessão com destaques

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "title": "Lançamento da coleção de verão",
  "description": "Mostramos as novidades e respondemos perguntas ao vivo.",
  "scheduled_at": "2026-10-20T19:00:00Z",
  "embed_url": "https://www.youtube.com/embed/EXEMPLO",
  "replay_url": "",
  "status": "scheduled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "featured_products": [
    {
      "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
      "position": 1,
      "name": "Chinelo Verão Azul",
      "sku": "CHN-AZ-39",
      "price_cents": 4990,
      "image_url": "https://exemplo.io.venddor.com.br/uploads/chinelo.jpg",
      "slug": "chinelo-verao-azul"
    }
  ]
}

Campos da resposta

...object

Os campos da sessão, como acima, mais featured_products.

featured_productsarray

Produtos em destaque, do mais novo para o mais antigo.

product_iduuid

Id do produto.

positioninteger

Ordem em que foi adicionado (maior = mais novo).

namestring

Nome.

skustring

SKU.

price_centsinteger

Preço em centavos.

image_urlstring

Imagem principal.

slugstring

Slug do produto na vitrine.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário do seller (equipe) não tem nenhum dos privilégios exigidos. O dono da loja nunca recebe este erro.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}`
403	O módulo Live Commerce está desligado nesta loja.	`{"error":"module_disabled","module":"live-commerce"}`
404	O id não é um UUID ou a sessão não existe.	`{"error":"LIVE_SESSION_NOT_FOUND"}`
403	A sessão pertence a outro seller.	`{"error":"SESSION_OWNERSHIP_REQUIRED"}`

Veja também

Listar e consultar lives

Lista as sessões do seller e devolve uma sessão com os produtos em destaque.

A lista serve para a tela de gerenciamento; a leitura de uma sessão serve para a edição, porque só ela traz os produtos em destaque.

Listar sessões

GET/api/v1/vendor/live-sessionsSeller

Lista as sessões do seller

Devolve no máximo as 100 primeiras sessões, da mais recente para a mais antiga pelo horário agendado. Não há paginação; use status para reduzir.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de consulta

statusstring

scheduledliveendedcancelled

Filtra por estado. Um valor desconhecido devolve lista vazia, não erro.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/live-sessions?status=scheduled" \
  -H "Authorization: Bearer $TOKEN"

200Sessões

json

{
  "sessions": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "title": "Lançamento da coleção de verão",
      "description": "Mostramos as novidades e respondemos perguntas ao vivo.",
      "scheduled_at": "2026-10-20T19:00:00Z",
      "embed_url": "https://www.youtube.com/embed/EXEMPLO",
      "replay_url": "",
      "status": "scheduled",
      "viewer_count_peak": 0,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Sessões, sem featured_products.

iduuid

Id da sessão.

vendor_iduuid

Seller dono da sessão.

vendor_namestring

Nome do seller. Ausente se vazio.

titlestring

Título.

descriptionstring

Descrição.

scheduled_atstring

Horário agendado (RFC 3339, UTC).

started_atstring

Quando foi ao ar. Ausente até iniciar.

ended_atstring

Quando saiu do ar, ou quando foi cancelada. Ausente antes disso.

embed_urlstring

URL do player que a vitrine mostra num iframe. A plataforma grava o texto como veio.

replay_urlstring

URL da gravação, para trocar o player depois que a sessão termina.

statusstring

scheduledliveendedcancelled

Estado: scheduled, live, ended ou cancelled.

viewer_count_peakinteger

Pico de espectadores simultâneos.

created_atstring

Criação (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

Total de sessões que atendem ao filtro. Pode ser maior que 100.

Consultar uma sessão

GET/api/v1/vendor/live-sessions/{id}Seller

Devolve uma sessão

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

200Sessão com destaques

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "title": "Lançamento da coleção de verão",
  "description": "Mostramos as novidades e respondemos perguntas ao vivo.",
  "scheduled_at": "2026-10-20T19:00:00Z",
  "embed_url": "https://www.youtube.com/embed/EXEMPLO",
  "replay_url": "",
  "status": "scheduled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "featured_products": [
    {
      "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
      "position": 1,
      "name": "Chinelo Verão Azul",
      "sku": "CHN-AZ-39",
      "price_cents": 4990,
      "image_url": "https://exemplo.io.venddor.com.br/uploads/chinelo.jpg",
      "slug": "chinelo-verao-azul"
    }
  ]
}

Campos da resposta

...object

Os campos da sessão, como acima, mais featured_products.

featured_productsarray

Produtos em destaque, do mais novo para o mais antigo.

product_iduuid

Id do produto.

positioninteger

Ordem em que foi adicionado (maior = mais novo).

namestring

Nome.

skustring

SKU.

price_centsinteger

Preço em centavos.

image_urlstring

Imagem principal.

slugstring

Slug do produto na vitrine.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário do seller (equipe) não tem nenhum dos privilégios exigidos. O dono da loja nunca recebe este erro.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}`
403	O módulo Live Commerce está desligado nesta loja.	`{"error":"module_disabled","module":"live-commerce"}`
404	O id não é um UUID ou a sessão não existe.	`{"error":"LIVE_SESSION_NOT_FOUND"}`
403	A sessão pertence a outro seller.	`{"error":"SESSION_OWNERSHIP_REQUIRED"}`