Endpoints e Serviços da Plataforma (API v1)

🔌 Endpoints e Serviços da Plataforma (API v1)

Este documento descreve a arquitetura de serviços HTTP, contratos OpenAPI declarativos e fluxos de integração implementados no backend do Academic Companion.

---

🛡️ Padrão de Autenticação e Segurança

• Tokens JWT:
  • accessToken: Validade de 24h, assinado com HMAC-SHA256 contendo sub: userId.
  • refreshToken: Validade de 7 dias, persistido e auditado na base relacional PostgreSQL.
• Cookies HTTP-Only:
  • Ambos os tokens trafegam exclusivamente via Cookies seguros (HttpOnly, SameSite: Lax em dev e SameSite: None + Secure em produção).
  • Previne ataques de XSS e extração de credenciais via JavaScript de terceiros.
• Boas-Vindas Automáticas:
  • No cadastro (POST /api/auth/register), o estudante já recebe automaticamente os cookies autenticados, seu perfil inicial (StudentProfile) e sua carteira (UserWallet) provisionada com 50 tokens gratuitos.

---

📡 Módulos Centrais e Endpoints

1. Autenticação e Perfil (/api/auth)

Método	Rota	Descrição	Segurança
POST	/api/auth/register	Cadastro do estudante (nome, email, senha, curso, universidade)	Pública
POST	/api/auth/login	Login com credenciais e emissão de cookies	Pública
POST	/api/auth/refresh	Renovação do accessToken através do cookie refreshToken	Cookie
POST	/api/auth/logout	Revogação dos cookies de autenticação	Pública
GET	/api/auth/me	Retorna dados completos do estudante, perfil e carteira	Autenticada

2. Oportunidades & Bolsas (/api/opportunities)

Método	Rota	Descrição	Segurança
GET	/api/opportunities/public-radar	Radar Universitário Aberto para a Landing Page (sem login)	Pública
GET	/api/opportunities	Listagem com filtros de pesquisa, categoria e paginação	Pública / Opcional
GET	/api/opportunities/:id	Detalhes completos de edital ou bolsa	Pública
GET	/api/opportunities/applications/me	Candidaturas ativas do estudante (alimenta o Kanban)	Autenticada
POST	/api/opportunities/apply	Registro de nova candidatura com status inicial	Autenticada
PATCH	/api/opportunities/applications/:id/status	Mudança de coluna no Kanban de candidaturas	Autenticada

3. Vivências & Projetos (/api/experiences)

Método	Rota	Descrição	Segurança
GET	/api/experiences	Lista projetos, ICs, estágios, monitorias e extensões	Autenticada
GET	/api/experiences/:id	Detalhes de uma vivência prática específica	Autenticada
POST	/api/experiences	Cadastro de nova atividade prática e competências	Autenticada
PUT	/api/experiences/:id	Atualização de dados, carga horária e orientação	Autenticada
DELETE	/api/experiences/:id	Remoção de vivência prática	Autenticada

4. Diário & Memórias Acadêmicas (/api/memories)

Método	Rota	Descrição	Segurança
GET	/api/memories	Histórico cronológico de reflexões e notas de estudo	Autenticada
GET	/api/memories/:id	Detalhes de anotação ou transcrição de áudio	Autenticada
POST	/api/memories	Registro de aprendizado, insight, reflexão ou conquista com suporte a data específica retroativa	Autenticada
POST	/api/memories/batch	Inserção transacionada em lote de múltiplos acontecimentos ou importações do Lattes	Autenticada
POST	/api/memories/lattes/scrape	Web scraping guiado de currículo Lattes por URL e detecção de desafio Captcha	Autenticada
POST	/api/memories/lattes/pdf	Extração inteligente de acontecimentos e marcos temporais de PDF impresso do Lattes	Autenticada
PUT	/api/memories/:id	Edição de conteúdo, tags temáticas e retificação de data do acontecimento	Autenticada
DELETE	/api/memories/:id	Exclusão de registro	Autenticada

5. Carteira de Tokens & Apoio Solidário (/api/wallet)

Método	Rota	Descrição	Segurança
GET	/api/wallet	Saldo disponível de tokens e status de apoio solidário	Autenticada
GET	/api/wallet/transactions	Extrato detalhado de débitos e créditos de tokens	Autenticada
POST	/api/wallet/simulate	Simulação instantânea de poder de compra (mín. R$ 2,50)	Autenticada
POST	/api/wallet/checkout	Sessão de pagamento de recarga voluntária	Autenticada

6. Notificações do Sistema (/api/notifications)

Método	Rota	Descrição	Segurança
GET	/api/notifications	Lista as notificações reais e contador de não lidas (unreadCount)	Autenticada
PATCH	/api/notifications/read	Marca notificações como lidas (específicas ou todas)	Autenticada
DELETE	/api/notifications/:id	Exclusão de notificação individual	Autenticada
POST	/api/notifications/bulk-delete	Exclusão em lote de notificações selecionadas	Autenticada

7. Dashboard & Personalização de Layout (/api/dashboard)

Método	Rota	Descrição	Segurança
GET	/api/dashboard/stats	Estatísticas agregadas do sistema e métricas da semana	Autenticada
GET	/api/dashboard/map	Dados geoespaciais 3D dos prédios da UFSM para o mapa interativo	Autenticada
GET	/api/dashboard/layout	Configuração personalizada de widgets e posições do discente	Autenticada
PUT	/api/dashboard/layout	Salva e persiste o layout customizado no PostgreSQL	Autenticada
POST	/api/dashboard/layout/reset	Restaura o layout padrão de fábrica no banco	Autenticada

8. Copiloto Acadêmico & Chat IA (/api/assistant)

Método	Rota	Descrição	Segurança
POST	/api/assistant/chat	Envia mensagem ao Copiloto IA (Gemini 2.5 Flash) com contexto da trajetória	Autenticada
GET	/api/assistant/conversations	Lista todas as conversas e tópicos arquivados do estudante	Autenticada
POST	/api/assistant/conversations	Cria uma nova thread de mentoria ou tópico conversacional	Autenticada
GET	/api/assistant/conversations/:id	Recupera histórico completo de balões e respostas de uma conversa	Autenticada
DELETE	/api/assistant/conversations/:id	Exclui conversa e mensagens associadas	Autenticada

9. Resumo Cognitivo de Editais (/api/opportunities)

Método	Rota	Descrição	Segurança
POST	/api/opportunities/:id/summarize	Extrai resumo executivo, critérios e dicas com Gemini (salva em ai_summary)	Autenticada

10. LinkedIn Impact Builder & IA de Carreira (/api/integrations/linkedin)

Método	Rota	Descrição	Segurança
POST	/api/integrations/linkedin/generate-post	Gera publicação profissional em 3 tons (Técnico, Storytelling, Executivo)	Autenticada
POST	/api/integrations/linkedin/optimize-profile	Gera Headline magnética, Pitch “Sobre” e recomendações de palavras-chave	Autenticada

11. Public API & Headless CMS (/api/public/v1)

Método	Rota	Descrição	Segurança
POST	/api/public/v1/keys	Gera nova chave de API exclusiva para portfólio externo	Autenticada (Cookie)
GET	/api/public/v1/keys	Lista as chaves de API cadastradas e telemetria	Autenticada (Cookie)
DELETE	/api/public/v1/keys/:keyId	Revoga imediatamente uma chave de API	Autenticada (Cookie)
GET	/api/public/v1/me/portfolio	Obtém portfólio completo com perfil e vivências públicas	API Key (X-Acad-Api-Key)
GET	/api/public/v1/me/experiences	Lista exclusivamente as vivências marcadas como públicas	API Key (X-Acad-Api-Key)
GET	/api/public/v1/me/profile	Retorna o perfil público do estudante	API Key (X-Acad-Api-Key)

---

📦 Padrão de Erros RFC 7807

Todas as respostas de erro HTTP (400, 401, 403, 404, 409, 500) seguem rigorosamente a RFC 7807:

{
  "type": "/errors/validation-error",
  "title": "Erro de validação nos dados enviados.",
  "status": 400,
  "detail": "A senha deve conter no mínimo 8 caracteres.",
  "errors": {
    "password": ["A senha deve conter no mínimo 8 caracteres."]
  }
}