Catálogo completo de endpoints

Inventário gerado a partir dos controllers em src/ (NestJS 11). Prefixo global: api. Versionamento URI: v1 salvo rotas VERSION_NEUTRAL.

Base local: http://localhost:3000
Swagger: /api/docs · JSON /api/docs-json · YAML /api/docs-yaml
Auth padrão: Authorization: Bearer <JWT> · opcional x-tenant-id (UUID)

Legenda Auth: Pública = @Public() (sem Bearer). Bearer = JWT obrigatório. Admin = role: admin (cross-tenant).

---

1. Meta, saúde e OpenAPI

Método	Path	Auth	Controller	Sucesso	Notas
GET	/api	Pública	AppController	200	{ name, version, docs, swagger } — docs aponta para /api/health
GET	/api/health	Pública	HealthController	200	{ status: "ok", timestamp } (liveness; não faz ping à BD)
GET	/api/docs	Pública	SwaggerModule	200	UI OpenAPI
GET	/api/docs-json	Pública	SwaggerModule	200	OpenAPI JSON
GET	/api/docs-yaml	Pública	SwaggerModule	200	OpenAPI YAML

Detalhe: 01-health-meta.md.

---

2. Auth — /api/v1/auth

Controller: AuthV1Controller · BD: USER_PROFILES (public."user").

Método	Path	Auth	Sucesso	Descrição
POST	/api/v1/auth/login	Pública	200	Email/senha → { accessToken, tokenType, expiresIn, user }. Body: email, password, opcional tenantId/tid
POST	/api/v1/auth/logout	Bearer	200	Decrementa metadata.sessoesAtivas. { success, sessoesAtivas }
POST	/api/v1/auth/register	Pública	201	Cria utilizador + tabelas relacionais. 409 se email/username duplicado
GET	/api/v1/auth/users/:userId	Bearer	200	Perfil completo. Qualquer JWT válido
PATCH	/api/v1/auth/users/:userId	Bearer	200	Patch parcial; arrays substituem. Próprio ou admin. 403/409
PATCH	/api/v1/auth/users/:userId/permissions	Bearer	200	grant/revoke por permissao_id ou chave

Erros típicos: 400 validação, 401 JWT/credenciais, 403 conta inativa ou sem permissão, 404 utilizador.

Detalhe: 02-auth.md.

---

3. Password reset — /api/v1/auth/password-reset

Controller: PasswordResetV1Controller · todas públicas.

Método	Path	Sucesso	Descrição
POST	/api/v1/auth/password-reset/request	200	Código 6 dígitos (~15 min), e-mail SMTP, token AES-256-GCM em {{link}}
GET	/api/v1/auth/password-reset/token?token=	200	Decifra token → email, codigo, expiraEm. 400 inválido/expirado
POST	/api/v1/auth/password-reset/confirm	204	Body: token ou email+codigo + nova senha

---

4. First access — /api/v1/auth/first-access

Controller: FirstAccessV1Controller · todas públicas.

Método	Path	Sucesso	Descrição
GET	/api/v1/auth/first-access/token?token=	200	Token do link /primeiro-acesso?token=
POST	/api/v1/auth/first-access/confirm	204	Tipo welcome_first_access em logs_password_resets

Detalhe: 03-password-reset-first-access.md.

---

5. CRM admin users — /api/v1/crm-admin/users

Controller: UserProfilesV1Controller.

Método	Path	Auth	Sucesso	Descrição
GET	/api/v1/crm-admin/users	Bearer	200	Lista todos os public."user" (resumo UserProfileResponseDto)

Detalhe: 04-crm-admin-users.md.

---

6. Empresas globais — /api/v1/companies

Controller: CompaniesV1Controller · BD default.

Método	Path	Auth	Sucesso	Descrição
POST	/api/v1/companies	Bearer	201	Cria empresa. Tenant: JWT, body tenantId ou x-tenant-id. 409 CNPJ
GET	/api/v1/companies	Bearer	200	Listagem global paginada. Query: pageNumber (default 1), pageSize (default 20, máx 100)

Detalhe: 05-companies.md.

---

7. Diretório por tenant — /api/v1/company/directory

Controller: CompanyDirectoryV1Controller. Admin sem tenant lista todas.

