Referência de endpoints da API

Todas as rotas usam o prefixo /api. Respostas de sucesso seguem { status: "success", message, data? }.

Autenticação padrão: Authorization: Bearer <sessionHash> (JWT retornado no login), salvo indicação contrária.

---

Status

Método	Rota	Auth	Descrição
GET	/	Pública	Health check

---

Auth

Método	Rota	Auth	Descrição
POST	/auth/login	Pública	Login por razao_social ou tenantSlug + email + password → retorna sessionHash
POST	/auth/logout	JWT	Invalida o token atual (header Bearer ou sessionHash no body)

---

Tenants (público)

Rotas sem autenticação para o frontend resolver o rótulo da empresa na tela de login (subdomínio → tenants.slug).

Método	Rota	Auth	Descrição
GET	/tenants/:slug/nome	Pública	Retorna { nome } de public.tenants quando o tenant está ativo

Exemplo: GET /api/tenants/horizonte-obras/nome → data.nome (campo tenants.nome).

Erros: 404 — slug inexistente ou tenant inativo.

---

Integração

Requer chaves granulares no JWT (integracao.modulo + chave específica). Perfis N0/N1/admin/super_admin fazem bypass.

Método	Rota	Permissão extra	Descrição
GET	/integration/catalog	integracao.modulo	Lista todas as integrações com rota interna, permissões e contagem de campos
GET	/integration/catalog/:apiKind	integracao.modulo	Detalhe de uma integração com todos os campos disponíveis em data (path, type, description)
GET	/integration/cep/:cep	integracao.cep	Endereço por CEP (ViaCEP ou provedor em global_integration_apis)
GET	/integration/cnpj/:cnpj	integracao.cnpj	Dados de empresa por CNPJ (ReceitaWS ou provedor configurado)
GET	/integration/timezones	—	Lista de timezones (AddEvent ou provedor configurado)

Query opcional em CEP/CNPJ/timezones: vendor, integrationUuid.

---

Roles

Método	Rota	Auth	Descrição
GET	/roles	JWT	Catálogo de perfis (public.roles)
PUT	/roles/:roleUuid	JWT	Atualiza o campo nome de uma role

---

Utilizadores (/users)

Permissões metadata indicadas abaixo. Escopo de dados N0–N3 aplicado nos repositórios.

Método	Rota	Permissão metadata	Descrição
POST	/users	users → perm-user-edit	Cria utilizador e relações (endereços, branding, CET, etc.). Campos custom do formulário de cliente → metadata.clientFormCustomFields
PUT	/users/:userUuid	perm-user-edit	Atualiza utilizador (substitui relações enviadas)
GET	/users/me	JWT apenas	Perfil do utilizador autenticado (+ clientFormCustomFields)
PATCH	/users/me	JWT apenas	Atualiza o próprio perfil (campos admin ignorados para N2/N3)
POST	/users/me/media	JWT apenas	Upload foto/banner via Google Drive (multipart/form-data: profilePhoto, banner, corPrimaria?)
GET/PATCH	/users/me/icon, /users/me/banner	JWT apenas	Leitura binária ou ?json=true; PATCH envia base64 → grava no Drive
GET/PATCH	/users/id/:userUuid/icon, .../banner	GET: JWT; PATCH: perm-user-edit	Mesmo contrato; banner aceita { remove: true }
GET	/users/search?q=	perm-user-list	Busca por texto (mín. 3 caracteres). Itens com role_number + role_nome
GET	/users/:userUuid	perm-user-list	Perfil completo (+ clientFormCustomFields; sem icon.base64/banner.base64 no metadata)
POST	/users/:userUuid/block	perm-user-block-button	Alterna bloqueio/desbloqueio
GET	/users/company/:companyUuid	perm-user-list	Lista utilizadores da empresa (role_number + role_nome de metadata.rolesCompany)
GET	/users/company/:companyUuid/subcompanies	perm-user-list	Lista utilizadores das subempresas (mesmos campos de perfil)

