Consumo

Esta guia documenta el modulo de consumo de credito directo soportado por ms-credigestion, donde NoviSuite intermedia entre el dashboard o MBA3 y el sistema de credito directo ISISYSTEM para realizar consumos de credito en tiempo real.

Proposito

ms-credigestion se encarga de:

Recibir solicitudes HTTP REST/JSON desde el dashboard o MBA3
Traducirlas a llamadas SOAP/XML contra los servicios WCF de ISISYSTEM
Parsear las respuestas XML y devolverlas como JSON limpio
Persistir el estado de cada autorizacion/consumo en PostgreSQL local
Manejar el ciclo de vida completo: consulta → financiacion → autorizacion → OTP → confirmacion → reverso

Flujo general: Dashboard/MBA3 → NoviSuite (ms-credigestion) → SOAP/XML → ISISYSTEM → XML → JSON → Dashboard/MBA3

Datos Base del Servicio

Dato	Valor
Dominio produccion	`https://credigestion-api.novicompu.com`
Puerto HTTP	`3005`
Base de datos local	`credigestion_service_development`
Health check	`GET /up`
Integracion SOAP upstream	ISISYSTEM (Cartera + Central)

Autenticacion

Todos los endpoints de consumo usan solo Bearer JWT. No aceptan ServiceKey.

Esquema	Header
`Bearer JWT`	`Authorization: Bearer <token>`

Resumen de Endpoints

Accion	Endpoint	Metodo SOAP	Servicio ISISYSTEM	Persiste en DB
Consultar linea de credito	`POST /consumo/cupo`	ConsultarTarjeta	Cartera	No
Consultar financiacion	`POST /consumo/financiacion`	ConsultarAlternativaFinanciacion	Central	No
Generar autorizacion	`POST /consumo/autorizacion`	GrabarAutorizacion	Cartera	Si
Registrar OTP	`POST /consumo/otp`	— (local)	—	Si
Confirmar consumo	`POST /consumo/confirmar`	GrabarConsumo	Cartera	Si
Reversar autorizacion	`POST /consumo/reverso`	GrabarReversoAutorizacion	Cartera	Si
Reversar consumo	`POST /consumo/reverso-consumo`	GrabarReversoConsumo	Cartera	Si

Arquitectura SOAP

La traduccion REST → SOAP, los namespaces, constantes inyectadas y manejo de errores estan documentados en Modulo isisystem-soap.

Servicios WCF de ISISYSTEM

Servicio	URL	Operaciones
Cartera	`http://186.5.126.42:8092/Cartera/ServicioCartera.svc`	ConsultarTarjeta, GrabarAutorizacion, GrabarConsumo, GrabarReversoAutorizacion, GrabarReversoConsumo
Central	`http://186.5.126.42:8092/Central/ServicioCentral.svc`	ConsultarAlternativaFinanciacion

Constantes SOAP

Constante	Valor por defecto	Variable de entorno
Usuario	`USUARIOASI`	`ISISYSTEM_USUARIO`
Codigo Empresa	`000598`	`ISISYSTEM_CODIGO_EMPRESA`
Terminal	`NOVISUITE-01`	`ISISYSTEM_TERMINAL`
Timeout	`30` segundos	`ISISYSTEM_TIMEOUT`

Reglas Automaticas

cNumeroTarjeta ↔ identificacion: El campo SOAP debe ir poblado con la cedula del cliente. El servicio aplica el fallback cNumeroTarjeta = dto.numero_tarjeta ?? dto.identificacion.
OTP bypass: Si dto.otp viene vacio, se envia automaticamente cCodigoOtp = ISISYSTEM_OTP_BYPASS.
Mapeo de errores SOAP:
- nNumeroError === 2 (cliente sin tarjeta) → HTTP 404
- Cualquier nNumeroError con lError: true → HTTP 422 (error de negocio)
Nodos vacios xsi:nil="true": El parser detecta via isNilOrEmptyObject() y retorna null.

`POST /api/v1/credigestion/consumo/cupo`

Consulta la linea de credito / tarjeta de un cliente en ISISYSTEM.

Autenticacion: Bearer JWT

Body

