API Admin de Convenios Empresariales — Comfaca Créditos

Los convenios empresariales son los acuerdos formales entre COMFACA y las empresas empleadoras que permiten a sus trabajadores acceder a créditos de libranza. Cada convenio vincula una empresa (identificada por su NIT) con COMFACA, habilitando el descuento por nómina como mecanismo de pago. Los endpoints administrativos permiten gestionar el ciclo de vida completo de estos convenios: creación, consulta, actualización y cambio de estado.

Todos los endpoints de esta sección bajo /api/admin/convenios requieren una sesión activa con rol administrador. Las peticiones sin autenticación o con rol insuficiente recibirán un error 401 o 403.

GET /api/admin/convenios

Lista todos los convenios empresariales con soporte de paginación y filtros opcionales. Devuelve además un conteo_estados con el resumen de convenios por estado.

Query Parameters

page

number

default:"1"

Número de página a consultar. Entero positivo.

limit

number

default:"20"

Número máximo de convenios a devolver por página.

estado

string

Filtra convenios por estado. Valores posibles: Activo, Inactivo, Suspendido, Vencido.

nit

string

Busca convenios por el NIT exacto de la empresa.

busqueda

string

Búsqueda de texto libre sobre razon_social, nit u otros campos indexados.

Response

success

boolean

true cuando la consulta es exitosa.

data

object

Show Estructura de la respuesta paginada

empresas

array

Array de objetos EmpresaConvenio.

Show Campos de EmpresaConvenio

string

ID interno del convenio.

nit

string

NIT de la empresa empleadora.

Razón social de la empresa.

fecha_convenio

string

Fecha de suscripción del convenio.

fecha_vencimiento

string

Fecha de vencimiento del convenio.

estado

string

Estado actual: Activo, Inactivo, Suspendido o Vencido.

representante_documento

string

Número de documento del representante legal.

representante_nombre

string

Nombre del representante legal.

telefono

string

Teléfono de contacto de la empresa.

correo

string

Correo electrónico de contacto.

createdAt

string

Fecha de creación del registro en ISO 8601.

updatedAt

string

Fecha de última modificación en ISO 8601.

pagination

object

Show Campos de paginación

page

number

Página actual.

limit

number

Tamaño de página.

total

number

Total de registros encontrados.

total_pages

number

Total de páginas.

has_next

boolean

Indica si hay página siguiente.

has_prev

boolean

Indica si hay página anterior.

conteo_estados

object

Objeto con el conteo de convenios por estado. Ejemplo: { "Activo": 45, "Inactivo": 3, "Vencido": 2 }.

GET /api/admin/convenios/:id

Obtiene el detalle completo de un convenio empresarial por su ID interno.

Path Parameters

number

required

ID numérico del convenio. Se convierte a Number internamente.

Response

data

object

Objeto EmpresaConvenio con todos los campos del convenio incluyendo los campos extendidos de dirección, sector económico y notas internas.

curl -X GET "https://app.comfaca.com/api/admin/convenios/42" \
  -H "Cookie: nuxt-session=<token>"

{
  "success": true,
  "message": null,
  "data": {
    "id": "42",
    "nit": "900123456",
    "razon_social": "Constructora Andina S.A.S.",
    "fecha_convenio": "2023-03-01",
    "fecha_vencimiento": "2025-03-01",
    "estado": "Activo",
    "representante_documento": "79456321",
    "representante_nombre": "Jorge Enrique Mora",
    "telefono": "6012345678",
    "correo": "convenios@constructoraandina.com",
    "direccion": "Cra 15 # 93-47",
    "ciudad": "Bogotá",
    "departamento": "Cundinamarca",
    "sector_economico": "Construcción",
    "numero_empleados": 250,
    "tipo_empresa": "S.A.S.",
    "createdAt": "2023-03-01T09:00:00.000Z",
    "updatedAt": "2024-06-15T11:20:00.000Z"
  },
  "timestamp": "2024-11-15T16:00:00.000Z"
}

POST /api/admin/convenios/create

Crea un nuevo convenio empresarial en el sistema. El NIT y la razón social son obligatorios. Todos los demás campos son opcionales.

Body

nit

string

required

NIT de la empresa empleadora. Debe ser único en el sistema.

Razón social completa de la empresa tal como aparece en el registro mercantil.

representante_documento

string

required

Número de documento de identidad del representante legal de la empresa.

representante_nombre

string

required

Nombre completo del representante legal.

telefono

string

Teléfono de contacto de la empresa (máx. 20 caracteres).

correo

string

Correo electrónico de contacto. Debe ser una dirección válida (máx. 255 caracteres).

fecha_vencimiento

string

Fecha de vencimiento del convenio en formato ISO 8601 (YYYY-MM-DD).

estado

string

Estado inicial del convenio. Valores permitidos: Activo, Inactivo, Suspendido, Vencido. Por defecto se asigna según la lógica del servicio.

direccion

string

Dirección física de la sede principal de la empresa.

ciudad

string

Ciudad donde opera la empresa (máx. 100 caracteres).

departamento

string

Departamento donde opera la empresa (máx. 100 caracteres).

sector_economico

string

Sector económico al que pertenece la empresa (máx. 100 caracteres). Ejemplo: Construcción, Educación, Salud.

numero_empleados

number

Número total de empleados de la empresa. Entero no negativo.

tipo_empresa

string

Tipo de sociedad empresarial (máx. 100 caracteres). Ejemplo: S.A.S., S.A., Ltda., E.S.P..