Mídia de branding (Google Drive)

Upload e leitura de icon, banner e foto de perfil. Ver google-drive-media.md e FRONTEND_USER_MEDIA_DRIVE.md.

Pastas no Shared Drive (por nome da empresa): {Empresa}/profile/, {Empresa}/banner/.

Campo em user_branding.metadata	Descrição
profileImageUrl, profileImageDriveFileId, profileImageMimeType, profileImageSizeBytes	Foto de perfil / icon
bannerImageUrl, bannerImageDriveFileId, bannerImageMimeType, bannerImageSizeBytes	Banner

Limites: 10 MB; JPEG, PNG, SVG.

Erros: 503 se Google Drive não configurado (upload); 404 se imagem inexistente.

Compatibilidade: GET .../icon|banner faz fallback para base64 legado no banco; GET /users/:uuid não inclui esse base64 no metadata.

---

Storage (/storage)

Rotas de diagnóstico do Google Drive (públicas).

Método	Rota	Auth	Descrição
GET	/storage/drive/health	Pública	Testa autenticação e permissões na pasta configurada
GET	/storage/drive/test-company-folder?companyName=	Pública	Cria pasta {empresa}/profile/ e envia PNG de teste

Variáveis no .env (dev e produção): GOOGLE_DRIVE_USER_MEDIA_FOLDER_ID, GOOGLE_APPLICATION_CREDENTIALS ou GOOGLE_DRIVE_SERVICE_ACCOUNT_JSON. Ver .env.example.

---

Company (atalho)

Método	Rota	Permissão metadata	Descrição
GET	/company/users?companyUuid=	perm-user-list	Equivalente a /users/company/:uuid (UUID na query ou JWT; role_number + role_nome)

---

Empresas (/companies)

Método	Rota	Permissão metadata	Descrição
GET	/companies/:companyUuid	perm-user-list	Detalhe da empresa
GET	/companies/:parentCompanyUuid/subcompanies	perm-user-list	Subempresas (filhas por metadata.parentCompanyId)
GET	/companies/:companyUuid/calculos-sistema	rate_simulator → perm-st-table	Painel Cálculos do sistema (metadata.calculosSistema)
PATCH	/companies/:companyUuid/calculos-sistema	rate_admin → perm-ra-edit	Merge profundo em calculosSistema
GET	/companies/:companyUuid/taxas-parametrizacao-cartoes	JWT (escopo empresa)	Lista efetiva: override em metadata.taxasParametrizacaoCartoes ou fallback global
GET	/companies/:companyUuid/taxas-parametrizacao-cartoes/singleton	JWT	Obtém o registro ativo (origem: empresa ou global)
GET	/companies/:companyUuid/taxas-parametrizacao-cartoes/:uuid	JWT	Por UUID: override da empresa ou linha em global_taxas_parametrizacao_cartoes
PATCH	/companies/:companyUuid/taxas-parametrizacao-cartoes	JWT	Atualiza singleton ativo e grava override em metadata.taxasParametrizacaoCartoes
PATCH	/companies/:companyUuid/taxas-parametrizacao-cartoes/:uuid	JWT	Idem por UUID (cria override a partir do global, preservando o UUID)
GET	/companies/:companyUuid/roles-company	perm-user-list	Todos os perfis (N1, N2, N10, …) — catálogo roles + metadata.rolesCompany
GET	/companies/:companyUuid/roles-company/users-count	perm-user-list	Contagem de utilizadores por role_number
PATCH	/companies/:companyUuid/roles-company	perm-user-edit	Atualiza role_nome por role_number (N1, N10, …)
GET/PATCH	/companies/:companyUuid/email-templates/{tipo}	JWT (escopo empresa)	Templates de e-mail editáveis — ver FRONTEND_EMAIL_TEMPLATES.md
GET/POST	/companies/:companyUuid/email-templates/{tipo}/render	JWT	Renderização do e-mail (preview/envio)