{
  "codigo_empresa": "000598",
  "identificacion": "0916884245",
  "numero_tarjeta": "0916884245"
}

Campos

Campo	Obligatorio	Validacion
`codigo_empresa`	Si	string, max 20
`identificacion`	Si	string, max 50
`numero_tarjeta`	No	string, max 20

Respuesta Exitosa

{
  "success": true,
  "cliente": "MARCILLO ERICK",
  "numero_tarjeta": "0916884245",
  "codigo_cliente": 12345,
  "fecha_activacion": "2024-01-15",
  "fecha_ultima_compra": "2026-03-20",
  "fecha_ultimo_pago": "2026-04-01",
  "tipos_cupo": [{
    "cCodigoTipoCupo": "003",
    "cDescripcionTipoCupo": "CRÉDITO DIRECTO",
    "cFrecuenciaCupo": "M",
    "nCupoDisponible": 1500.00,
    "nCupoAsignado": 3000.00,
    "nCupoUtilizado": 1500.00
  }],
  "sub_cupos": [{
    "cCodigoTipoOperacion": "001",
    "cDescripcionTipoOperacion": "COMPRAS",
    "cFrecuenciaCupo": "M",
    "nCupoDisponibleOpe": 1500.00,
    "nPlazoMaximo": 36
  }]
}

Errores

HTTP	Caso
`400`	Body invalido
`401`	JWT invalido
`502`	ISISYSTEM rechazo
`504`	timeout

`POST /api/v1/credigestion/consumo/financiacion`

Consulta las alternativas de financiacion (plazos y cuotas) para un monto dado.

Autenticacion: Bearer JWT

Body

{
  "codigo_empresa": "000598",
  "numero_tarjeta": "0916884245",
  "codigo_producto": "004",
  "codigo_tipo_cupo": "003",
  "monto": "400",
  "items": [{"texto_articulo": "TV Samsung 55", "cantidad": 1, "precio": "400.00"}]
}

Campos

Campo	Obligatorio	Validacion
`codigo_empresa`	Si	string, max 20
`numero_tarjeta`	Si	string, max 20
`codigo_producto`	Si	string, max 3
`codigo_tipo_cupo`	Si	string, max 3
`codigo_tipo_operacion`	No	string, max 3
`monto`	Si	numerico como string
`items`	No	ArticuloConsumoDto[]

ArticuloConsumoDto

Campo	Obligatorio	Validacion
`codigo_articulo`	No	string
`texto_articulo`	Si	string
`cantidad`	Si	entero, min 1
`precio`	Si	numerico como string
`codigo_tipo_articulo`	No	string
`caracteristicas`	No	string (formato `025:AZUL-026:23x45`)

Respuesta Exitosa

{
  "success": true,
  "opciones": [
    {"plazo": 3, "cuota_mensual": 136.50, "cuota_garantia_extendida": 0, "interes_total": 9.50, "deuda_total": 409.50, "cuota_entrada_minima": 0},
    {"plazo": 6, "cuota_mensual": 70.25, "interes_total": 21.50, "deuda_total": 421.50},
    {"plazo": 12, "cuota_mensual": 37.80, "interes_total": 53.60, "deuda_total": 453.60}
  ]
}

Errores

HTTP	Caso
`400`	Body invalido
`401`	JWT invalido
`502`	ISISYSTEM rechazo
`504`	timeout

`POST /api/v1/credigestion/consumo/autorizacion`

Solicita la autorizacion de consumo en ISISYSTEM. Crea un registro local en PostgreSQL con el estado inicial.

Autenticacion: Bearer JWT

Body

{
  "codigo_empresa": "000598",
  "identificacion": "0916884245",
  "numero_tarjeta": "0916884245",
  "codigo_producto": "004",
  "plazo": 12,
  "monto": "400",
  "punto_venta": "POS-001",
  "codigo_tipo_cupo": "003"
}

Campos

Campo	Obligatorio	Validacion
`codigo_empresa`	Si	string, max 20
`identificacion`	Si	string, max 50
`numero_tarjeta`	Si	string, max 20
`codigo_producto`	Si	string, max 3
`plazo`	Si	entero, min 1
`monto`	Si	numerico como string
`punto_venta`	Si	string, max 50
`codigo_tipo_cupo`	No	string, max 3
`codigo_tipo_operacion`	No	string, max 3
`cuota_inicial`	No	numerico como string
`garantia_extendida`	No	boolean
`items`	No	ArticuloConsumoDto[]

