POST /api/solicitudes/guardar-solicitud

Este grupo de endpoints permite a un afiliado autenticado crear, consultar y eliminar sus solicitudes de crédito. El endpoint principal POST /api/solicitudes/guardar-solicitud es el destino final del wizard multi-paso de la aplicación: recibe el payload completo con la información de la solicitud, del solicitante y todos los datos complementarios, los valida con Zod y los persiste en la base de datos. El owner_username se toma directamente de la sesión activa del usuario, no del cuerpo de la petición, garantizando que una solicitud siempre pertenezca al afiliado autenticado.

Autenticación: Requiere sesión activa.

Cuerpo de la petición

El payload es un objeto JSON con las secciones del wizard. Todas las secciones excepto solicitud son opcionales a nivel del schema, aunque el negocio requiere que estén completas para avanzar en el ciclo de vida.

Sección `solicitud` (requerida)

object

required

Datos principales de la solicitud de crédito.

Show Campos de solicitud

number

required

Monto total solicitado en pesos colombianos (COP). Debe ser un número no negativo.

integer

required

Plazo de pago expresado en meses. Número entero no negativo.

number

Tasa de interés mensual aplicada al crédito. Número no negativo. Opcional si la línea de crédito define la tasa automáticamente.

number

Cuota mensual calculada en pesos COP.

string

Estado inicial de la solicitud. Por defecto "POSTULADO" si no se especifica.

string

Tipo de producto crediticio solicitado (ej. "LIBRE_INVERSION", "VIVIENDA").

string

Clasificación del crédito según el catálogo de Comfaca.

string

Moneda de la solicitud. Por defecto "COP".

string

Descripción de la modalidad de crédito seleccionada.

boolean

Indica si el afiliado ya tuvo un crédito anterior con Comfaca.

string

Rol del usuario en la solicitud. Valores válidos: "T" (Titular), "S" (Solicitante), "C" (Codeudor), "E" (Empleado).

string

Nombre de usuario propietario. Se asigna automáticamente desde la sesión si no se incluye.

Sección `solicitante` (opcional en schema, requerida en negocio)

object

Datos personales y laborales del solicitante principal.

Show Campos de solicitante

string

"natural" o "juridica". También acepta objeto {label, value} desde el wizard.

string

Código del tipo de documento de identidad (ej. "CC", "CE").

string

Número de documento de identidad.

string

Nombres del solicitante.

string

Apellidos del solicitante.

Razón social (aplica solo para personas jurídicas).

string

NIT de la empresa (aplica solo para personas jurídicas).

string

Código del país de nacimiento del solicitante (ej. "CO").

string

Fecha de nacimiento en formato ISO 8601 ("YYYY-MM-DD").

string

Fecha de expedición del documento de identidad en formato ISO 8601 ("YYYY-MM-DD").

string

Género del solicitante: "M" (Masculino), "F" (Femenino), "O" (Otro).

string

Estado civil según catálogo de parámetros (ej. "S", "C", "U").

string

Nivel educativo: "primaria", "bachillerato", "tecnico", "universitario", "posgrado", "ninguno".

string

Profesión u ocupación del solicitante.

string

Correo electrónico del solicitante.

string

Teléfono móvil del solicitante.

string

Teléfono fijo del solicitante.

string

Dirección de residencia.

string

Barrio de residencia.

string

Ciudad de residencia. Acepta string o objeto {label, value, description}.

string

Departamento de residencia.

string

País de residencia (código ISO).

string

Tipo de vivienda: "N" (Ninguna), "F" (Familiar), "P" (Propia), "A" (Arrendada), "H" (Hipotecada).

integer

Número de personas a cargo del solicitante. Mínimo 0.

string

Cargo o posición laboral actual.

number

Salario mensual en pesos COP. No negativo.

integer

Antigüedad laboral en meses. Mínimo 0.

string

Tipo de contrato laboral según catálogo.

string

Sector económico de la empresa empleadora.

string

Código de la categoría del afiliado en Comfaca.

boolean

Indica si el solicitante vive con su núcleo familiar.

Secciones adicionales del wizard

any

Datos de la línea de crédito seleccionada (convenio, producto, condiciones especiales).

any

Datos del cónyuge o compañero permanente del solicitante (cuando aplica).

any

Información detallada del empleo actual del solicitante.

any

Relación de ingresos mensuales y descuentos de nómina existentes.

any

Resumen de la situación económica general del solicitante.

any

Lista de propiedades (bienes inmuebles o vehículos) del solicitante.

any

Relación de deudas activas del solicitante con otras entidades.

any

Referencias familiares y personales del solicitante.

Respuestas

boolean

true cuando la solicitud fue creada exitosamente.

string

"Solicitud guardada exitosamente."

object

Objeto con los datos de la solicitud creada, incluyendo el numero_solicitud generado y todos los campos persistidos.

Tabla de errores

Código HTTP	Causa	Descripción
`401`	Sin sesión	No hay sesión activa o expiró.
`422`	Validación Zod	`valor_solicitud` o `plazo_meses` ausentes, `rol_en_solicitud` inválido u otro fallo de schema.
`429`	Límite alcanzado	El afiliado superó el número máximo de solicitudes activas permitidas.
`502`	Error de backend	Fallo al persistir en la base de datos o al conectar con el servicio.

Ejemplo — Petición JSON