Parametrização de cartões (empresa)

Override por empresa em company.metadata.taxasParametrizacaoCartoes. Sem override, leitura cai na tabela singleton global_taxas_parametrizacao_cartoes.

Campo na resposta	Descrição
origem	empresa (override) ou global (fallback)
overpricePlusDebito / overpricePlusCredito / antecipacao / pix	Valores numéricos (nullable)
metadata	JSON livre; updated_by é gravado no PATCH

Comportamento do PATCH:

• Usa o registro resolvido (override ou global) como base.
• Se ainda não houver override e o UUID for o do global, cria o bloco em metadata preservando o mesmo UUID e o createdAt do seed.
• Persistência usa o tenantId da empresa resolvida (suporte cross-tenant N0/admin); se o update por tenant falhar, tenta updateMetadataAnyTenant.
• Resposta sempre com origem: "empresa" após gravar.

Catálogo global: ver Parametrização global de cartões. SQL: db/global_taxas_parametrizacao_cartoes.sql.

---

Governança (/governance)

Detalhe da empresa

Método	Rota	Descrição
GET	/governance/companies/:companyUuid	Campos de company + metadata JSONB (exceto metadata.permissions)

Formulário dinâmico

Persistência em company.metadata.governance.user_form.

Método	Rota	Descrição
GET	/governance/user-form	Catálogo + valores dos campos dinâmicos
PUT	/governance/user-form/fields	Substitui definições de campos
PUT	/governance/user-form/values	Atualiza valores dos campos

Formulário de cliente (3 rotas)

Persistência: company.metadata.governance.client_form_design. Estado natural: visible: false.

Método	Rota	Descrição
GET	/governance/company-client-form-fields	Lista todos os campos com slots de máscara (mask.*, validator.*, display.*, constant.*) e isObrigatorio. Query opcional: ?companyUuid=
PATCH	/governance/company-client-form-fields	Patch por id: objeto com visible?, section?, position?, slots de máscara, isObrigatorio?, uiLabel? (custom). Resposta = lista completa
DELETE	/governance/company-client-form-fields	Apaga campos custom por ids[]. Built-in não podem ser removidos. Resposta = lista completa

Resposta (GET, PATCH e DELETE): data.fields[] inclui maskName, ruleMask, validatorName, validateMask, displayName, displayMask, constantName, constantMask, isObrigatorio.

Exemplo GET (data.fields[] — trecho):

[
  {
    "id": "email",
    "visible": true,
    "kind": "builtin",
    "uiLabel": null,
    "section": "contato",
    "position": 1,
    "maskName": "mask.email",
    "ruleMask": "email",
    "validatorName": null,
    "validateMask": null,
    "displayName": null,
    "displayMask": null,
    "constantName": null,
    "constantMask": null,
    "isObrigatorio": true
  },
  {
    "id": "cpfCnpj",
    "visible": true,
    "kind": "builtin",
    "uiLabel": null,
    "section": "identificacao",
    "position": 4,
    "maskName": "mask.cpf",
    "ruleMask": "000.000.000-00",
    "validatorName": "validator.cpf",
    "validateMask": "digits:11;check:mod11",
    "displayName": null,
    "displayMask": null,
    "constantName": null,
    "constantMask": null,
    "isObrigatorio": true
  }
]

Cada slot referencia global_masks_filters.field_key + format_override (prefixos mask.*, validator.*, display.*, constant.*).

Regras de unicidade: apenas o id de campos custom deve ser único. position, maskName e ruleMask podem repetir na mesma seção (vários campos podem usar validator.cpf, por exemplo).

Exemplo PATCH:

{
  "fields": {
    "email": true,
    "senha": false,
    "rg": { "visible": true, "section": "identificacao", "position": 3 },
    "codigoPromocional": {
      "visible": true,
      "section": "complementar",
      "position": 1,
      "uiLabel": "Código promocional"
    }
  }
}

Exemplo DELETE:

{
  "ids": ["data_nascimento", "codigoPromocional"]
}

Seções built-in: identificacao, endereco, contato, perfil. Custom novo: complementar (ordem automática). Overrides de layout built-in persistem em metadata.governance.client_form_design.layout; overrides de máscara em metadata.governance.client_form_design.masks.

Valores no cadastro do utilizador (POST /users ou PUT/PATCH /users/:uuid):

• Catálogo de ids: company.metadata.governance.client_form_design.customFields
• Valores gravados em: user.metadata.clientFormCustomFields (ex.: { "data_nascimento": "1990-05-10" })
• Envio no POST /users: body plano com ids do formulário (nomeCompleto, email, senha ou password), wrapper { "fields": { ... } }, clientFormCustomFields, ou custom no topo (data_nascimento)
• Leitura: GET /users/:userUuid e GET /users/me expõem data.clientFormCustomFields (espelho de metadata.clientFormCustomFields)

{
  "nomeCompleto": "Maria",
  "email": "maria@exemplo.com",
  "password": "Senha@123",
  "companyUuid": "uuid-da-empresa",
  "data_nascimento": "1990-05-10",
  "codigoPromocional": "PROMO10"
}

Equivalente explícito:

{
  "clientFormCustomFields": {
    "data_nascimento": "1990-05-10"
  }
}

Permissões metadata da empresa

Fonte: company.metadata.permissions. Query opcional ?companyUuid= nas rotas de contexto.

Método	Rota	Descrição
GET	/governance/company-metadata-permissions	Matriz completa
GET	/governance/company-metadata-permissions/:module	Um módulo
PUT	/governance/company-metadata-permissions	Patch multi-módulo
PUT	/governance/company-metadata-permissions/:module	Patch de um módulo
PUT	/governance/company-metadata-permissions/:module/options/:option	Uma opção perm-*

Rotas com UUID no path (preferidas quando o frontend já tem o UUID):

Método	Rota
GET	/governance/companies/:companyUuid/metadata-permissions
GET	/governance/companies/:companyUuid/metadata-permissions/:module
PATCH	/governance/companies/:companyUuid/metadata-permissions
PATCH	/governance/companies/:companyUuid/metadata-permissions/:module
PATCH	/governance/companies/:companyUuid/metadata-permissions/:module/options/:option

Permissões metadata do utilizador (sessão)

Fonte: user.metadata.permissions do utilizador autenticado.

Método	Rota
GET	/governance/user-metadata-permissions
GET	/governance/user-metadata-permissions/:module
PUT	/governance/user-metadata-permissions
PUT	/governance/user-metadata-permissions/:module
PUT	/governance/user-metadata-permissions/:module/options/:option

Permissões metadata de utilizador alvo

Ver FRONTEND_GOVERNANCE_TARGET_USER_PERMISSIONS.md.

Método	Rota
GET	/governance/users/:userUuid/metadata-permissions
GET	/governance/users/:userUuid/metadata-permissions/:module
PATCH	/governance/users/:userUuid/metadata-permissions
PATCH	/governance/users/:userUuid/metadata-permissions/:module
PATCH	/governance/users/:userUuid/metadata-permissions/:module/options/:option

Theme tokens

Persistência em company.metadata.theme_tokens.

Método	Rota	Auth	Descrição
GET	/governance/:companyUuid/company-metadata-theme-tokens	JWT ou X-Governance-External-Key	Leitura do bloco metadata (rota canónica para integrações)
GET	/governance/companies/:companyUuid/theme-tokens	JWT	Theme tokens da empresa
PUT	/governance/companies/:companyUuid/theme-tokens	JWT	Substitui conjunto completo
PATCH	/governance/companies/:companyUuid/theme-tokens	JWT	Merge parcial (null remove chave)
DELETE	/governance/companies/:companyUuid/theme-tokens	JWT	Restaura defaults (apaga customizações)
DELETE	/governance/companies/:companyUuid/theme-tokens/:tokenKey	JWT	Remove um token (URL-encode chaves --*)

