API atual/Referência completa/Sessões ao vivo

Quizzes e voucher relâmpago

Cria, abre e fecha quizzes durante a live e revela o voucher relâmpago.

Criar quiz

Prepara um quiz para a sessão: pergunta, de 2 a 4 alternativas, qual é a correta e o prêmio. O quiz nasce em draft, invisível aos espectadores, até você abri-lo com open. A resposta correta nunca é enviada aos espectadores enquanto o quiz está aberto.

POST/api/v1/admin/live-sessions/{id}/quizzesAdmin

Cria uma pergunta de múltipla escolha em rascunho

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.

Corpo da requisição

questionstringobrigatório

Pergunta.

optionsarrayobrigatório

De 2 a 4 alternativas (strings).

correct_indexintegerobrigatório

Posição da alternativa correta em options, começando em 0.

reward_typestringpadrão: points

pointsvoucher

Tipo de prêmio. Outro valor vira points.

reward_pointsinteger

Pontos para cada espectador que acertar (quando reward_type é points).

reward_voucherobject

Quando reward_type é voucher: voucher_type, value e valid_days do voucher emitido para cada premiado.

reward_first_kinteger

Quando o prêmio é voucher: quantos dos primeiros a acertar ganham.

Exemplo de requisição (Criar quiz)

bash

curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/quizzes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "Qual cor da camiseta em destaque?",
  "options": [
    "Azul",
    "Verde"
  ],
  "correct_index": 0,
  "reward_type": "points",
  "reward_points": 10
}'

Resposta (Criar quiz)

201Quiz criado

json

{
  "id": "ecc3e7ba-d655-4955-abf8-39081e5a0ffd",
  "session_id": "7ec34d19-64f7-4d36-92eb-dbb217448af7",
  "question": "Qual cor da camiseta em destaque?",
  "options": [
    "Azul",
    "Verde"
  ],
  "reward_type": "points",
  "reward_points": 10,
  "reward_first_k": 0,
  "status": "draft"
}

Campos da resposta

iduuid

Identificador do quiz (use em open e close).

session_iduuid

Sessão.

questionstring

Pergunta.

optionsarray

Alternativas.

correct_indexinteger

Índice da alternativa correta. Omitido quando vale 0, então a ausência do campo significa que a correta é a primeira.

reward_typestring

points ou voucher.

reward_pointsinteger

Pontos por acerto.

reward_first_kinteger

Quantos premiados no modo voucher.

statusstring

draft, open ou closed.

opens_atstring

Abertura, RFC 3339. Ausente em rascunho.

closes_atstring

Fim previsto, RFC 3339. Ausente em rascunho.

Erros (Criar quiz)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
404	Gamificação indisponível.	`{"error":"gamification not available"}`
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
500	Pergunta vazia, menos de 2 ou mais de 4 alternativas, ou `correct_index` fora do intervalo. A plataforma responde 500 em vez de 400; leia o `detail`.	`{"error":"gamification error","detail":"quiz needs a question and 2-4 options"}`

Abrir quiz

Abre um quiz em draft por uma duração: os espectadores veem a pergunta e as alternativas (sem a resposta certa) e cada um pode responder uma única vez. O quiz fecha sozinho para novas respostas ao fim do prazo, mas o prêmio só é pago quando você chama close.

POST/api/v1/admin/live-sessions/{id}/quizzes/{quizId}/openAdmin

Libera o quiz para os espectadores responderem

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.

quizIduuidobrigatório

Quiz a abrir.

Corpo da requisição

duration_secondsintegerpadrão: 60

Quantos segundos o quiz fica aberto.

Exemplo de requisição (Abrir quiz)

bash

curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/quizzes/ecc3e7ba-d655-4955-abf8-39081e5a0ffd/open" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "duration_seconds": 30
}'

Resposta (Abrir quiz)

200Quiz aberto

json

{
  "message": "quiz opened"
}

Erros (Abrir quiz)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
500	O quiz não existe nesta sessão ou não está em `draft` (por exemplo já foi aberto). A plataforma responde 500 em vez de 409.	`{"error":"gamification error","detail":"quiz not found or not draft"}`

Fechar quiz e pagar prêmios

Fecha o quiz, revela a resposta certa aos espectadores e paga os prêmios: com points, os pontos vão para todos que acertaram; com voucher, um voucher vai para os reward_first_k primeiros que acertaram, na ordem das respostas. Não precisa de corpo.

POST/api/v1/admin/live-sessions/{id}/quizzes/{quizId}/closeAdmin

Encerra o quiz e paga os prêmios

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.

quizIduuidobrigatório

Quiz a fechar.

Exemplo de requisição (Fechar quiz)

bash

curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/quizzes/ecc3e7ba-d655-4955-abf8-39081e5a0ffd/close" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Fechar quiz)

200Quiz fechado

json

{
  "message": "quiz closed"
}

Erros (Fechar quiz)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
500	O quiz não existe nesta sessão ou já foi fechado.	`{"error":"gamification error","detail":"quiz not found or already closed"}`

Revelar voucher relâmpago

Marca o voucher relâmpago como revelado e avisa os espectadores em tempo real. A partir daí, quem já assistiu flash_unlock_after_seconds pode resgatá-lo. Exige que flash_voucher_id tenha sido configurado. Não precisa de corpo.

POST/api/v1/admin/live-sessions/{id}/flash-voucher/revealAdmin

