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

POSTCriar sessão

Agenda uma nova sessão de live para o seller, no estado agendada.

Cria a sessão com o título, o horário e a URL do player. A sessão nasce scheduled. O seller dono é sempre o do token; um vendor_id enviado no corpo é ignorado.

POST/api/v1/vendor/live-sessionsSeller

Cria uma sessão de live

Cabeçalhos

Authorizationstringobrigatório

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

Corpo da requisição

titlestringobrigatório

Título. Não pode ser vazio nem só espaços.

scheduled_atstringobrigatório

Horário agendado, RFC 3339. Não pode estar mais de 5 minutos no passado.

descriptionstringpadrão:

Descrição mostrada na vitrine.

embed_urlstringpadrão:

URL do player incorporável. Pode ficar vazia e ser preenchida depois com PUT.

replay_urlstringpadrão:

URL da gravação, se já existir.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/live-sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Resposta

201Sessão criada

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

Campos da resposta

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).

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"}`
400	JSON inválido ou `scheduled_at` que não é RFC 3339.	`{"error":"INVALID_BODY","detail":"parsing time ..."}`
400	`title` ou `scheduled_at` ausente.	`{"error":"LIVE_SESSION_CREATE_FAILED","detail":"title is required"}`
400	`scheduled_at` mais de 5 minutos no passado.	`{"error":"SCHEDULED_AT_IN_PAST","detail":"scheduled_at must be in the future"}`

Veja também