Formulário de cadastro White Label

Persistência em company.metadata.governance.white_label_cadastro_form_design.

Método	Rota	Auth	Descrição
GET	/governance/company-white-label-cadastro-form-fields?companyUuid={uuid}	JWT	Lista campos com slots de máscara + isObrigatorio
PATCH	/governance/company-white-label-cadastro-form-fields?companyUuid={uuid}	JWT	Merge de visible, section, position, slots de máscara, isObrigatorio, uiLabel
DELETE	/governance/company-white-label-cadastro-form-fields?companyUuid={uuid}	JWT	Remove campos custom (body.ids)

Formulário de cadastro Estabelecimento Comercial

Persistência em company.metadata.governance.estabelecimento_comercial_cadastro_form_design.

Método	Rota	Auth	Descrição
GET	/governance/company-estabelecimento-comercial-cadastro-form-fields?companyUuid={uuid}	JWT	Lista campos com slots de máscara + isObrigatorio
PATCH	/governance/company-estabelecimento-comercial-cadastro-form-fields?companyUuid={uuid}	JWT	Merge de visible, section, position, slots de máscara, isObrigatorio, uiLabel
DELETE	/governance/company-estabelecimento-comercial-cadastro-form-fields?companyUuid={uuid}	JWT	Remove campos custom (body.ids)

---

White Label (/white-labels)

Método	Rota	Permissão metadata	Descrição
POST	/white-labels	perm-wl-edit	Cria white label
PUT	/white-labels/:companyUuid	perm-wl-edit	Atualiza white label
GET	/white-labels	perm-wl-edit-rates	Lista com filtros (escopo: empresa do JWT)
GET	/white-labels/:companyUuid	perm-wl-details	Detalhe completo
GET	/white-labels/:whiteLabelId/fees	perm-wl-edit-rates	Taxas (MDR ou custo efetivo)
GET	/white-labels/fees/effective-cost	perm-wl-edit-rates	Todas as taxas de custo efetivo ativas
GET	/white-labels/lookup/card-brands	perm-wl-edit-rates	Bandeiras (card_brands)

---

Logs (/logs)

Método	Rota	Descrição
GET	/logs/company/:companyUuid	Console de auditoria (paginação, filtros)
GET	/logs/company/:companyUuid/:id	Detalhe de um registro (api_request_logs)

WebSocket — logs em tempo real

• Namespace: /ws/logs
• Entrar na sala: emitir join com { companyUuid } → recebe joined
• Sair: emitir leave com { companyUuid }
• Evento do servidor: new-log (formato console de auditoria)

---

Configuração global (/global-config)

Tabelas global_* no pool PostgreSQL de auth/tenant. Todas exigem JWT.

Atalhos (escopo global por padrão)

Recurso	GET lista	GET item	PATCH item
Máscaras	/masks-filters	/masks-filters/:fieldKey	/masks-filters/:fieldKey
Taxas	/taxas	/taxas/:fieldKey	/taxas/:fieldKey
E-mail templates	/email-templates	/email-templates/:templateKey	/email-templates/:templateKey

templateKey: welcome, password-reset, first-access, proposal, document-delivery. Detalhes para o frontend: FRONTEND_EMAIL_TEMPLATES.md.

Query opcional: scopeUuid, fieldKeyPrefix (taxas).

Por escopo (/scopes/:scopeUuid/...)

Recurso	Rotas
Máscaras	masks-filters, masks-filters/:fieldKey
Taxas	taxas, taxas/:fieldKey
E-mail templates	email-templates, email-templates/:templateKey
Notificações	notificacoes, notificacoes/:channelKey
Templates de serviço	servico-templates, servico-templates/:templateSlug
Theme tokens	theme-tokens, theme-tokens/:tokenKey

Configurações e overrides