Método	Path	Auth	Sucesso	Descrição
POST	/api/v1/company/directory	Bearer + tenant	201	Criar no contexto do tenant
GET	/api/v1/company/directory	Bearer	200	Lista paginada (pageNumber, pageSize). Admin sem tenant = global
GET	/api/v1/company/directory/:companyId	Bearer	200	Detalhe + sync de roles/contacts
PATCH	/api/v1/company/directory/:id	Bearer	200	Atualização parcial (dados gerais / metadata)
PUT	/api/v1/company/directory/:companyId/branding	Bearer	200	Upsert branding
POST	/api/v1/company/directory/:companyId/addresses	Bearer	201	Adicionar morada
PATCH	/api/v1/company/directory/:companyId/addresses/:addressId	Bearer	200	Atualizar morada
DELETE	/api/v1/company/directory/:companyId/addresses/:addressId	Bearer	204	Remover morada
POST	/api/v1/company/directory/:companyId/documents	Bearer	201	Adicionar documento
DELETE	/api/v1/company/directory/:companyId/documents/:documentId	Bearer	204	Remover documento

Detalhe: 06-company-directory.md.

---

8. Utilizadores por empresa — /api/v1/company

Controller: CompanyUsersV1Controller. tenetid é alias histórico de tenentid.

Método	Path	Auth	Sucesso	Descrição
GET	/api/v1/company/:companyId/tenetid/:tenantId	Bearer	200	Alias typo — sub-empresas
GET	/api/v1/company/:companyId/tenentid/:tenantId	Bearer	200	Sub-empresas ligadas à empresa
GET	/api/v1/company/:companyId/tenentid/:tenantId/user	Bearer	200	Utilizadores das sub-empresas
GET	/api/v1/company/:companyId/user/with-subcompanies	Bearer	200	Contagem empresa + filhas
GET	/api/v1/company/:companyId/user	Bearer	200	Contagem de users da empresa

Detalhe: 07-company-users.md.

---

9. Operacional — /api/v1/company/directory/:companyId/operational

Controller: CompanyOperationalV1Controller. JWT + tenant (admin pode omitir tenant). 404 se company fora do tenant.

Query de período (dashboard, top, comissões): dataInicio, dataFim (ISO / YYYY-MM-DD). Default: ~30 dias até agora. Top: limite 1–100 (default 10).

Método	Path relativo ao prefixo operacional	Sucesso	Descrição
GET	/estabelecimentos	200	ECs cujo representante pertence à company
GET	/estabelecimentos/:estabelecimentoId	200	Detalhe + valoresDeclarados
GET	/dashboard	200	TPV transacoes_locais status APPR
GET	/top-estabelecimentos	200	Ranking por volume bruto APPR
GET	/comissoes/resumo	200	Bruto / líquido / spread por EC
GET	/alugueis/resumo	200	Só entrepay_dispositivos.status = ATIVO
GET	/propostas	200	propostas.company_id ou ECs acessíveis

Exemplo: GET /api/v1/company/directory/{companyId}/operational/dashboard?dataInicio=2026-04-01&dataFim=2026-05-04

Detalhe: 08-company-operational.md.

---

10. Presença REST — /api/v1/presence

Controller: PresenceV1Controller. Estado em memória — restart limpa sessões.

Método	Path	Auth	Sucesso	Descrição
GET	/api/v1/presence/active-users	Bearer + tenant	200	Sessões no tenant. 400 sem tenantId/x-tenant-id
GET	/api/v1/presence/active-users-global	Bearer admin	200	Todas as sessões. 403 se não admin
GET	/api/v1/presence/online-count/main-companies	Bearer	200	Empresas mãe. Query opcional parentCompanyId
GET	/api/v1/presence/online-count/sub-companies	Bearer	200	Sub-empresas. Query opcional parentCompanyId
GET	/api/v1/presence/online-count/aggregated-by-parent	Bearer	200	Query obrigatória parentCompanyId (UUID v4)

WebSocket — namespace /presence

Item	Valor
Path Socket.IO	/socket.io
Handshake	{ token: "<JWT>" } (mesmo segredo que a API)
Salas	tenant:<tenantId>, admin:observer (admins não contam como online)
Eventos (ex.)	presence:sync, presence:join, presence:leave, presence:error, cliente presence:status

Detalhe: 09-presence.md.

---

11. White label — /api/v1/white-labels

Controller: WhiteLabelsV1Controller.

Método	Path	Auth	Sucesso	Descrição
GET	/api/v1/white-labels/:tenantId	Bearer	200	Paginado (pageNumber, pageSize). Não-admin só o próprio tenant. Admin: qualquer

Detalhe: 10-white-label.md.

---

12. APIs externas (proxies autenticados)

Todas exigem Bearer. Upstream público.