Libera o voucher relâmpago configurado para a sessão

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 (Revelar voucher)

bash

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

Resposta (Revelar voucher)

200Voucher revelado

json

{
  "message": "flash voucher revealed"
}

Erros (Revelar voucher)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
500	Não há voucher relâmpago configurado na sessão. A plataforma responde 500 em vez de 409.	`{"error":"gamification error","detail":"no flash voucher configured"}`

Veja também

API atual/Referência completa/Sessões ao vivo

Quizzes e voucher relâmpago

Cria, abre e fecha quizzes durante a live e revela o voucher relâmpago.

Criar quiz

POST/api/v1/admin/live-sessions/{id}/quizzesAdmin

Cria uma pergunta de múltipla escolha em rascunho

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.

Corpo da requisição

questionstringobrigatório

Pergunta.

optionsarrayobrigatório

De 2 a 4 alternativas (strings).

correct_indexintegerobrigatório

Posição da alternativa correta em options, começando em 0.

reward_typestringpadrão: points

pointsvoucher

Tipo de prêmio. Outro valor vira points.

reward_pointsinteger

Pontos para cada espectador que acertar (quando reward_type é points).

reward_voucherobject

Quando reward_type é voucher: voucher_type, value e valid_days do voucher emitido para cada premiado.

reward_first_kinteger

Quando o prêmio é voucher: quantos dos primeiros a acertar ganham.

Exemplo de requisição (Criar quiz)

bash

curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/quizzes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "Qual cor da camiseta em destaque?",
  "options": [
    "Azul",
    "Verde"
  ],
  "correct_index": 0,
  "reward_type": "points",
  "reward_points": 10
}'

Resposta (Criar quiz)

201Quiz criado

json

{
  "id": "ecc3e7ba-d655-4955-abf8-39081e5a0ffd",
  "session_id": "7ec34d19-64f7-4d36-92eb-dbb217448af7",
  "question": "Qual cor da camiseta em destaque?",
  "options": [
    "Azul",
    "Verde"
  ],
  "reward_type": "points",
  "reward_points": 10,
  "reward_first_k": 0,
  "status": "draft"
}

Campos da resposta

iduuid

Identificador do quiz (use em open e close).

session_iduuid

Sessão.

questionstring

Pergunta.

optionsarray

Alternativas.

correct_indexinteger

Índice da alternativa correta. Omitido quando vale 0, então a ausência do campo significa que a correta é a primeira.

reward_typestring

points ou voucher.

reward_pointsinteger

Pontos por acerto.

reward_first_kinteger

Quantos premiados no modo voucher.

statusstring

draft, open ou closed.

opens_atstring

Abertura, RFC 3339. Ausente em rascunho.

closes_atstring

Fim previsto, RFC 3339. Ausente em rascunho.

Erros (Criar quiz)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
404	Gamificação indisponível.	`{"error":"gamification not available"}`
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
500	Pergunta vazia, menos de 2 ou mais de 4 alternativas, ou `correct_index` fora do intervalo. A plataforma responde 500 em vez de 400; leia o `detail`.	`{"error":"gamification error","detail":"quiz needs a question and 2-4 options"}`

Abrir quiz

POST/api/v1/admin/live-sessions/{id}/quizzes/{quizId}/openAdmin

Libera o quiz para os espectadores responderem

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.

quizIduuidobrigatório

Quiz a abrir.

Corpo da requisição

duration_secondsintegerpadrão: 60

Quantos segundos o quiz fica aberto.

Exemplo de requisição (Abrir quiz)

bash

curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/quizzes/ecc3e7ba-d655-4955-abf8-39081e5a0ffd/open" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "duration_seconds": 30
}'

Resposta (Abrir quiz)

200Quiz aberto

json

{
  "message": "quiz opened"
}

Erros (Abrir quiz)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
500	O quiz não existe nesta sessão ou não está em `draft` (por exemplo já foi aberto). A plataforma responde 500 em vez de 409.	`{"error":"gamification error","detail":"quiz not found or not draft"}`

Fechar quiz e pagar prêmios

POST/api/v1/admin/live-sessions/{id}/quizzes/{quizId}/closeAdmin

Encerra o quiz e paga os prêmios

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.

quizIduuidobrigatório

Quiz a fechar.

Exemplo de requisição (Fechar quiz)

bash

curl -X POST "$BASE_URL/api/v1/admin/live-sessions/7ec34d19-64f7-4d36-92eb-dbb217448af7/quizzes/ecc3e7ba-d655-4955-abf8-39081e5a0ffd/close" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Fechar quiz)

200Quiz fechado

json

{
  "message": "quiz closed"
}

Erros (Fechar quiz)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
500	O quiz não existe nesta sessão ou já foi fechado.	`{"error":"gamification error","detail":"quiz not found or already closed"}`

Revelar voucher relâmpago

POST/api/v1/admin/live-sessions/{id}/flash-voucher/revealAdmin

Libera o voucher relâmpago configurado para a sessão

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 (Revelar voucher)

bash

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

Resposta (Revelar voucher)

200Voucher revelado

json

{
  "message": "flash voucher revealed"
}

Erros (Revelar voucher)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um administrador.	`{"error":"insufficient permissions"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
500	Não há voucher relâmpago configurado na sessão. A plataforma responde 500 em vez de 409.	`{"error":"gamification error","detail":"no flash voucher configured"}`