Recurso	Rotas principais
Configurações	GET/PATCH /configuracoes, GET/PATCH /configuracoes/:uuid
Módulos	GET/PATCH /configuracoes/:uuid/modulos, .../:moduleSlug
Overrides máscaras	.../masks-overrides, .../:fieldKey
Overrides notificações	.../notificacoes-overrides, .../:channelKey
Overrides serviço	.../servico-overrides, .../:templateSlug
Overrides theme	.../theme-overrides, .../:tokenKey
CRM roles	GET/PATCH /crm-roles, /crm-roles/:uuid
Escopos governança	GET/PATCH /governance-scopes, /governance-scopes/:uuid
Adquirentes	GET/POST /adquirentes, GET/PUT /adquirentes/:uuid
Credenciamentos	GET/POST /credenciamentos, GET/PUT /credenciamentos/:uuid
Parametrização cartões	GET/POST /global-taxas-parametrizacao-cartoes, GET/PATCH/PUT/DELETE /global-taxas-parametrizacao-cartoes/:uuid
APIs integração	GET/PATCH /integration-apis, /integration-apis/:uuid

Atalhos de overrides sem prefixo configuracoes: /masks-overrides/:configuracaoUuid/...

Parametrização global de cartões (/global-taxas-parametrizacao-cartoes)

Tabela singleton public.global_taxas_parametrizacao_cartoes (singleton_key = 1). Seed: db/global_taxas_parametrizacao_cartoes.sql — regenerar com node scripts/generate-global-taxas-parametrizacao-cartoes-sql.mjs.

Método	Rota	Descrição
GET	/global-taxas-parametrizacao-cartoes	Lista (normalmente 0 ou 1 registro)
GET	/global-taxas-parametrizacao-cartoes/singleton	Registro ativo (singleton_key = 1)
GET	/global-taxas-parametrizacao-cartoes/:uuid	Por UUID
POST	/global-taxas-parametrizacao-cartoes	Cria (409 se singleton já existir)
PATCH	/global-taxas-parametrizacao-cartoes/:uuid	Atualização parcial
PUT	/global-taxas-parametrizacao-cartoes/:uuid	Substituição completa
DELETE	/global-taxas-parametrizacao-cartoes/:uuid	Remove

Override por empresa: rotas em /companies/:companyUuid/taxas-parametrizacao-cartoes (secção Empresas).

Adquirentes e credenciamentos

global_adquirentes inclui catálogo de endpoints da API externa em metadata (array JSON).

Recurso	GET lista	GET item	POST	PUT item
Adquirentes (global_adquirentes)	/adquirentes	/adquirentes/:uuid	/adquirentes	/adquirentes/:uuid
Adquirentes base (sem metadata)	/adquirentes_base	—	—	—
Credenciamentos (global_credenciamento)	/credenciamentos	/credenciamentos/:uuid	/credenciamentos	/credenciamentos/:uuid

Seed: db/global_adquirentes_seed.sql — regenerar com node scripts/generate-adquirentes-seed.mjs.

POST body adquirente: { "nome": "Movingpay", "status": "ativo", "metadata": [{ "titulo": "Transações", "acao": "Listar", "metodo": "GET", "path": "/transacoes", "flag": true }] } (status e metadata opcionais).

PUT body adquirente: { "nome": "...", "status": "inativo", "metadata": [...] } (pelo menos um campo; metadata substitui o catálogo inteiro).

---

Clientes (/clientes)

Tabela public.clientes, filtrada por tenant_id do JWT.

Método	Rota	Descrição
GET	/clientes	Lista (filtros: situacaoAtual, whiteLabelUuid)
GET	/clientes/:uuid	Detalhe
PATCH	/clientes/:uuid	Atualização parcial

---

Módulos de permissão metadata

Identificadores válidos em rotas :module:

dashboard, users, white_label, plans, establishments, terminals_local, compliance, documents_manage, rate_simulator, rate_admin, machine_rental, financial_commissions

Chaves perm-* por módulo: ver Swagger ou src/common/permissions/user-metadata-permissions.config.ts.