API Admin de Solicitudes de Crédito — Comfaca Créditos

El grupo de endpoints administrativos de solicitudes otorga a los usuarios con rol administrador control total sobre el ciclo de vida de las solicitudes de crédito en Comfaca Créditos en Línea. Desde este panel es posible consultar el historial completo con su timeline, actualizar campos del expediente, cambiar el estado de la solicitud con trazabilidad automática, iniciar el proceso de firma digital y administrar la lista de firmantes asociados.

Todos los endpoints de esta sección requieren una sesión activa con rol administrador. Las peticiones sin sesión o con rol insuficiente recibirán un error 401 Unauthorized o 403 Forbidden.

GET /api/admin/solicitudes

Lista todas las solicitudes de crédito con soporte de paginación y filtros opcionales.

Query Parameters

string

Filtra las solicitudes por estado. Valores posibles: POSTULADO, DOCUMENTOS_CARGADOS, ENVIADO_VALIDACION, APROBADA, RECHAZADA, DESESTIMADA, CANCELADA, DESISTE, PENDIENTE_FIRMADO, FIRMADO.

number

default:"20"

Número máximo de solicitudes a devolver por página. Debe ser un entero positivo.

number

default:"0"

Número de solicitudes a omitir para la paginación (offset). Debe ser un entero no negativo.

Response

boolean

true cuando la operación se ejecuta correctamente.

string

Mensaje descriptivo del resultado ("Solicitudes obtenidas exitosamente").

object

Show Estructura del objeto data

array

Array de objetos SolicitudAdmin. Ver estructura completa en la sección de tipos.

object

Show Campos de paginación

number

Número de página actual.

number

Tamaño de la página.

number

Total de solicitudes que coinciden con los filtros.

number

Total de páginas disponibles.

boolean

Indica si hay una página siguiente.

boolean

Indica si hay una página anterior.

curl -X GET "https://app.comfaca.com/api/admin/solicitudes?estado=APROBADA&limit=10&skip=0" \
  -H "Cookie: nuxt-session=<token>"

GET /api/admin/solicitudes/:id

Obtiene el detalle completo de una solicitud de crédito incluyendo el payload del solicitante, la lista de documentos adjuntos, el timeline de cambios de estado y los firmantes asociados.

Path Parameters

string

required

El numero_solicitud único que identifica la solicitud. Ejemplo: SOL-2024-000123.

Response

object

Show Estructura de SolicitudAdmin

string

Identificador interno de la solicitud.

string

Número de solicitud legible.

string

Estado actual de la solicitud.

number

Monto solicitado en pesos colombianos.

number

Plazo del crédito en meses.

string

Código del tipo de crédito (máx. 3 caracteres).

string

Descripción de la modalidad crediticia.

string

Username del solicitante propietario de la solicitud.

string

Fecha de creación en ISO 8601.

string

Fecha de última actualización en ISO 8601.

object

Show Datos del solicitante

string

Nombres del solicitante.

string

Apellidos del solicitante.

string

Correo electrónico.

string

Número de documento de identidad.

string

Tipo de documento (CC, CE, NIT, etc.).

string

Teléfono de contacto.

array

Show Entradas del timeline

string

Estado registrado en este evento.

string

Fecha del evento en ISO 8601.

string

Descripción detallada del cambio.

string

Nota adicional del administrador.

array

Show Documentos adjuntos

string

ID del documento.

string

Nombre original del archivo subido.

string

Nombre del archivo en almacenamiento.

string

Tipo MIME del archivo.

number

Tamaño en bytes.

string

Fecha de carga.

PUT /api/admin/solicitudes/:id

Actualiza los campos técnicos y financieros de una solicitud de crédito. Todos los campos son opcionales; solo se actualizan los que se envían en el body.

Path Parameters

string

required

El numero_solicitud de la solicitud a actualizar.

Body

string

