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

Ciclo de vida da live

Coloca a sessão no ar, encerra a transmissão ou cancela a sessão.

Três ações mudam o estado. Todas devolvem a sessão atualizada e não recebem corpo. Cada ação confere o estado atual: pedir uma transição inválida devolve 409 e não altera nada.

Iniciar

POST/api/v1/vendor/live-sessions/{id}/startSeller

Coloca a sessão no ar

Move de scheduled para live e grava started_at. O horário agendado não é conferido: dá para iniciar antes ou depois dele.

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 POST "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/start" \
  -H "Authorization: Bearer $TOKEN"

200Sessão atualizada

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": "live",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "started_at": "2026-10-20T19:01:12Z"
}

Encerrar

POST/api/v1/vendor/live-sessions/{id}/endSeller

Encerra a transmissão

Move de live para ended e grava ended_at. Uma sessão scheduled não pode ser encerrada; cancele.

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 POST "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/end" \
  -H "Authorization: Bearer $TOKEN"

200Sessão atualizada

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": "ended",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "started_at": "2026-10-20T19:01:12Z",
  "ended_at": "2026-10-20T20:15:40Z"
}

Cancelar

POST/api/v1/vendor/live-sessions/{id}/cancelSeller

Cancela a sessão

Move de scheduled ou live para cancelled e grava ended_at. Sessões ended ou cancelled respondem 409.

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 POST "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/cancel" \
  -H "Authorization: Bearer $TOKEN"

200Sessão atualizada

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": "cancelled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "ended_at": "2026-10-19T10:00:00Z"
}

Campos da resposta

...object

A sessão completa, como em Criar sessão.

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"}`
409	`start` em sessão que não está `scheduled`.	`{"error":"LIVE_SESSION_NOT_SCHEDULED","detail":"live session is not in scheduled state"}`
409	`end` em sessão que não está `live`.	`{"error":"LIVE_SESSION_NOT_LIVE","detail":"live session is not in live state"}`
409	`cancel` em sessão `ended` ou `cancelled`.	`{"error":"LIVE_SESSION_ALREADY_TERMINAL","detail":"live session is already ended or cancelled"}`

Veja também

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

Ciclo de vida da live

Coloca a sessão no ar, encerra a transmissão ou cancela a sessão.

Três ações mudam o estado. Todas devolvem a sessão atualizada e não recebem corpo. Cada ação confere o estado atual: pedir uma transição inválida devolve 409 e não altera nada.

Iniciar

POST/api/v1/vendor/live-sessions/{id}/startSeller

Coloca a sessão no ar

Move de scheduled para live e grava started_at. O horário agendado não é conferido: dá para iniciar antes ou depois dele.

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 POST "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/start" \
  -H "Authorization: Bearer $TOKEN"

200Sessão atualizada

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": "live",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "started_at": "2026-10-20T19:01:12Z"
}

Encerrar

POST/api/v1/vendor/live-sessions/{id}/endSeller

Encerra a transmissão

Move de live para ended e grava ended_at. Uma sessão scheduled não pode ser encerrada; cancele.

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 POST "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/end" \
  -H "Authorization: Bearer $TOKEN"

200Sessão atualizada

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": "ended",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "started_at": "2026-10-20T19:01:12Z",
  "ended_at": "2026-10-20T20:15:40Z"
}

Cancelar

POST/api/v1/vendor/live-sessions/{id}/cancelSeller

Cancela a sessão

Move de scheduled ou live para cancelled e grava ended_at. Sessões ended ou cancelled respondem 409.

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 POST "$BASE_URL/api/v1/vendor/live-sessions/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/cancel" \
  -H "Authorization: Bearer $TOKEN"

200Sessão atualizada

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": "cancelled",
  "viewer_count_peak": 0,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "ended_at": "2026-10-19T10:00:00Z"
}

Campos da resposta

...object

A sessão completa, como em Criar sessão.

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"}`
409	`start` em sessão que não está `scheduled`.	`{"error":"LIVE_SESSION_NOT_SCHEDULED","detail":"live session is not in scheduled state"}`
409	`end` em sessão que não está `live`.	`{"error":"LIVE_SESSION_NOT_LIVE","detail":"live session is not in live state"}`
409	`cancel` em sessão `ended` ou `cancelled`.	`{"error":"LIVE_SESSION_ALREADY_TERMINAL","detail":"live session is already ended or cancelled"}`