Version: 2.0
Fecha: 16 de Marzo, 2026
Estado: NORMATIVO - Referencia Backend para Desarrollo
Ecosistema: Simappe (Backend)
Define los endpoints HTTP backend del ecosistema Simappe que un cliente debe consumir para completar el ciclo: autenticacion → sesion → seleccion de empresa → carga de menus y opciones del usuario. Este documento es la guia conductual de contratos backend: cada fase indica que hacer, en que orden y que esperar del servidor.
Alcance: Solo servicios backend. No describe implementacion de frontend.
Uso: Seguir las fases en orden secuencial. Cada fase depende de la anterior salvo que se indique lo contrario.
┌─────────────────────┐ ┌──────────────────────┐ ┌────────────────────┐
│ Cliente │ │ SimappeGateway │ │ Backend Services │
│ (cualquier frontend │────▶│ (API Gateway) │────▶│ │
│ o integracion) │ │ Puerto: 8090 │ │ OAuth2Server │
│ │ │ Valida JWT │ │ SimappeAdmin │
│ │ │ Rate Limiting │ │ SimappeClient │
│ │ │ Circuit Breaker │ │ │
└─────────────────────┘ └──────────────────────┘ └────────────────────┘
Todas las peticiones HTTP pasan por SimappeGateway. El cliente NO accede directamente a los microservicios.
FASE 1 — Parametros del Sistema (sin autenticacion)
│
├──▶ (1) POST template-parameters/read-active
└──▶ (2) GET system-parameters/read-active
│
FASE 2 — Autenticacion
│
├──▶ (3) GET totp/enabled/{username}
├──▶ (4) POST login ← si NO tiene TOTP
├──▶ (5) POST totp/login ← si SI tiene TOTP
│ Alternativo:
├──▶ (6) POST magic-link/generate
└──▶ (7) GET magic-link/validate
│
▼ ← accessToken + refreshToken obtenidos
│
FASE 3 — Validacion y Datos de Sesion
│
├──▶ (8) POST jwt ← validar token vigente
└──▶ (9) POST jwt-get ← obtener UserSession (roles, customerId)
│
FASE 4 — Seleccion de Empresa (si multiples)
│
├──▶ (10) GET company/read-customer ← listar empresas disponibles
└──▶ (11) POST jwt-select-company ← seleccionar empresa → NUEVO JWT
│
▼ ← nuevo JWT con companyId en payload. Token anterior invalidado.
│
FASE 5 — Carga de Datos de Operacion (en paralelo)
│
├──▶ (12) GET customer/get
├──▶ (13) GET company/get
├──▶ (14) GET customer-parameters/read-customer
└──▶ (15) GET company-parameters/read-company
│
FASE 6 — Perfil de Usuario
│
└──▶ (16) GET user-profile/get-by-identity
│
FASE 7 — Carga de Menus y Opciones del Usuario
│
└──▶ (19) POST menu/read-by-roles ← productos, modulos, opciones por rol
│
FASE 8 — Registro y Mantenimiento de Sesion
│
├──▶ (20) POST login-history/last ← registro de auditoria
├──▶ (17) POST refresh ← automatico, antes de expirar token
└──▶ (18) POST logout ← fire-and-forget al cerrar sesion
│
▼
SESION COMPLETA — Dashboard operativo con menus y opciones cargados
Cuando ejecutar: Al iniciar la aplicacion, antes de cualquier interaccion con el usuario.
Requiere autenticacion: No.
| # | Metodo | Endpoint | Servicio | Body | Respuesta |
|---|---|---|---|---|---|
| 1 | POST |
/simappe-admin/api/v1/template-parameters/read-active |
simappe-admin | {} (vacio) |
TemplateParameter[] — Estructura de parametros configurables |
| 2 | GET |
/simappe-admin/api/v1/system-parameters/read-active |
simappe-admin | — | SystemParameter[] — Parametros globales (idioma, timezone, features) |
Resultado esperado: El cliente tiene la estructura de parametros y configuraciones globales del sistema. Estos datos se usan como base para resolver parametros en fases posteriores.
Cuando ejecutar: Despues de cargar parametros del sistema (Fase 1).
Paso previo obligatorio: Verificar si el usuario tiene TOTP habilitado antes de enviar credenciales.
| # | Metodo | Endpoint | Headers | Respuesta |
|---|---|---|---|---|
| 3 | GET |
/simappe-oauth2-server/api/v1/totp/enabled/{username} |
Ninguno (publico) | boolean — true si TOTP esta habilitado |
| # | Metodo | Endpoint | Body | Headers | Respuesta |
|---|---|---|---|---|---|
| 4 | POST |
/simappe-oauth2-server/api/v1/login |
{ "username": "xxx", "password": "xxx" } |
Content-Type: application/json |
LoginResponse { accessToken, refreshToken, expiresIn } |
| 5 | POST |
/simappe-oauth2-server/api/v1/totp/login |
{ "username": "xxx", "password": "xxx", "totpCode": "123456" } |
Content-Type: application/json |
LoginResponse |
false → usar endpoint (4)true → usar endpoint (5)| # | Metodo | Endpoint | Body / Params | Respuesta |
|---|---|---|---|---|
| 6 | POST |
/simappe-oauth2-server/api/v1/magic-link/generate |
{ "email": "xxx@xxx.com", "redirectUrl": "http://..." } |
Confirmacion de envio |
| 7 | GET |
/simappe-oauth2-server/api/v1/magic-link/validate?token={token} |
Query param: token |
LoginResponse |
Resultado esperado: accessToken y refreshToken obtenidos. A partir de aqui, todas las peticiones deben incluir Authorization: Bearer {accessToken}.
Cuando ejecutar: Inmediatamente despues de obtener el token.
Headers requeridos en adelante:Authorization: Bearer {accessToken}yaccessToken: {accessToken}
| # | Metodo | Endpoint | Headers | Respuesta | Notas |
|---|---|---|---|---|---|
| 8 | POST |
/simappe-oauth2-server/api/v1/jwt |
Authorization: Bearer {accessToken}, accessToken: {accessToken} |
LoginResponse (validacion) |
Se recomienda cachear respuesta ~30 segundos |
| 9 | POST |
/simappe-oauth2-server/api/v1/jwt-get |
Authorization: Bearer {accessToken}, accessToken: {accessToken} |
UserSession |
— |
Estructura de UserSession:
{
"id": 123,
"username": "usuario123",
"firstName": "Carlos",
"lastName": "Torres",
"email": "carlos@empresa.com",
"customerId": 456,
"companyId": null,
"companyName": null,
"customerName": "Empresa ABC",
"roles": [
{ "id": 1, "name": "ROLE_ADMIN" }
]
}
Resultado esperado: Se conoce la identidad del usuario, su customerId y sus roles[]. El companyId sera null hasta completar la Fase 4.
Cuando ejecutar: Despues de obtener
UserSession. Solo si el usuario tiene acceso a multiples empresas.
Paso critico: El endpoint (11) emite un JWT nuevo. El token anterior queda invalidado. Todos los headers deben actualizarse con el nuevo token.
| # | Metodo | Endpoint | Headers | Respuesta | Notas |
|---|---|---|---|---|---|
| 10 | GET |
/simappe-admin/api/v1/company/read-customer?customerId={id} |
Authorization: Bearer {accessToken} |
{ response: { content: Company[] } } |
Lista empresas del cliente |
| 11 | POST |
/simappe-oauth2-server/api/v1/jwt-select-company?companyId={id} |
Authorization: Bearer {accessToken}, accessToken: {accessToken} |
LoginResponse con NUEVO JWT |
El token cambia. Todos los headers deben actualizarse. |
Resultado esperado: Nuevo accessToken con companyId en el payload JWT. Este companyId es el que el backend usa para resolver el tenant (base de datos, configuraciones, modulos).
Cuando ejecutar: Despues de obtener el nuevo JWT con
companyId(Fase 4).
Ejecucion en paralelo: Estos 4 endpoints son independientes y pueden ejecutarse simultaneamente.
| # | Metodo | Endpoint | Headers | Respuesta |
|---|---|---|---|---|
| 12 | GET |
/simappe-admin/api/v1/customer/get?id={customerId} |
Authorization: Bearer {accessToken} |
Customer { id, name, nit, type, ... } |
| 13 | GET |
/simappe-admin/api/v1/company/get?id={companyId} |
Authorization: Bearer {accessToken} |
Company { id, name, nit, ... } |
| 14 | GET |
/simappe-admin/api/v1/customer-parameters/read-customer?customerId={id} |
Authorization: Bearer {accessToken} |
CustomerParameter[] |
| 15 | GET |
/simappe-admin/api/v1/company-parameters/read-company?companyId={id} |
Authorization: Bearer {accessToken} |
CompanyParameter[] |
Jerarquia de parametros:
System<Customer<Company(el mas especifico gana)
Resultado esperado: Se tienen los datos de la empresa, del cliente, y todos los parametros resueltos por jerarquia.
Cuando ejecutar: Despues de cargar datos de operacion (Fase 5).
Excepcion: Se omite para usuarios concustomerId = 1(usuarios internos de plataforma).
| # | Metodo | Endpoint | Headers | Respuesta | Notas |
|---|---|---|---|---|---|
| 16 | GET |
/simappe-client/api/v1/user-profile/get-by-identity?userIdentityId={id} |
Authorization: Bearer {accessToken} |
UserProfileDto o 404 |
Se ejecuta una sola vez y se cachea |
Resultado esperado: Perfil del usuario cargado (datos de contacto, configuracion personal). Si retorna 404, el perfil no existe y el cliente debe manejar esa condicion.
Cuando ejecutar: Despues de validar el perfil del usuario (Fase 6).
Este endpoint es central: Retorna la estructura completa de productos, modulos, grupos y opciones a las que el usuario tiene acceso segun sus roles.
| # | Metodo | Endpoint | Body | Headers | Respuesta |
|---|---|---|---|---|---|
| 19 | POST |
/simappe-admin/api/v1/menu/read-by-roles |
[1, 2, 3] — Array de roleId (numeros) |
Authorization: Bearer {accessToken}, accessToken: {accessToken} |
VMenu[] |
Los roleId se obtienen del array roles[] de la UserSession (Fase 3, endpoint 9).
Estructura de VMenu:
Cada elemento del array VMenu[] es un registro plano que representa una combinacion rol → aplicacion → modulo → grupo → opcion:
{
"roleId": 1,
"roleName": "ROLE_ADMIN",
"roleDescription": "Administrador",
"applicationId": 10,
"applicationCode": "NEBULA_ACC",
"applicationName": "Contabilidad",
"applicationDescription": "Modulo de contabilidad",
"applicationFavicon": "fa-calculator",
"applicationUrl": "/accounting",
"applicationOrder": 1,
"applicationConfig": null,
"moduleId": 100,
"moduleCode": "MOD_CC",
"moduleName": "Centro de Costos",
"moduleDescription": "Gestion de centros de costo",
"moduleIcon": "pi pi-money-bill",
"moduleTooltips": "Centros de costo",
"moduleUrl": "/cost-centers",
"moduleOrder": 1,
"moduleConfig": null,
"optionGroupId": 200,
"optionGroupCode": "GRP_CC_ADMIN",
"optionGroupName": "Administracion",
"optionGroupDescription": "Opciones de administracion",
"optionGroupUrl": "/admin",
"optionGroupOrder": 1,
"optionGroupConfig": null,
"optionId": 300,
"optionCode": "OPT_CC_LIST",
"optionName": "Listar Centros de Costo",
"optionTooltips": "Ver listado",
"optionPath": "list",
"optionFullPath": "/accounting/cost-centers/admin/list",
"optionOrder": 1,
"optionParentItemId": 0,
"optionConfig": null
}
Jerarquia del VMenu:
Application (producto)
└── Module (modulo)
└── Option Group (grupo de opciones)
└── Option (opcion/permiso individual)
El cliente debe agrupar los registros planos por applicationId → moduleId → optionGroupId para construir la navegacion.
Resultado esperado: El cliente conoce todos los productos, modulos y opciones disponibles para el usuario segun sus roles. Con esta informacion se construye el menu de navegacion y se determinan los permisos de acceso.
Cuando ejecutar: El registro de login (20) se ejecuta una vez al cargar el dashboard. El refresh (17) se ejecuta en background de forma continua. El logout (18) al cerrar sesion.
| # | Metodo | Endpoint | Body / Params | Headers | Modo |
|---|---|---|---|---|---|
| 19 | POST |
/simappe-oauth2-server/api/v1/login-history/last |
Query param: username |
Authorization: Bearer {accessToken}, accessToken: {accessToken} |
Una vez, al cargar dashboard |
| 17 | POST |
/simappe-oauth2-server/api/v1/refresh |
{ "refreshToken": "{refreshToken}" } |
Origin: {app-origin} |
Automatico, ~1 min antes de expirar |
| 18 | POST |
/simappe-oauth2-server/api/v1/logout |
{ "accessToken": "{accessToken}" } |
Authorization: Bearer {accessToken}, accessToken: {accessToken} |
Fire-and-forget |
Estructura de LoginHistory:
{
"id": "507f1f77bcf86cd799439011",
"username": "usuario123",
"loginDate": "2026-03-16T14:30:00.000Z",
"ip": "192.168.1.100"
}
El payload del JWT de Simappe contiene:
{
"User": {
"id": 123,
"username": "usuario123",
"customerId": 456,
"companyId": 789
},
"roles": ["ROLE_ADMIN"],
"exp": 1742169600,
"iat": 1742168000
}
Nota: El campo
companyIdsolo se incluye despues de llamar al endpoint (11)jwt-select-company. Antes de eso, el JWT tienecompanyId: null.
| Servicio | # Endpoints | Funcion en el Flujo |
|---|---|---|
| simappe-oauth2-server | 10 | Autenticacion, tokens JWT, TOTP, Magic Link, Refresh, Logout, Login History |
| simappe-admin | 8 | Parametros sistema/cliente/empresa, empresas, clientes, menus por roles |
| simappe-client | 1 | Perfil de usuario |
| SimappeGateway | — | Proxy, validacion JWT, rate limiting (transparente) |
Total de endpoints en el flujo: 20
customerId = 1) el endpoint (16) no se ejecuta.VMenu[] determina que productos, modulos y opciones ve el usuario. El cliente debe filtrar la navegacion basandose exclusivamente en esta respuesta.menu/read-by-roles puede cachearse por ~5 minutos, ya que los roles y permisos no cambian durante una sesion activa.| Version | Fecha | Descripcion |
|---|---|---|
| 1.0.0 | 2026-03-16 | Creacion del documento. Flujo login simappe-admin |
| 1.1.0 | 2026-03-16 | Revision: documento enfocado exclusivamente en contratos backend |
| 2.0.0 | 2026-03-16 | Integracion de Fase 7 (menus/opciones por roles) y Fase 8 (login history). Documento conductual completo |