Nuevo estado de la solicitud. Use el endpoint /estado dedicado para cambios de estado con notificaciones automáticas.

number

Monto solicitado. Debe ser un número positivo.

number

Plazo del crédito en meses. Entero positivo.

number

Tasa de interés aplicable. Valor no negativo.

string

Código del producto (máx. 2 caracteres).

boolean

Indica si el solicitante ha tenido créditos anteriores con COMFACA.

string

Descripción de la modalidad crediticia (máx. 255 caracteres).

string

Código del tipo de crédito (máx. 3 caracteres).

string

Código de moneda ISO 4217 (máx. 3 caracteres). Por defecto COP.

number

Valor de la cuota mensual calculada. No negativo.

string

Fecha de radicación en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ).

Response

object

Show Campos retornados

string

Número de solicitud actualizada.

string

Estado actual tras la actualización.

string

Monto actualizado serializado como string.

PUT /api/admin/solicitudes/:id/estado

Cambia el estado de una solicitud de crédito. Este endpoint va más allá de una simple actualización: registra automáticamente una entrada en el timeline de la solicitud y envía una notificación en tiempo real al solicitante con el nuevo estado y el mensaje correspondiente.

Path Parameters

string

required

El numero_solicitud de la solicitud.

Body

string

required

Nuevo estado a asignar. Estados reconocidos con mensajes automáticos:

APROBADA — “Tu solicitud de crédito ha sido aprobada.”
DESESTIMADA — “Tu solicitud de crédito ha sido desestimada por falta de requisitos.”
RECHAZADA — “Tu solicitud de crédito ha sido rechazada.”
CANCELADA — “Tu solicitud de crédito ha sido cancelada.”
DESISTE — “Has desistido de continuar con tu solicitud de crédito.”

string

Nota adicional del administrador que se adjunta al mensaje del timeline y a la notificación. Útil para explicar el motivo del cambio de estado.

Response

object

Show Campos retornados

string

Número de solicitud cuyo estado fue modificado.

string

Nuevo estado registrado.

curl -X PUT "https://app.comfaca.com/api/admin/solicitudes/SOL-2024-000123/estado" \
  -H "Content-Type: application/json" \
  -H "Cookie: nuxt-session=<token>" \
  -d '{
    "estado": "APROBADA",
    "descripcion": "Documentación verificada. Crédito aprobado por comité."
  }'

{
  "success": true,
  "message": "Estado actualizado exitosamente",
  "data": {
    "numero_solicitud": "SOL-2024-000123",
    "estado": "APROBADA"
  },
  "timestamp": "2024-11-15T14:32:10.000Z"
}

El cambio de estado registra automáticamente al administrador autenticado (username) en la entrada del timeline. Si la sesión no está disponible, se registra como "sistema".

POST /api/admin/solicitudes/:id/iniciar-firmado

Inicia el proceso de firma digital de una solicitud de crédito. Este endpoint reemplaza los firmantes existentes en la base de datos, crea los nuevos registros, invoca el servicio externo de firma digital y actualiza el estado de la solicitud a PENDIENTE_FIRMADO.

Path Parameters

string

required

El numero_solicitud de la solicitud a enviar a firma.

Body

array

required

Lista de firmantes del proceso. Debe contener al menos un firmante.

Show Estructura de cada firmante

string

required

Identificador único del firmante en el sistema externo.

number

required

Orden de firma (1 = firma primero). Se asigna automáticamente si no se proporciona.

string

Tipo de firmante. Valor por defecto "1".

string

required

Nombre completo del firmante.

string

required

Número de documento de identidad del firmante.

string

required

Correo electrónico al que se enviará el enlace de firma.

string

required

Rol del firmante dentro del proceso (ej. "deudor", "codeudor", "representante").

string

Teléfono de contacto del firmante.

string

Código de país para el teléfono. Por defecto "57" (Colombia).

Response

object

