Guia de Configuração dos Módulos eCosif — Para o Banco
Destinatário: Instituição financeira (banco) que utiliza o sistema eCosif
Objetivo: Explicar como configurar cada módulo do ecossistema para que a solução funcione no ambiente do banco (URLs, variáveis de ambiente, base de dados e integrações).
Este documento deve ser utilizado pela equipa técnica do banco em conjunto com o fornecedor do sistema para definir endereços, segredos e parâmetros de cada serviço.
Versões dos módulos
Versão de cada módulo à data deste documento (para referência na configuração e no suporte):
| Módulo | Versão | Descrição |
|---|---|---|
| ecosif-angular | 0.7.01.202601282 | Frontend (aplicação web) |
| ecosif-auth | 0.7.01.202601280 | Autenticação e JWT |
| ecosif-masterdata | 0.7.01.202601280 | Dados mestres |
| ecosif-moviments | 0.7.01.202601280 | Lançamentos e movimentos |
| ecosif-querys | 0.7.01.202601280 | Consultas |
| ecosif-reports | 0.7.01.202601282 | Relatórios |
| ecosif-compliance | 0.1.02.202509121 | Compliance contábil |
| ecosif-automations | 0.7.01.202601280 | Automatizações (importação, etc.) |
Nota: ao atualizar o sistema, o fornecedor informará as novas versões de cada módulo.
1. Visão geral do ecossistema
O eCosif é composto por:
- Um frontend (aplicação web) — interface utilizada pelos colaboradores do banco.
- Vários serviços de backend (APIs) — autenticação, dados mestres, lançamentos, consultas, relatórios, compliance e automatizações.
Em produção, é habitual expor tudo sob um único domínio (por exemplo https://app.ecosif.banco.com.br), com o frontend na raiz e cada backend num path próprio:
| O quê | URL típica |
|---|---|
| Aplicação web (frontend) | https://app.ecosif.banco.com.br |
| Autenticação | https://app.ecosif.banco.com.br/ecosif-auth |
| Dados mestres | https://app.ecosif.banco.com.br/ecosif-masterdata |
| Lançamentos / movimentos | https://app.ecosif.banco.com.br/ecosif-moviments |
| Consultas | https://app.ecosif.banco.com.br/ecosif-querys |
| Relatórios | https://app.ecosif.banco.com.br/ecosif-reports |
| Compliance | https://app.ecosif.banco.com.br/ecosif-compliance |
| Automatizações (se exposto) | https://app.ecosif.banco.com.br/ecosif-automations |
O banco deve definir qual será o domínio final (ex.: app.ecosif.banco.com.br) e garantir que todos os módulos são configurados com esse valor onde for indicado abaixo.
2. O que o banco precisa de fornecer (resumo)
Antes de configurar cada módulo, o banco deve preparar:
- Domínio / URL base — URL pública onde o sistema será acedido (ex.:
https://app.ecosif.banco.com.br). - Base de dados PostgreSQL — host, porta, nome da base, utilizador e senha (por serviço, se for política do banco ter utilizadores distintos).
- Chave secreta JWT — uma chave forte e única, partilhada entre o módulo de autenticação e os restantes serviços que validam o token.
- Origem CORS — em regra a mesma URL do frontend (ex.:
https://app.ecosif.banco.com.br). - Opcional: credenciais OAuth2 (ex.: Google) ou Azure AD, se o banco quiser login com identidade federada.
- Opcional: credenciais e buckets AWS (S3/SQS), se usar o módulo de automatizações em cloud.
3. Configuração por módulo
3.1 Frontend (ecosif-angular)
Função: Interface web (telas de login, cadastros, lançamentos, consultas, relatórios, administração).
O que o banco configura:
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| URL base das APIs | Paths relativos ao mesmo domínio. Com um único domínio, normalmente são apenas os paths: /ecosif-auth, /ecosif-masterdata, etc. |
Definir no build ou em env.js: authUrl: '/ecosif-auth', apiUrl: '/ecosif-masterdata', etc. |
| Domínio de produção | URL onde os utilizadores acedem à aplicação. | https://app.ecosif.banco.com.br |
| Paginação padrão | Número de registos por página (opcional). | Ex.: 100 |
| Azure AD (opcional) | Se o banco usar login com Azure AD: Client ID e Authority. | Fornecidos pelo Azure Portal |
Não é necessário configurar base de dados no frontend; as chamadas são feitas às APIs nos paths indicados.
3.2 Autenticação (ecosif-auth)
Função: Login (utilizador/senha e, se configurado, OAuth2/Google ou Azure AD), emissão e validação de tokens JWT.
O que o banco configura:
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| Host PostgreSQL | POSTGRES_HOST |
Servidor da base de dados | postgres.banco.internal ou endereço RDS |
| Porta PostgreSQL | POSTGRES_PORT |
Porta do PostgreSQL | 5432 |
| Nome da base | POSTGRES_DB |
Nome do base de dados | ecosif |
| Utilizador da base | POSTGRES_USER |
Utilizador com permissões no schema do auth | ecosif_auth |
| Senha da base | POSTGRES_PASSWORD |
Senha do utilizador | (definir de forma segura) |
| Chave secreta JWT | AUTH_TOKEN_SECRET |
Chave para assinar e validar tokens (todos os serviços que validam JWT usam a mesma) | String longa e aleatória |
| Validade do token | TOKEN_EXPIRATION |
Tempo de vida do token em milissegundos | 86400000 (24 horas) |
| Origens CORS | ECOSIF_CORS |
URL do frontend (origem permitida) | https://app.ecosif.banco.com.br |
| OAuth2 Google (opcional) | AUTH2_CLIENT_ID, AUTH2_SECRET |
Se o banco oferecer login com Google | Valores do Google Cloud Console |
| Migrações Flyway | ECOSIF_FLYWAY_ENABLED |
Executar migrações de schema na arranque | true ou false (conforme combinado) |
O serviço deve ser exposto no path /ecosif-auth (configuração de context path no servidor ou no API Gateway).
3.3 Dados mestres (ecosif-masterdata)
Função: Gestão de empresas, filiais, planos de contas, fundos, históricos, utilizadores (dados de referência).
O que o banco configura:
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| Host PostgreSQL | POSTGRES_HOST |
Servidor da base de dados | Igual ao do auth (ou outro, se política assim o exigir) |
| Porta PostgreSQL | POSTGRES_PORT |
Porta do PostgreSQL | 5432 |
| Nome da base | POSTGRES_DB |
Nome da base | ecosif |
| Utilizador da base | POSTGRES_USER |
Utilizador com permissões no schema | ecosif_masterdata |
| Senha da base | POSTGRES_PASSWORD |
Senha do utilizador | (definir de forma segura) |
| Chave JWT | AUTH_TOKEN_SECRET |
A mesma que no ecosif-auth (para validar tokens) | Mesmo valor do auth |
| Validade do token | TOKEN_EXPIRATION |
Referência (ex.: 24h) | 86400000 |
| Origens CORS | ECOSIF_CORS |
URL do frontend | https://app.ecosif.banco.com.br |
| AWS S3 (opcional) | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_S3_BUCKET |
Se houver integração com S3 para ficheiros | Conforme ambiente AWS do banco |
O serviço deve ser exposto no path /ecosif-masterdata.
3.4 Lançamentos / Movimentos (ecosif-moviments)
Função: Lançamentos contábeis, lotes, consolidação, encerramento, importação de ficheiros (ex.: IPL).
O que o banco configura:
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| Host PostgreSQL | POSTGRES_HOST |
Servidor da base de dados | Igual aos outros serviços |
| Porta PostgreSQL | POSTGRES_PORT |
Porta do PostgreSQL | 5432 |
| Nome da base | POSTGRES_DB |
Nome da base | ecosif |
| Utilizador da base | POSTGRES_USER |
Utilizador com permissões | ecosif_moviments |
| Senha da base | POSTGRES_PASSWORD |
Senha do utilizador | (definir de forma segura) |
| Chave JWT | AUTH_TOKEN_SECRET |
A mesma que no ecosif-auth | Mesmo valor do auth |
| Validade do token | TOKEN_EXPIRATION |
Referência | 86400000 |
| Origens CORS | ECOSIF_CORS |
URL do frontend | https://app.ecosif.banco.com.br |
| Flyway | ECOSIF_FLYWAY_ENABLED |
Executar migrações na arranque | true ou false |
| AWS S3 (opcional) | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_S3_BUCKET |
Buckets para importação/erro/relatórios | Conforme ambiente AWS |
O serviço deve ser exposto no path /ecosif-moviments.
3.5 Consultas (ecosif-querys)
Função: Consultas de saldos, razão, listagens (apenas leitura).
O que o banco configura:
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| Host PostgreSQL | POSTGRES_HOST |
Servidor da base de dados | Igual aos outros serviços |
| Porta PostgreSQL | POSTGRES_PORT |
Porta do PostgreSQL | 5432 |
| Nome da base | POSTGRES_DB |
Nome da base | ecosif |
| Utilizador da base | POSTGRES_USER |
Utilizador (leitura) | ecosif_querys |
| Senha da base | POSTGRES_PASSWORD |
Senha do utilizador | (definir de forma segura) |
| Chave JWT | AUTH_TOKEN_SECRET |
A mesma que no ecosif-auth | Mesmo valor do auth |
| Validade do token | TOKEN_EXPIRATION |
Referência | 86400000 |
| Origens CORS | ECOSIF_CORS |
URL do frontend | https://app.ecosif.banco.com.br |
O serviço deve ser exposto no path /ecosif-querys.
3.6 Relatórios (ecosif-reports)
Função: Geração de relatórios contábeis (PDF, CSV, TXT), por exemplo balancetes e razão.
O que o banco configura:
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| Host PostgreSQL | POSTGRES_HOST |
Servidor da base de dados | Igual aos outros serviços |
| Porta PostgreSQL | POSTGRES_PORT |
Porta do PostgreSQL | 5432 |
| Nome da base | POSTGRES_DB |
Nome da base | ecosif |
| Utilizador da base | POSTGRES_USER |
Utilizador (leitura para relatórios) | ecosif_reports |
| Senha da base | POSTGRES_PASSWORD |
Senha do utilizador | (definir de forma segura) |
| Chave JWT | AUTH_TOKEN_SECRET |
A mesma que no ecosif-auth | Mesmo valor do auth |
| Validade do token | TOKEN_EXPIRATION |
Referência | 86400000 |
| Origens CORS | ECOSIF_CORS |
URL do frontend | https://app.ecosif.banco.com.br |
O serviço deve ser exposto no path /ecosif-reports.
3.7 Compliance (ecosif-compliance)
Função: Validação e conformidade contábil (regras COSIF/CVM); motor de regras; API REST com documentação Swagger.
O que o banco configura:
A aplicação usa um ficheiro de configuração (ex.: config.json ou config-prod.json) onde muitos valores podem ser definidos por variáveis de ambiente. Seguem os principais:
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| Porta HTTP | ECOSIF_COMPLIANCE_PORT |
Porta em que o serviço escuta | 8021 |
| Host PostgreSQL | ECOSIF_DB_SERVER |
Servidor da base de dados | Igual aos outros serviços |
| Porta PostgreSQL | ECOSIF_DB_PORT |
Porta do PostgreSQL | 5432 |
| Nome da base | ECOSIF_DB_LOGIN |
Nome da base | ecosif |
| Utilizador da base | ECOSIF_DB_USER |
Utilizador | postgres ou utilizador dedicado |
| Senha da base | ECOSIF_DB_PASSWORD |
Senha do utilizador | (definir de forma segura) |
| Origens CORS | ECOSIF_CORS |
URL do frontend | https://app.ecosif.banco.com.br |
| Timeout de sessão | ECOSIF_SESSION_TIMEOUT |
Tempo de sessão em minutos (opcional) | 30 |
| Ambiente de config | ECOSIF_RUNTIME_ENVIRONMENT |
Escolha do ficheiro (ex.: prod → config-prod.json) |
prod |
O serviço deve ser exposto no path /ecosif-compliance. As regras de negócio (e tolerâncias) são geridas na base de dados ou via API, não por variáveis de ambiente.
3.8 Automatizações (ecosif-automations)
Função: Importação automática de ficheiros (ex.: .IPL, .CT32.LD), tipicamente accionada por eventos (S3, filas). Pode correr como Lambdas na AWS ou como serviço em ECS.
O que o banco configura (quando o módulo chama as APIs do eCosif):
| Parâmetro | Variável de ambiente (exemplo) | Descrição | Exemplo de valor |
|---|---|---|---|
| URL base das APIs | ECOSIF_API_BASE_URL |
URL pública onde estão os outros serviços | https://app.ecosif.banco.com.br |
| Modo | ECOSIF_LOCAL_MODE |
false para usar S3/SQS na AWS |
false |
| Região AWS | AWS_REGION |
Região dos recursos (bucket, filas) | us-east-1 |
| Bucket S3 | AWS_S3_BUCKET_NAME ou AWS_S3_BUCKET |
Bucket para ficheiros de entrada e saída | Nome do bucket definido pelo banco |
| Fila SQS (entries) | AWS_SQS_QUEUE_URL / AWS_SQS_ENTRIES_QUEUE_URL |
URLs das filas (conforme desenho) | URLs fornecidas pelo banco/fornecedor |
Com ECOSIF_API_BASE_URL=https://app.ecosif.banco.com.br, o módulo chamará automaticamente https://app.ecosif.banco.com.br/ecosif-moviments e https://app.ecosif.banco.com.br/ecosif-masterdata conforme necessário. Credenciais AWS (acesso a S3/SQS) devem ser fornecidas via IAM roles (Lambdas/ECS) ou variáveis de ambiente, conforme política do banco.
4. Checklist para o banco
- [ ] Definir o domínio final do sistema (ex.:
https://app.ecosif.banco.com.br). - [ ] Preparar a base de dados PostgreSQL (instância, utilizadores e senhas por serviço, se aplicável).
- [ ] Definir e guardar de forma segura a chave JWT (
AUTH_TOKEN_SECRET) e usá-la em todos os serviços que validam token. - [ ] Configurar CORS em todos os backends com a URL exata do frontend (incluindo
https://). - [ ] Em cada módulo, definir context path (ou equivalente) para o path indicado (
/ecosif-auth,/ecosif-masterdata, etc.) ou garantir que o API Gateway/load balancer encaminha esses paths para o serviço correto. - [ ] Se usar OAuth2/Google ou Azure AD: obter credenciais e configurar apenas no ecosif-auth (e, no frontend, se for Azure AD).
- [ ] Se usar AWS (S3/SQS) para automatizações: preparar bucket, filas e credenciais IAM e configurar no ecosif-automations (e nos módulos que usam S3, se aplicável).
5. Contacto e documentação técnica
Para detalhes técnicos de cada módulo (portas, logs, actuator, Docker, etc.), o banco pode consultar a documentação operacional de cada repositório (pasta docs/ de cada módulo), em particular:
ecosif-angular/docs/operational.mdeecosif-angular/docs/aws-ecs-api-gateway.mdecosif-auth/docs/operational.mdeecosif-auth/docs/aws-ecs-api-gateway.md- E equivalentes para ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports, ecosif-compliance e ecosif-automations.
Em caso de dúvida sobre valores concretos (ex.: nomes de variáveis ou formato de URLs), a equipa do fornecedor do sistema deve ser contactada para alinhar com a infraestrutura e políticas de segurança do banco.
Equipe eCosif · Documento para entrega ao banco · Configuração dos módulos