Respuesta Exitosa

{
  "success": true,
  "autorizacion_id": "14022",
  "numero_operacion": 56789,
  "codigo_seguridad_enviado": true,
  "biometria_requerida": false,
  "imagen_qr": null,
  "estado": "AUTORIZADO",
  "id": "1"
}

Clave: Si codigo_seguridad_enviado=true, se requiere el paso OTP. Si es false (QA), se salta a confirmacion.

Errores

HTTP	Caso
`400`	Body invalido
`401`	JWT invalido
`502`	ISISYSTEM rechazo (`lError: true`)
`504`	timeout

`POST /api/v1/credigestion/consumo/otp`

Registra el codigo OTP ingresado por el cliente. Solo checkpoint local — no llama a ISISYSTEM. El OTP se valida en /confirmar.

Autenticacion: Bearer JWT

Body

{"autorizacion_id": "14022", "otp": "483926"}

Campos

Campo	Obligatorio	Validacion
`autorizacion_id`	Si	string, max 50
`otp`	Si	string, max 10

Respuesta Exitosa

{"success": true, "autorizacion_id": "14022", "estado": "OTP_RECIBIDO", "message": "OTP registrado. Proceda a confirmar el consumo."}

Validaciones de Estado

Solo se puede registrar OTP si el estado actual es AUTORIZADO
Si el estado no es valido, devuelve 400 Bad Request

Errores

HTTP	Caso
`400`	estado invalido
`401`	JWT invalido
`404`	autorizacion no encontrada

`POST /api/v1/credigestion/consumo/confirmar`

Confirma el consumo enviando la factura y OTP a ISISYSTEM (GrabarConsumo).

Autenticacion: Bearer JWT

Body

{
  "autorizacion_id": "14022",
  "numero_factura": "FAC-001-001-000012345",
  "monto_facturado": "400",
  "fecha_factura": "2026-04-15",
  "valor_iva": "48",
  "valor_comision": "0"
}

Campos

Campo	Obligatorio	Validacion
`autorizacion_id`	Si	string, max 50
`numero_factura`	Si	string, max 50
`monto_facturado`	Si	numerico como string
`fecha_factura`	Si	string, max 10 (yyyy-mm-dd)
`valor_iva`	No	numerico como string
`valor_comision`	No	numerico como string

Datos Automaticos del Registro Local

Al confirmar, el servicio toma del registro local (credigestion_consumos):

codigo_producto, codigo_tipo_cupo, codigo_tipo_operacion (de la autorizacion)
numero_tarjeta, identificacion (del cliente)
otp (registrado en /otp)
plazo, monto (del consumo original)

Respuesta Exitosa

{
  "success": true,
  "autorizacion_id": "14022",
  "estado": "CONSUMIDO",
  "numero_operacion": 56789,
  "valor_cuota": 37.80,
  "pago_minimo": 37.80,
  "saldo_actual": 1900.00,
  "fecha_max_pago": "2026-05-15",
  "tabla_amortizacion": [{"numero_cuota": 1, "fecha_vencimiento": "2026-05-15", "valor_capital": 33.33, "valor_interes": 4.47, "valor_cuota": 37.80}],
  "cupos_afectados": [{"cCodigoTipoCupo": "003", "nCupoDisponible": 1100.00, "nCupoUtilizado": 1900.00}]
}

Validaciones de Estado

Se acepta tanto AUTORIZADO como OTP_RECIBIDO
Si el OTP no fue registrado previamente, se envia "0" como cCodigoOtp (ISISYSTEM decide si lo requiere)

Errores

HTTP	Caso
`400`	body invalido o estado no es AUTORIZADO/OTP_RECIBIDO
`401`	JWT invalido
`404`	autorizacion no encontrada
`502`	ISISYSTEM rechazo (puede ser OTP invalido)
`504`	timeout

`POST /api/v1/credigestion/consumo/reverso`

