Visão Geral
A API de Quiz fornece endpoints para o sistema de recuperação de streaks do The News. Os quizzes são gerados automaticamente a partir das edições diárias da newsletter, permitindo que usuários recuperem seus streaks perdidos respondendo perguntas sobre o conteúdo.
Base URL
https://sac-waffle-v2.theo-110.workers.dev
Autenticação
A maioria dos endpoints requer autenticação via JWT token. Endpoints administrativos estão separados e claramente indicados.
Authorization: Bearer {token}
Content-Type: application/json
Recursos Principais
1. Quizzes para Usuários
- Listar quizzes disponíveis (últimos 3 dias)
- Visualizar perguntas do quiz
- Submeter respostas
- Histórico de tentativas
- Recuperação automática de streak
2. Administração
- Gerar quiz diário manualmente
- Criar quiz para data específica
- Listar todos os quizzes
- Deletar quizzes
Regras do Sistema
| Regra | Valor |
|---|
| Perguntas por quiz | 10 |
| Opções por pergunta | 4 |
| Mínimo de acertos para passar | 6 (60%) |
| Tentativas por quiz | 1 |
| Dias recuperáveis | Até 3 dias anteriores |
Endpoints Disponíveis
Rotas Autenticadas (Usuário)
| Endpoint | Descrição |
|---|
| GET /quiz/available | Lista quizzes disponíveis |
| GET /quiz/:id | Obtém quiz com perguntas |
| POST /quiz/submit | Submete respostas do quiz |
| GET /quiz/history | Histórico de tentativas |
Rotas Administrativas
| Endpoint | Descrição |
|---|
| POST /quiz/admin/generate | Força geração do quiz diário |
| POST /quiz/admin/create | Cria quiz para data específica |
| GET /quiz/admin/list | Lista todos os quizzes |
| DELETE /quiz/admin/:id | Deleta quiz específico |
Fluxo de Recuperação de Streak
Quando o usuário passa no quiz (acertos >= 6):
- Sistema verifica as respostas do usuário
- Calcula pontuação total
- Se passou, registra leitura histórica automaticamente
- Streak é recuperado para a data do quiz
- Tentativa é salva com
streakRecovered: true
O quiz é gerado automaticamente todos os dias às 12h (horário de Brasília) com base na edição do dia anterior da newsletter.
Tratamento de Erros
A API retorna erros padronizados no seguinte formato:
{
"success": false,
"message": "Descrição do erro"
}
Códigos de Status HTTP
| Código | Descrição |
|---|
200 | Sucesso |
201 | Criado com sucesso |
400 | Requisição inválida |
401 | Não autorizado |
403 | Acesso negado (já tentou o quiz) |
404 | Quiz não encontrado |
409 | Conflito (quiz já existe para data) |
500 | Erro interno do servidor |
Geração Automática de Quizzes
O sistema gera quizzes automaticamente usando:
- Beehiiv API: Busca a última edição da newsletter
- OpenAI GPT-4o: Gera 10 perguntas sobre o conteúdo
- Cloudflare D1: Armazena quizzes e tentativas
Aos domingos não há edição da newsletter, portanto o quiz de segunda-feira é baseado na edição de sábado.
Suporte
Para dúvidas ou problemas com a API, entre em contato:
