src/config/routes.ts

Versão: 1.0
 Última atualização: 27 de agosto de 2025
 Responsável: Ariel Spencer & Fabrício Bahiense

📋 Descrição

O que faz?

Configura e registra todas as rotas da API principal do NexusPlatform para usuários finais, organizando endpoints por entidades e aplicando middleware de autenticação adequado para cada contexto.

Por que existe?

Centraliza a configuração de rotas da aplicação principal, separando rotas públicas (webhooks, login) das privadas (operações autenticadas), mantendo a organização modular e segura do sistema.

Como funciona?

Recebe uma instância do Express e registra rotas em ordem específica: primeiro webhooks (sem auth), depois rotas públicas de usuário, em seguida aplica autenticação JWT global para todas as rotas protegidas.

🔧 Documentação Técnica

Arquitetura

Express App → registerRoutes() → Ordem Específica de Registro:

↓

1. Webhooks (sem auth)
        2. Rotas públicas (/api/user não autorizadas)
        3. Middleware JWT Global
        4. Todas as rotas protegidas
        5. Error Handler

Tecnologias Utilizadas

Runtime: Node.js com TypeScript
Framework: Express.js
Autenticação: JWT (JSON Web Tokens)
Middleware: Custom auth e error handling

Estrutura de Pastas

backend/                 
				        # Projeto
└── src/                 
				       # Source
        └── config/                  # Configurações
                └── routes.ts            # Registro de rotas

Estrutura de Rotas

Webhooks (Sem Autenticação)

Rotas de webhook configuradas via webhookController
Posição: Primeiro na ordem (antes de qualquer middleware de auth)
Finalidade: Receber callbacks externos (pagamentos, etc.)

Rotas Não Autorizadas

/api/user - Rotas públicas de usuário

Rotas Autorizadas (Autenticação via JWT)

Todas aplicadas após app.use(authenticateJWT):

/api/user - Operações autenticadas de usuário
/api/subscription - Gerenciamento de assinaturas/planos
/api/invoice - Gestão de faturas
/api/payment - Métodos de pagamento
/api/contact - Gestão individual de contatos
/api/contact-list - Gestão de listas de contatos
/api/campaign - Campanhas de marketing

📦 Dependências

Dependências Principais

Módulo	Tipo	Finalidade
Express	Framework	Interface de tipos do Express
authenticateJWT	Middleware	Autenticação JWT para usuários
errorHandler	Middleware	Tratamento global de erros

Dependências Internas

userRoutes - Rotas autenticadas de usuários
userRoutesUnauthorized - Rotas públicas (login, registro)
subscriptionRoutes - Gestão de assinaturas/planos
invoiceRoutes - Gestão de faturas
paymentMethodRoutes - Métodos de pagamento
contactRoutes - Gestão individual de contatos
contactListRoutes - Gestão de listas de contatos
campaignRoutes - Campanhas de marketing
webhookController - Manipulação de webhooks externos

🔧 Como Usar

import express from 'express'
import { registerRoutes } from './config/routes'

const app = express()

registerRoutes(app)

⚠️ Ordem de Registro

Webhooks - Externos não têm JWT, precisam estar antes da autenticação
Rotas públicas - Login/registro devem estar antes do middleware de auth
Middleware JWT global - Aplicado apenas uma vez, protege todas as rotas subsequentes
Rotas protegidas - Todas automaticamente autenticadas
Error handler último - Captura erros de toda a aplicação

Colocar authenticateJWT antes dos webhooks quebra callbacks externos.

🐛 Troubleshooting

Problemas Comuns

Webhooks retornando 401 Unauthorized

Sintomas: Callbacks externos falhando com erro de
				autenticação
 Causa: webhookController registrado após authenticateJWT
 Solução: Webhooks devem estar PRIMEIRO na ordem de registro

Usuários não conseguem fazer login

Sintomas: Erro 401 em rotas de login/registro
 Causa: Rotas de login estão sendo protegidas por JWT
 Solução: Verificar se userRoutesUnauthorized está antes do authenticateJWT

Todas as rotas protegidas falhando

Sintomas: Erro 401 em todas as rotas após login
 Causa: authenticateJWT não aplicado ou mal configurado
 Solução: Verificar se middleware está entre rotas
				públicas e protegidas

📚 Referências e Links Úteis

Última revisão: 27 de agosto de 2025 por Ariel Spencer