Reversa una autorizacion antes de confirmar.

Autenticacion: Bearer JWT

Body

{"autorizacion_id": "14022", "numero_tarjeta": "0916884245", "identificacion": "0916884245"}

Campos

Campo	Obligatorio	Validacion
`autorizacion_id`	Si	string, max 50
`numero_tarjeta`	No	Se toma del registro si no se envia
`identificacion`	No	Se toma del registro si no se envia

Respuesta Exitosa

{"success": true, "estado": "REVERSADO", "message": "Autorizacion reversada exitosamente"}

Validaciones de Estado

No se puede reversar si el estado es CONSUMIDO (ya fue confirmado — usar /reverso-consumo)
No se puede reversar si ya esta en estado REVERSADO

Errores

HTTP	Caso
`400`	body invalido o estado no permite reverso
`401`	JWT invalido
`404`	autorizacion no encontrada
`502`	ISISYSTEM rechazo el reverso
`504`	timeout

`POST /api/v1/credigestion/consumo/reverso-consumo`

Reversa un consumo ya confirmado. Usa numero_factura como referencia.

Autenticacion: Bearer JWT

Body

{"autorizacion_id": "14022", "numero_tarjeta": "0916884245"}

Campos

Campo	Obligatorio	Validacion
`autorizacion_id`	Si	string, max 50
`numero_tarjeta`	No	Se toma del registro si no se envia

Datos Enviados a ISISYSTEM

El servicio construye la llamada SOAP GrabarReversoConsumo con:

cNumeroReferencia: numero de factura del registro local
cNumeroTarjeta: del DTO o del registro local
cTerminal: variable de entorno ISISYSTEM_TERMINAL
cUsuario: variable de entorno ISISYSTEM_USUARIO
lAjusteConciliacion: false

Respuesta Exitosa

{"success": true, "estado": "CONSUMO_REVERSADO", "numero_factura": "FAC-001-001-000012345", "message": "Reverso realizado correctamente"}

Validaciones de Estado

Solo se puede reversar si el estado es CONSUMIDO
Si no tiene numero_factura registrado, devuelve 400
No se puede reversar si esta en estado AUTORIZADO, OTP_RECIBIDO, REVERSADO o CONSUMO_REVERSADO

Errores

HTTP	Caso
`400`	body invalido, estado no es `CONSUMIDO`, o no hay factura registrada
`401`	JWT invalido
`404`	autorizacion no encontrada
`502`	ISISYSTEM rechazo el reverso del consumo
`504`	timeout

Maquina de Estados

stateDiagram-v2
    [*] --> AUTORIZADO : POST /autorizacion\n(GrabarAutorizacion SOAP)

    AUTORIZADO --> OTP_RECIBIDO : POST /otp\n(checkpoint local)
    AUTORIZADO --> CONSUMIDO : POST /confirmar\n(GrabarConsumo SOAP)
    AUTORIZADO --> REVERSADO : POST /reverso\n(GrabarReversoAutorizacion SOAP)

    OTP_RECIBIDO --> CONSUMIDO : POST /confirmar\n(GrabarConsumo SOAP)

    CONSUMIDO --> CONSUMO_REVERSADO : POST /reverso-consumo\n(GrabarReversoConsumo SOAP)

    REVERSADO --> [*]
    CONSUMO_REVERSADO --> [*]

Transiciones Validas

Estado Actual	Accion	Estado Resultante
`AUTORIZADO`	`POST /otp`	`OTP_RECIBIDO`
`AUTORIZADO`	`POST /confirmar`	`CONSUMIDO`
`AUTORIZADO`	`POST /reverso`	`REVERSADO`
`OTP_RECIBIDO`	`POST /confirmar`	`CONSUMIDO`
`CONSUMIDO`	`POST /reverso-consumo`	`CONSUMO_REVERSADO`

Estados Terminales

REVERSADO — autorizacion anulada antes de consumir
CONSUMO_REVERSADO — consumo confirmado y luego anulado

Modelo de Datos: `credigestion_consumos`