Datos retornados por el servicio externo de firma digital incluyendo el transaccion_id del proceso iniciado.

curl -X POST "https://app.comfaca.com/api/admin/solicitudes/SOL-2024-000123/iniciar-firmado" \
  -H "Content-Type: application/json" \
  -H "Cookie: nuxt-session=<token>" \
  -d '{
    "firmantes": [
      {
        "id": "firm-001",
        "orden": 1,
        "tipo": "1",
        "nombre_completo": "Carlos Andrés Pérez",
        "numero_documento": "10245678",
        "email": "carlos.perez@correo.com",
        "rol": "deudor",
        "telefono": "3001234567",
        "codigo_pais": "57"
      },
      {
        "id": "firm-002",
        "orden": 2,
        "tipo": "1",
        "nombre_completo": "María Lucía Torres",
        "numero_documento": "52345678",
        "email": "maria.torres@correo.com",
        "rol": "codeudor",
        "codigo_pais": "57"
      }
    ]
  }'

{
  "success": true,
  "message": "Proceso de firmado iniciado exitosamente",
  "data": {
    "transaccion_id": "TXN-2024-ABC123",
    "estado": "PENDIENTE_FIRMADO",
    "firmantes_registrados": 2
  },
  "timestamp": "2024-11-15T14:45:00.000Z"
}

Al ejecutarse correctamente, el estado de la solicitud cambia a PENDIENTE_FIRMADO y se registra una entrada en el timeline con el transaccion_id del proceso de firma.

GET /api/admin/solicitudes/:id/firmantes

Obtiene la lista de firmantes registrados para una solicitud de crédito, ordenados por el campo orden de forma ascendente.

Path Parameters

string

required

El numero_solicitud de la solicitud.

Response

array

Array de objetos firmante ordenados por orden.

Show Estructura de cada firmante

string

ID del firmante (serializado desde BigInt).

string

ID de la solicitud asociada.

number

Orden de firma.

string

Tipo de firmante.

string

Nombre completo del firmante.

string

Número de documento.

string

Correo electrónico del firmante.

string

Rol en el proceso de firma.

string

Fecha de creación en ISO 8601.

string

Fecha de última modificación en ISO 8601.

DELETE /api/admin/solicitudes/:id/firmantes

Elimina un firmante específico de una solicitud de crédito. Requiere el firmanteId en el body de la petición.

Path Parameters

string

required

El numero_solicitud de la solicitud.

Body

string

required

ID numérico del firmante a eliminar (se recibe como string y se convierte a BigInt internamente).

Response

null

null cuando la eliminación es exitosa.

string

"Firmante eliminado exitosamente" cuando la operación concluye sin errores.

GET /api/admin/solicitudes/estados-count

Devuelve un conteo rápido de solicitudes agrupadas por estado. Ideal para renderizar badges y resúmenes estadísticos en el panel de administración sin cargar el listado completo.

Query Parameters

No acepta parámetros de consulta.

Response

object

Objeto plano donde cada clave es un estado y su valor es la cantidad de solicitudes en ese estado.

{
  "success": true,
  "message": "Conteo por estados obtenido",
  "data": {
    "POSTULADO": 12,
    "DOCUMENTOS_CARGADOS": 8,
    "ENVIADO_VALIDACION": 5,
    "APROBADA": 34,
    "PENDIENTE_FIRMADO": 3,
    "FIRMADO": 27,
    "RECHAZADA": 6,
    "DESESTIMADA": 2,
    "CANCELADA": 1,
    "DESISTE": 4
  },
  "timestamp": "2024-11-15T15:00:00.000Z"
}

Usa GET /api/admin/solicitudes/estados-count como consulta ligera para refrescar los contadores del dashboard cada cierto intervalo. Es más eficiente que consultar el endpoint de listado completo solo para obtener totales.

Tipo `SolicitudAdmin`

Estructura TypeScript completa que representa una solicitud en el contexto administrativo:

interface SolicitudAdmin {
  id: string
  created_at: string
  updated_at: string
  estado: string
  valor_solicitud?: number
  plazo_meses?: number
  numero_solicitud?: string
  tipcre?: string
  tipo_credito?: string
  detalle_modalidad?: string
  owner_username: string
  payload?: {
    informacion_laboral?: InformacionLaboral
    ingresos_descuentos?: IngresosDescuentos
    informacion_economica?: InformacionEconomica
    linea_credito?: LineaCreditoSimulador
  }
  timeline: Array<{
    estado: string
    fecha: string
    detalle?: string
    descripcion?: string
  }>
  documentos?: Array<{
    id: string
    documento_requerido_id: string
    nombre_original: string
    saved_filename: string
    tipo_mime: string
    tamano_bytes: number
    created_at: string
  }>
  solicitante?: {
    email: string
    nombres: string
    apellidos: string
    numero_documento: string
    telefono_movil: string
    tipo_documento: string
  }
}

Filtros disponibles (`FiltrosSolicitudes`)

interface FiltrosSolicitudes {
  fecha_desde?: string
  fecha_hasta?: string
  rango_fechas?: { inicio: string; fin: string }
  numero_documento?: string
  nombre_usuario?: string
  owner_username?: string
  estados?: string[]
  numero_solicitud?: string
  monto_minimo?: number
  monto_maximo?: number
  skip?: number
  limit?: number
  ordenar_por?: string
  orden_direccion?: "asc" | "desc"
}

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

API Admin de Solicitudes de Crédito — Comfaca Créditos

GET /api/admin/solicitudes

Query Parameters

Response

GET /api/admin/solicitudes/:id

Path Parameters

Response

PUT /api/admin/solicitudes/:id

Path Parameters

Body

Response

PUT /api/admin/solicitudes/:id/estado

Path Parameters

Body

Response

POST /api/admin/solicitudes/:id/iniciar-firmado

Path Parameters

Body

Response

GET /api/admin/solicitudes/:id/firmantes

Path Parameters

Response

DELETE /api/admin/solicitudes/:id/firmantes

Path Parameters

Body

Response

GET /api/admin/solicitudes/estados-count

Query Parameters

Response

Tipo `SolicitudAdmin`

Filtros disponibles (`FiltrosSolicitudes`)

​GET /api/admin/solicitudes

​Query Parameters

​Response

​GET /api/admin/solicitudes/:id

​Path Parameters

​Response

​PUT /api/admin/solicitudes/:id

​Path Parameters

​Body

​Response

​PUT /api/admin/solicitudes/:id/estado

​Path Parameters

​Body

​Response

​POST /api/admin/solicitudes/:id/iniciar-firmado

​Path Parameters

​Body

​Response

​GET /api/admin/solicitudes/:id/firmantes

​Path Parameters

​Response

​DELETE /api/admin/solicitudes/:id/firmantes

​Path Parameters

​Body

​Response

​GET /api/admin/solicitudes/estados-count

​Query Parameters

​Response

​Tipo SolicitudAdmin

​Filtros disponibles (FiltrosSolicitudes)

GET /api/admin/solicitudes

Query Parameters

Response

GET /api/admin/solicitudes/:id

Path Parameters

Response

PUT /api/admin/solicitudes/:id

Path Parameters

Body

Response

PUT /api/admin/solicitudes/:id/estado

Path Parameters

Body

Response

POST /api/admin/solicitudes/:id/iniciar-firmado

Path Parameters

Body

Response

GET /api/admin/solicitudes/:id/firmantes

Path Parameters

Response

DELETE /api/admin/solicitudes/:id/firmantes

Path Parameters

Body

Response

GET /api/admin/solicitudes/estados-count

Query Parameters

Response

Tipo `SolicitudAdmin`

Filtros disponibles (`FiltrosSolicitudes`)