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

number

default:"1"

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

number

default:"20"

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

string

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

string

Busca convenios por el NIT exacto de la empresa.

string

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

Response

boolean

true cuando la consulta es exitosa.

object

Show Estructura de la respuesta paginada

array

Array de objetos EmpresaConvenio.

Show Campos de EmpresaConvenio

string

ID interno del convenio.

string

NIT de la empresa empleadora.

Razón social de la empresa.

string

Fecha de suscripción del convenio.

string

Fecha de vencimiento del convenio.

string

Estado actual: Activo, Inactivo, Suspendido o Vencido.

string

Número de documento del representante legal.

string

Nombre del representante legal.

string

Teléfono de contacto de la empresa.

string

Correo electrónico de contacto.

string

Fecha de creación del registro en ISO 8601.

string

Fecha de última modificación en ISO 8601.

object

Show Campos de paginación

number

Página actual.

number

Tamaño de página.

number

Total de registros encontrados.

number

Total de páginas.

boolean

Indica si hay página siguiente.

boolean

Indica si hay página anterior.

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

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

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.

string

required

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

string

required

Nombre completo del representante legal.

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

number

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

string

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

string

Descripción general del convenio y sus condiciones.

string

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

Response

object

Show Campos del convenio creado

string

ID asignado al nuevo convenio.

string

NIT de la empresa convenio.

Razón social registrada.

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:

string

NIT de la empresa.

Razón social.

string

Documento del representante legal.

string

Nombre del representante legal.

string

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

string

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

string

Fecha de vencimiento en ISO 8601.

string

Nuevo estado: Activo, Inactivo, Suspendido o Vencido.

string

Dirección física actualizada.

string

Ciudad (máx. 100 caracteres).

string

Departamento (máx. 100 caracteres).

string

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

number

Número de empleados actualizado.

string

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

string

Descripción del convenio.

string

Notas internas del equipo administrativo.

Response

object

Show Campos del convenio actualizado

string

ID del convenio.

string

NIT actualizado.

Razón social actualizada.

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`

​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

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`