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

estado

string

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

limit

number

default:"20"

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

skip

number

default:"0"

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

Response

success

boolean

true cuando la operación se ejecuta correctamente.

message

string

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

data

object

Show Estructura del objeto data

collection

array

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

pagination

object

Show Campos de paginación

page

number

Número de página actual.

page_size

number

Tamaño de la página.

total

number

Total de solicitudes que coinciden con los filtros.

total_pages

number

Total de páginas disponibles.

has_next

boolean

Indica si hay una página siguiente.

has_prev

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

data

object

Show Estructura de SolicitudAdmin

string

Identificador interno de la solicitud.

numero_solicitud

string

Número de solicitud legible.

estado

string

Estado actual de la solicitud.

valor_solicitud

number

Monto solicitado en pesos colombianos.

plazo_meses

number

Plazo del crédito en meses.

tipo_credito

string

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

detalle_modalidad

string

Descripción de la modalidad crediticia.

owner_username

string

Username del solicitante propietario de la solicitud.

created_at

string

Fecha de creación en ISO 8601.

updated_at

string

Fecha de última actualización en ISO 8601.

solicitante

object

Show Datos del solicitante

nombres

string

Nombres del solicitante.

apellidos

string

Apellidos del solicitante.

string

Correo electrónico.

numero_documento

string

Número de documento de identidad.

tipo_documento

string

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

telefono_movil

string

Teléfono de contacto.

timeline

array

Show Entradas del timeline

estado

string

Estado registrado en este evento.

fecha

string

Fecha del evento en ISO 8601.

detalle

string

Descripción detallada del cambio.

descripcion

string

Nota adicional del administrador.

documentos

array

Show Documentos adjuntos

string

ID del documento.

nombre_original

string

Nombre original del archivo subido.

saved_filename

string

Nombre del archivo en almacenamiento.

tipo_mime

string

Tipo MIME del archivo.

tamano_bytes

number

Tamaño en bytes.

created_at

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

estado

string

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

valor_solicitud

number

Monto solicitado. Debe ser un número positivo.

plazo_meses

number

Plazo del crédito en meses. Entero positivo.

tasa_interes

number

Tasa de interés aplicable. Valor no negativo.

producto_tipo

string

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

ha_tenido_credito

boolean

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

detalle_modalidad

string

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

tipo_credito

string

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

moneda

string

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

cuota_mensual

number

Valor de la cuota mensual calculada. No negativo.

fecha_radicado

string

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

Response

data

object

Show Campos retornados

numero_solicitud

string

Número de solicitud actualizada.

estado

string

Estado actual tras la actualización.

valor_solicitud

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

estado

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.”

descripcion

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

data

object

Show Campos retornados

numero_solicitud

string

Número de solicitud cuyo estado fue modificado.

estado

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

firmantes

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.

orden

number

required

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

tipo

string

Tipo de firmante. Valor por defecto "1".

nombre_completo

string

required

Nombre completo del firmante.

numero_documento

string

required

Número de documento de identidad del firmante.

string

required

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

rol

string

required

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

telefono

string

Teléfono de contacto del firmante.

codigo_pais

string

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

Response

data

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

data

array

Array de objetos firmante ordenados por orden.

Show Estructura de cada firmante

string

ID del firmante (serializado desde BigInt).

solicitud_id

string

ID de la solicitud asociada.

orden

number

Orden de firma.

tipo

string

Tipo de firmante.

nombre_completo

string

Nombre completo del firmante.

numero_documento

string

Número de documento.

string

Correo electrónico del firmante.

rol

string

Rol en el proceso de firma.

created_at

string

Fecha de creación en ISO 8601.

updated_at

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

firmanteId

string

required

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

Response

data

null

null cuando la eliminación es exitosa.

message

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

data

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`)

Build docs developers (and LLMs) love

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

Documentation Index

​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)

Build docs developers (and LLMs) love

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`)