Columna	Tipo	Descripcion
`id`	bigint PK	ID interno
`autorizacion_id`	varchar(50)	Numero de autorizacion de ISISYSTEM
`numero_operacion`	varchar(20)	Numero de operacion de ISISYSTEM
`estado`	varchar(30)	Estado actual
`codigo_empresa`	varchar(20)	Codigo de empresa
`identificacion`	varchar(50)	Cedula del cliente
`numero_tarjeta`	varchar(20)	Numero de tarjeta
`codigo_producto`	varchar(10)	Codigo de producto
`codigo_tipo_cupo`	varchar(10)	Codigo tipo de cupo
`codigo_tipo_operacion`	varchar(10)	Codigo tipo de operacion
`monto`	decimal(18,2)	Monto autorizado
`plazo`	int	Plazo autorizado
`punto_venta`	varchar(50)	Punto de venta
`otp`	varchar(10)	OTP registrado
`numero_factura`	varchar(50)	Numero de factura
`monto_facturado`	decimal(18,2)	Monto facturado
`fecha_factura`	date	Fecha de factura
`isisystem_auth_response`	jsonb	Respuesta cruda de GrabarAutorizacion
`isisystem_consumo_response`	jsonb	Respuesta cruda de GrabarConsumo
`biometria_requerida`	boolean	Si requiere biometria
`imagen_qr`	text	QR en base64 (si aplica)
`source_system`	varchar(50)	Origen (default: `NOVISUITE`)
`created_at` / `updated_at`	timestamp	Fechas de creacion/modificacion

Formato Global de Errores

El filtro global del servicio responde errores con este envelope:

{
  "status": "error",
  "statusCode": 502,
  "message": "ISISYSTEM rechazo la operacion: GrabarConsumo",
  "errors": []
}

Casos Tipicos

Error de ISISYSTEM (lError: true)

{
  "status": "error",
  "statusCode": 502,
  "message": "ISISYSTEM rechazo la operacion: GrabarAutorizacion",
  "upstreamMessage": "Cupo insuficiente para el monto solicitado",
  "operation": "GrabarAutorizacion",
  "errorCode": 2
}

Timeout contra ISISYSTEM

{
  "status": "error",
  "statusCode": 504,
  "message": "ISISYSTEM no respondio a tiempo durante GrabarConsumo"
}

Estado Invalido

{
  "status": "error",
  "statusCode": 400,
  "message": "La autorizacion 14022 no esta en estado AUTORIZADO (actual: CONSUMIDO)"
}

Autorizacion No Encontrada

{
  "status": "error",
  "statusCode": 404,
  "message": "No se encontro autorizacion 14022"
}

Datos de Prueba QA

Credenciales de Consumo

Variable	Valor QA	Nota
`ISISYSTEM_USUARIO`	`POSNVC001`	Usuario funcional asignado a NoviSuite
`ISISYSTEM_CODIGO_EMPRESA`	`000598`	Empresa por defecto
`ISISYSTEM_OTP_BYPASS`	`999999`	OTP fijo mientras no este Biometria

Clientes de Prueba

Cedula	Cliente	Cupo Disponible	Estado
`0914665005`	GILBERT TACLE	$1700	Activa
`0926208323`	TINOCO SALTOS	$1685	Activa

Notas de Prueba

OTP bypass QA: 999999 (se inyecta automaticamente si el campo OTP esta vacio)
Mapeo cNumeroTarjeta: en QA el campo debe ir poblado con la cedula del cliente
Productos: el wizard usa "004" por defecto; verificar disponibilidad en QA

Ejemplos de Integracion con curl

Consultar Cupo

curl -X POST http://localhost:3005/api/v1/credigestion/consumo/cupo \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "codigo_empresa": "000598",
    "identificacion": "0916884245"
  }'

Solicitar Autorizacion

curl -X POST http://localhost:3005/api/v1/credigestion/consumo/autorizacion \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "codigo_empresa": "000598",
    "identificacion": "0916884245",
    "numero_tarjeta": "0916884245",
    "codigo_producto": "004",
    "plazo": 12,
    "monto": "400",
    "punto_venta": "POS-001",
    "codigo_tipo_cupo": "003"
  }'

Confirmar Consumo