descripcion

string

Descripción general del convenio y sus condiciones.

notas_internas

string

Notas de uso exclusivo del equipo administrativo. No son visibles para el solicitante.

Response

data

object

Show Campos del convenio creado

string

ID asignado al nuevo convenio.

nit

string

NIT de la empresa convenio.

Razón social registrada.

estado

string

Estado inicial del convenio.

curl -X POST "https://app.comfaca.com/api/admin/convenios/create" \
  -H "Content-Type: application/json" \
  -H "Cookie: nuxt-session=<token>" \
  -d '{
    "nit": "900456789",
    "razon_social": "Hospital Regional del Norte E.S.P.",
    "representante_documento": "12345678",
    "representante_nombre": "Ana María Rodríguez",
    "telefono": "6076543210",
    "correo": "convenios@hospitalregional.gov.co",
    "fecha_vencimiento": "2026-12-31",
    "estado": "Activo",
    "ciudad": "Montería",
    "departamento": "Córdoba",
    "sector_economico": "Salud",
    "numero_empleados": 850,
    "tipo_empresa": "E.S.P.",
    "descripcion": "Convenio de libranza para empleados del hospital.",
    "notas_internas": "Revisado y aprobado por comité el 01/11/2024."
  }'

{
  "success": true,
  "message": "Convenio creado exitosamente",
  "data": {
    "id": "58",
    "nit": "900456789",
    "razon_social": "Hospital Regional del Norte E.S.P.",
    "estado": "Activo"
  },
  "timestamp": "2024-11-15T16:15:00.000Z"
}

PUT /api/admin/convenios/:id

Actualiza los campos de un convenio empresarial existente. Todos los campos son opcionales; solo se modifican los que se incluyan en el body.

Path Parameters

number

required

ID numérico del convenio a actualizar.

Body

Acepta los mismos campos que POST /api/admin/convenios/create, todos como opcionales:

nit

string

NIT de la empresa.

Razón social.

representante_documento

string

Documento del representante legal.

representante_nombre

string

Nombre del representante legal.

telefono

string

Teléfono de contacto (máx. 20 caracteres).

correo

string

Correo electrónico de contacto (máx. 255 caracteres).

fecha_vencimiento

string

Fecha de vencimiento en ISO 8601.

estado

string

Nuevo estado: Activo, Inactivo, Suspendido o Vencido.

direccion

string

Dirección física actualizada.

ciudad

string

Ciudad (máx. 100 caracteres).

departamento

string

Departamento (máx. 100 caracteres).

sector_economico

string

Sector económico (máx. 100 caracteres).

numero_empleados

number

Número de empleados actualizado.

tipo_empresa

string

Tipo de empresa (máx. 100 caracteres).

descripcion

string

Descripción del convenio.

notas_internas

string

Notas internas del equipo administrativo.

Response

data

object

Show Campos del convenio actualizado

string

ID del convenio.

nit

string

NIT actualizado.

Razón social actualizada.

estado

string

Estado resultante tras la actualización.

Endpoints Públicos Relacionados

Además de los endpoints administrativos, existen dos endpoints públicos (sin autenticación) para la validación de convenios desde el flujo de solicitud de crédito:

GET /api/convenios/activo

Devuelve la lista de convenios con estado Activo. Utilizado en el formulario de solicitud para que el trabajador seleccione su empresa empleadora. No requiere autenticación.

GET /api/convenios/:nit/:cedula/validar

Valida si una cédula específica pertenece a una empresa con convenio activo para el NIT dado. Usado para verificar elegibilidad antes de iniciar la solicitud. No requiere autenticación.

Tipo `EmpresaConvenio`

Estructura TypeScript del objeto convenio:

interface EmpresaConvenio {
  id: string
  nit: string
  razon_social: string
  fecha_convenio: string
  fecha_vencimiento: string
  estado: string               // "Activo" | "Inactivo" | "Suspendido" | "Vencido"
  representante_documento: string
  representante_nombre: string
  telefono: string
  correo: string
  createdAt: string
  updatedAt: string
}

interface ConveniosResponse {
  empresas: EmpresaConvenio[]
  pagination: PaginationInfo
  conteo_estados: Record<string, number>
}

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

API Admin de Convenios Empresariales — Comfaca Créditos

GET /api/admin/convenios

Query Parameters

Response

GET /api/admin/convenios/:id

Path Parameters

Response

POST /api/admin/convenios/create

Body

Response

PUT /api/admin/convenios/:id

Path Parameters

Body

Response

Endpoints Públicos Relacionados

GET /api/convenios/activo

GET /api/convenios/:nit/:cedula/validar

Tipo `EmpresaConvenio`

Build docs developers (and LLMs) love

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

Documentation Index

​GET /api/admin/convenios

​Query Parameters

​Response

​GET /api/admin/convenios/:id

​Path Parameters

​Response

​POST /api/admin/convenios/create

​Body

​Response

​PUT /api/admin/convenios/:id

​Path Parameters

​Body

​Response

​Endpoints Públicos Relacionados

GET /api/convenios/activo

GET /api/convenios/:nit/:cedula/validar

​Tipo EmpresaConvenio

Build docs developers (and LLMs) love

GET /api/admin/convenios

Query Parameters

Response

GET /api/admin/convenios/:id

Path Parameters

Response

POST /api/admin/convenios/create

Body

Response

PUT /api/admin/convenios/:id

Path Parameters

Body

Response

Endpoints Públicos Relacionados

Tipo `EmpresaConvenio`