Método	Path CentralCRM	Upstream
GET	/api/v1/external-apis/opencnpj/:cnpj	https://api.opencnpj.org/{CNPJ} (só dígitos)
GET	/api/v1/external-apis/cep/v1/:cep	https://brasilapi.com.br/api/cep/v1/{cep}
GET	/api/v1/external-apis/cep/v2/:cep	https://brasilapi.com.br/api/cep/v2/{cep} (geo quando disponível)
GET	/api/v1/external-apis/banks/v1	https://brasilapi.com.br/api/banks/v1

Detalhe: 11-external-apis.md.

---

13. Portal / subdomínio

Método	Path	Auth	Controller	Sucesso	Descrição
GET	/api/v1/portal/subdomain-url?portalTenantId=	Pública (sem JWT)	PortalUrlController	200	URL {slug}.{PORTAL_BASE_DOMAIN}. 404 inativo/inexistente
GET	/api/v1/portal/internal/check-host	Pública	PortalTlsCheckController	200	Check interno TLS (Caddy). Fora do Swagger
GET	/api/tenants/id/:tenantId/icon	Bearer	TenantBrandingMediaV1Controller	200 / 204	Binário ou ?json=true. 404 tenant inexistente

Detalhe: 12-portal-subdomain.md.

---

14. Templates de e-mail — /api/v1/email-templates

Controller: EmailTemplateV1Controller. Apenas admin.

Método	Path	Auth	Sucesso	Descrição
GET	/api/v1/email-templates/:templateKey	Bearer admin	200	Chaves: lock_reset, waving_hand. 403/404
PATCH	/api/v1/email-templates/:templateKey	Bearer admin	200	Patch placeholders. 400 placeholder inválido

Detalhe: 13-email-templates.md.

---

15. Branding do utilizador — /api/centralbackend/users

Controller: UserBrandingMediaV1Controller · VERSION_NEUTRAL (sem /v1). PATCH de terceiros exige perm-user-edit. Query ?json=true devolve JSON.

Método	Path	Auth	Descrição
GET	/api/centralbackend/users/me/icon	Bearer	Ícone do autenticado
PATCH	/api/centralbackend/users/me/icon	Bearer	Atualizar ícone
GET	/api/centralbackend/users/me/banner	Bearer	Banner do autenticado
PATCH	/api/centralbackend/users/me/banner	Bearer	Atualizar/remover banner
GET	/api/centralbackend/users/id/:userUuid/icon	Bearer	Ícone de outro
PATCH	/api/centralbackend/users/id/:userUuid/icon	Bearer	PATCH terceiro (perm-user-edit)
GET	/api/centralbackend/users/id/:userUuid/banner	Bearer	Banner de outro
PATCH	/api/centralbackend/users/id/:userUuid/banner	Bearer	PATCH terceiro (perm-user-edit)

Detalhe: 14-user-branding-media.md.

---

16. Roles — /api/centralbackend/roles

Controller: CentralbackendRolesController · VERSION_NEUTRAL.

Método	Path	Auth	Descrição
GET	/api/centralbackend/roles	Bearer	Catálogo public.roles
GET	/api/centralbackend/roles/with-users	Bearer	Roles com utilizadores por role_number

---

17. Users legado — /api/users

Controller: UsersLegacyController · VERSION_NEUTRAL. Preferir /api/v1/auth/users/:userId.

Método	Path	Auth	Equivalente
GET	/api/users/:userId	Bearer	GET /api/v1/auth/users/:userId
PUT	/api/users/:userId	Bearer	PATCH /api/v1/auth/users/:userId
PATCH	/api/users/:userId	Bearer	PATCH /api/v1/auth/users/:userId

Detalhe: 15-roles-legacy.md.

---

18. Cadastro completo — /api/centralcrm/cadastrocompany

Controller: CentralcrmCadastroCompanyController · VERSION_NEUTRAL.

Método	Path	Auth	Sucesso	Descrição
POST	/api/centralcrm/cadastrocompany	Bearer	201	Transação única (empresa + relacionados)

Detalhe: 16-cadastro-company.md.

---

Totais

Superfície	Quantidade
HTTP REST (controllers da app)	70 rotas (incluindo aliases tenetid/tenentid e legado PUT/PATCH users)
OpenAPI (docs / json / yaml)	3
WebSocket	1 namespace (/presence)

Rotas públicas (@Public): GET /api, GET /api/health, POST /api/v1/auth/login, POST /api/v1/auth/register, as 3 de password-reset, as 2 de first-access, GET /api/v1/portal/subdomain-url, GET /api/v1/portal/internal/check-host.

Formato de erro global:

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