Visão geral das APIs

Backend NestJS 11 do CentralCRM. Prefixo global: api. Versionamento URI: rotas em /api/v1/... (exceto rotas VERSION_NEUTRAL em /api/...).

Inventário completo: catalogo-completo.md (~70 rotas HTTP + namespace WebSocket).

Superfícies

Superfície	Path	Função
REST	/api + /api/v1/...	CRUD, auth, operacional, presença, proxies externos
OpenAPI	/api/docs	Swagger UI
WebSocket	namespace /presence	Presença em tempo real (Socket.IO)
Health	GET /api, GET /api/health	Metadados e liveness

Autenticação

• Guard JWT global (JwtAuthGuard) — ADR 0001.
• Cabeçalho: Authorization: Bearer <access_token>.
• Opcional: x-tenant-id (UUID) quando o JWT não inclui tenantId.

Rotas públicas (@Public)

• GET /api
• GET /api/health
• POST /api/v1/auth/login
• POST /api/v1/auth/register
• POST /api/v1/auth/password-reset/request
• GET /api/v1/auth/password-reset/token
• POST /api/v1/auth/password-reset/confirm
• GET /api/v1/auth/first-access/token
• POST /api/v1/auth/first-access/confirm
• GET /api/v1/portal/subdomain-url
• GET /api/v1/portal/internal/check-host

Swagger (/api/docs, /api/docs-json, /api/docs-yaml) também é acessível sem Bearer.

Tipos de token

Origem	Claims	Uso
Login	sub (+ tenantId se enviado no body)	APIs sem tenant; patch de perfil
Multi-tenant / default-crm	sub + tenantId	Diretório, operacional, presença
Admin	sub + role: admin	Visão global; WebSocket admin:observer; templates de e-mail

Bases de dados

Conexão	Variáveis	Uso
default	POSTGRES_* / DATABASE_* / PG*	Empresas, operacional, presença, white labels, tenants
USER_PROFILES	AUTH_DATABASE_*	public."user" + tabelas relacionais (login/registo)

Redis (REDIS_*) cacheia branding; não guarda sessões de presença.

Formato de erro

{
  "statusCode": 400,
  "timestamp": "2026-08-08T12:00:00.000Z",
  "path": "/api/v1/auth/login",
  "message": "string ou string[]"
}

Pipes globais: whitelist + forbidNonWhitelisted (campo extra → 400) e SqlInjectionValidationPipe.

Módulos Nest (resumo)

AppModule
├── AuthModule              (JWT strategy + guard)
├── AuthLoginModule         (login, users, roles, branding user)
├── PasswordResetModule     (reset, first-access, email templates)
├── CompanyModule           (companies, directory, users por empresa, cadastro)
├── CompanyOperationalModule
├── PresenceModule          (REST + Gateway Socket.IO)
├── WhiteLabelModule
├── PortalSubdomainModule
├── ExternalApisModule      (OpenCNPJ, BrasilAPI CEP/bancos)
├── HealthModule
├── RedisModule
└── Mail / SMTP             (via PasswordReset / welcome)

Base URL

{BASE_URL}/api          → ex.: http://localhost:3000/api
{BASE_URL}/api/v1/...   → rotas versionadas