{
  "solicitud": {
    "valor_solicitud": 5000000,
    "plazo_meses": 24,
    "tasa_interes": 1.5,
    "cuota_mensual": 242872,
    "estado": "POSTULADO",
    "producto_tipo": "LIBRE_INVERSION",
    "tipo_credito": "LI",
    "moneda": "COP",
    "detalle_modalidad": "Libre Inversión",
    "ha_tenido_credito": false,
    "rol_en_solicitud": "T"
  },
  "solicitante": {
    "tipo_persona": "natural",
    "tipo_documento": "CC",
    "numero_documento": "1012345678",
    "nombres": "JUAN CARLOS",
    "apellidos": "PÉREZ GÓMEZ",
    "fecha_nacimiento": "1985-06-15",
    "genero": "M",
    "estado_civil": "S",
    "nivel_educativo": "universitario",
    "email": "juan.perez@empresa.com",
    "telefono_movil": "3001234567",
    "direccion": "Cra 15 # 93-47",
    "barrio": "Chicó",
    "ciudad": "11001",
    "departamento": "11",
    "pais_residencia": "CO",
    "tipo_vivienda": "A",
    "personas_a_cargo": 0,
    "cargo": "INGENIERO DE SISTEMAS",
    "salario": 4500000,
    "antiguedad_meses": 36,
    "tipo_contrato": "INDEFINIDO",
    "sector_economico": "TEC",
    "codigo_categoria": "A",
    "vive_con_nucleo_familiar": true
  },
  "informacion_laboral": {
    "empresa": "Tech Solutions SAS",
    "nit_empresa": "900123456-1",
    "telefono_empresa": "6012345678",
    "direccion_empresa": "Calle 72 # 12-65"
  }
}

Ejemplo — cURL

curl -X POST http://localhost:4000/api/solicitudes/guardar-solicitud \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d @solicitud-payload.json

Ejemplo — Respuesta exitosa `200`

{
  "success": true,
  "message": "Solicitud guardada exitosamente.",
  "data": {
    "numero_solicitud": "000001-202501-LI",
    "owner_username": "juan.perez",
    "estado": "POSTULADO",
    "valor_solicitud": 5000000,
    "plazo_meses": 24,
    "tasa_interes": 1.5,
    "cuota_mensual": 242872,
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}

GET /api/solicitudes/mis-solicitudes

Lista todas las solicitudes de crédito del usuario autenticado con soporte de paginación mediante limit y offset. Autenticación: Requiere sesión activa.

Query Parameters

integer

default:"20"

Número máximo de solicitudes a retornar por página. Por defecto 20.

integer

default:"0"

Número de solicitudes a omitir para la paginación. Por defecto 0.

Respuesta exitosa `200`

array

Lista de solicitudes del usuario. Cada elemento contiene el detalle de la solicitud.

integer

Total de solicitudes del usuario (para calcular páginas).

integer

El límite aplicado en esta consulta.

integer

El offset aplicado en esta consulta.

Ejemplo — cURL

curl -X GET "http://localhost:4000/api/solicitudes/mis-solicitudes?limit=10&offset=0" \
  -b cookies.txt

Ejemplo — Respuesta `200`

{
  "success": true,
  "message": "Solicitudes obtenidas exitosamente",
  "data": {
    "solicitudes": [
      {
        "numero_solicitud": "000001-202501-LI",
        "estado": "POSTULADO",
        "valor_solicitud": 5000000,
        "plazo_meses": 24,
        "created_at": "2025-01-15T10:30:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

GET /api/solicitudes/:id

Obtiene el detalle completo de una solicitud de crédito por su numero_solicitud. Incluye los registros de PDFs generados asociados. Autenticación: Requiere sesión activa. Solo el propietario de la solicitud puede consultarla.

Path Parameters

string

required

El numero_solicitud de la solicitud a consultar. Formato: "000001-202501-LI".

Tabla de errores

Código HTTP	Causa	Descripción
`400`	ID ausente	No se proporcionó el parámetro `id`.
`401`	Sin sesión	No hay sesión activa.
`403`	Sin permisos	La solicitud pertenece a otro usuario.
`404`	No encontrada	No existe una solicitud con ese `numero_solicitud`.

Ejemplo — cURL

curl -X GET http://localhost:4000/api/solicitudes/000001-202501-LI \
  -b cookies.txt

Ejemplo — Respuesta `200`

{
  "success": true,
  "data": {
    "numero_solicitud": "000001-202501-LI",
    "owner_username": "juan.perez",
    "estado": "DOCUMENTOS_CARGADOS",
    "valor_solicitud": "5000000",
    "plazo_meses": 24,
    "tasa_interes": "1.5",
    "cuota_mensual": "242872",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T09:00:00.000Z",
    "pdfs_generados": null
  }
}

Los campos numéricos de tipo BigInt (como valor_solicitud y tasa_interes) son serializados como strings para compatibilidad JSON. El cliente debe parsearlos a número si los necesita para cálculos.

DELETE /api/solicitudes/:id

Elimina una solicitud de crédito de forma permanente. Solo el propietario de la solicitud o un usuario con rol administrator pueden ejecutar esta operación. Autenticación: Requiere sesión activa.

Path Parameters

string

required

El numero_solicitud de la solicitud a eliminar.

Tabla de errores

Código HTTP	Causa	Descripción
`400`	ID ausente	No se proporcionó el parámetro `id`.
`401`	Sin sesión	No hay sesión activa.
`403`	Sin permisos	El usuario no es propietario ni administrador.
`404`	No encontrada	No existe la solicitud con ese ID.

Ejemplo — cURL

curl -X DELETE http://localhost:4000/api/solicitudes/000001-202501-LI \
  -b cookies.txt

Ejemplo — Respuesta `200`

{
  "success": true,
  "message": "Solicitud eliminada exitosamente",
  "data": null
}

La eliminación es permanente e irreversible. Todos los documentos y datos asociados a la solicitud también serán eliminados en cascada. Solo ejecuta esta operación si estás completamente seguro.

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

POST /api/solicitudes/guardar-solicitud — Crear Solicitud de Crédito