curl -X POST http://localhost:3005/api/v1/credigestion/consumo/confirmar \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "autorizacion_id": "14022",
    "numero_factura": "FAC-001-001-000012345",
    "monto_facturado": "400",
    "fecha_factura": "2026-04-15"
  }'

Reversar Consumo Confirmado

curl -X POST http://localhost:3005/api/v1/credigestion/consumo/reverso-consumo \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "autorizacion_id": "14022"
  }'

Variables de Entorno

# -- ISISYSTEM SOAP (credito directo) --
ISISYSTEM_CARTERA_URL=http://186.5.126.42:8092/Cartera/ServicioCartera.svc
ISISYSTEM_CENTRAL_URL=http://186.5.126.42:8092/Central/ServicioCentral.svc
ISISYSTEM_USUARIO=POSNVC001
ISISYSTEM_CODIGO_EMPRESA=000598
ISISYSTEM_TERMINAL=NOVISUITE-01
ISISYSTEM_TIMEOUT=30
ISISYSTEM_OTP_BYPASS=999999

Notas Importantes

El modulo isisystem-soap es global — cualquier otro modulo del servicio puede inyectar IsisystemSoapService
Las constantes SOAP (cUsuario, cCodigoEmpresa, cTerminal) no se envian desde el request del cliente; el servicio las inyecta automaticamente
El OTP no tiene un endpoint SOAP propio — /otp es un checkpoint local que guarda el codigo, y la validacion real ocurre en /confirmar (GrabarConsumo con cCodigoOtp)
Si no se registra OTP antes de confirmar, se envia "0" como cCodigoOtp
Para reversar una autorizacion (antes de confirmar): usar /reverso → GrabarReversoAutorizacion
Para reversar un consumo (despues de confirmar): usar /reverso-consumo → GrabarReversoConsumo
El numero_factura es el cNumeroReferencia que se envia a GrabarReversoConsumo
Timeout SOAP configurable via ISISYSTEM_TIMEOUT (en segundos, default 30)

Consumo

Consumo

Proposito

Datos Base del Servicio

Autenticacion

Resumen de Endpoints

Arquitectura SOAP

Servicios WCF de ISISYSTEM

Constantes SOAP

Reglas Automaticas

POST /api/v1/credigestion/consumo/cupo

Body

Campos

Respuesta Exitosa

Errores

POST /api/v1/credigestion/consumo/financiacion

Body

Campos

ArticuloConsumoDto

Respuesta Exitosa

Errores

POST /api/v1/credigestion/consumo/autorizacion

Body

Campos

Respuesta Exitosa

Errores

POST /api/v1/credigestion/consumo/otp

Body

Campos

Respuesta Exitosa

Validaciones de Estado

Errores

POST /api/v1/credigestion/consumo/confirmar

Body

Campos

Datos Automaticos del Registro Local

Respuesta Exitosa

Validaciones de Estado

Errores

POST /api/v1/credigestion/consumo/reverso

Body

Campos

Respuesta Exitosa

Validaciones de Estado

Errores

POST /api/v1/credigestion/consumo/reverso-consumo

Body

Campos

Datos Enviados a ISISYSTEM

Respuesta Exitosa

Validaciones de Estado

Errores

Maquina de Estados

Transiciones Validas

Estados Terminales

Modelo de Datos: credigestion_consumos

Formato Global de Errores

Casos Tipicos

Error de ISISYSTEM (lError: true)

Timeout contra ISISYSTEM

Estado Invalido

Autorizacion No Encontrada

Datos de Prueba QA

Credenciales de Consumo

Clientes de Prueba

Notas de Prueba

Ejemplos de Integracion con curl

Consultar Cupo

Solicitar Autorizacion

Confirmar Consumo

Reversar Consumo Confirmado

Variables de Entorno

Notas Importantes

`POST /api/v1/credigestion/consumo/cupo`

`POST /api/v1/credigestion/consumo/financiacion`

`POST /api/v1/credigestion/consumo/autorizacion`

`POST /api/v1/credigestion/consumo/otp`

`POST /api/v1/credigestion/consumo/confirmar`

`POST /api/v1/credigestion/consumo/reverso`

`POST /api/v1/credigestion/consumo/reverso-consumo`

Modelo de Datos: `credigestion_consumos`