Integracion ISISYSTEM

Guia de Integracion para ISISYSTEM

Esta guia esta dirigida al equipo tecnico de ISISYSTEM. Explica como enviar datos de clientes a NoviSuite (ms-credigestion) para su replicacion hacia el ERP MBA3.

Informacion Base

Concepto	Valor
Dominio produccion	https://credigestion-api.novicompu.com
Puerto interno	3005
Protocolo	REST/JSON sobre HTTPS
Health check	GET /up

Autenticacion: ServiceKey

ISISYSTEM se autentica usando un ServiceKey compartido. No se usa JWT.

Header Requerido

Authorization: ServiceKey <SU_CLAVE_SECRETA>
Content-Type: application/json

El ServiceKey es una clave secreta que el equipo de NoviSuite le proporcionara a ISISYSTEM de forma segura. Nunca comparta esta clave en canales publicos.

Como Funciona

1. NoviSuite configura la variable ISISYSTEM_SERVICE_KEY en el servicio
2. ISISYSTEM envia el header Authorization: ServiceKey <clave> en cada request
3. El ServiceKeyGuard de NoviSuite valida la clave:
   • Si coincide → el request continua y se marca como origen ISISYSTEM
   • Si no coincide → retorna 401 Unauthorized
4. Si ISISYSTEM envia Bearer en lugar de ServiceKey → es rechazado explicitamente con 401

Endpoint Oficial para Crear Clientes

Este es el unico endpoint que ISISYSTEM debe usar para crear clientes en NoviSuite.

POST https://credigestion-api.novicompu.com/api/v1/credigestion/clients/from-isisystem

Autenticacion

Tipo	Soportado
ServiceKey	Si (obligatorio)
Bearer JWT	No (rechazado con 401)

Payload Requerido

{
  "codigo_empresa": "EMP01",
  "nombre_cliente": "Juan Perez",
  "identificacion": "1712345678",
  "email": "[email protected]",
  "telefono_1": "0991234567",
  "telefono_2": "022345678",
  "direccion_1": "Av. Principal 123",
  "extra_fields": {
    "texto_4": "Creado desde ISISYSTEM"
  }
}

Campos Obligatorios

Campo	Tipo	Max. longitud	Descripcion
codigo_empresa	string	20	Codigo de la empresa en MBA3
nombre_cliente	string	255	Nombre completo del cliente
identificacion	string	50	Cedula, RUC o identificacion fiscal

Campos Opcionales

Campo	Tipo	Descripcion
email	string	Correo electronico
telefono_1	string	Telefono principal
telefono_2	string	Telefono secundario
direccion_1	text	Direccion principal
extra_fields	object	Campos adicionales de MBA3 (ver abajo)

Campos Extendidos (extra_fields)

Se pueden enviar campos adicionales de MBA3 mediante extra_fields. Estos se guardan como JSONB y se mapean directamente al payload de MBA3.

Familias Soportadas

Familia	Campos	Notas
lista_datos_n	lista_datos_1 a lista_datos_10	Valores de lista
alfanumerico_n	alfanumerico_1 a alfanumerico_10	Texto alfanumerico
valor_n	valor_1 a valor_10	Valores numericos
fecha_n	fecha_1 a fecha_10	Formato aaaa-mm-dd
booleano_n	booleano_1 a booleano_10	1=True / 0=False
texto_n	texto_1 a texto_10	Texto libre (hasta 32000 chars)

Ejemplo con extra_fields

{
  "codigo_empresa": "EMP01",
  "nombre_cliente": "Juan Perez",
  "identificacion": "1712345678",
  "extra_fields": {
    "fecha_6": "2026-04-14",
    "booleano_8": "1",
    "texto_4": "Creado desde ISISYSTEM",
    "valor_8": "1250.55"
  }
}

Flujo Completo de Creacion

Cuando ISISYSTEM envia una solicitud al endpoint oficial, NoviSuite ejecuta estos pasos automaticamente:

ISISYSTEM ──ServiceKey──> NoviSuite (ms-credigestion)
                               │
                               │ 1. Valida ServiceKey
                               │ 2. Pre-check en paralelo contra MBA3 y registro local
                               │ 3. Decide:
                               │    - Si existe en MBA3 → 409 EXISTS_IN_MBA3
                               │    - Si existe solo local → 409 EXISTS_LOCAL
                               │    - Si no existe → crea en PostgreSQL local
                               │ 4. Retorna respuesta
                               │
                               ▼
                          PostgreSQL Local
                          (mba3_synced = false)
                               │
                               │ Sync manual posterior
                               ▼
                          MBA3 (ERP principal)

Paso 1: ISISYSTEM envia la solicitud

curl -X POST 'https://credigestion-api.novicompu.com/api/v1/credigestion/clients/from-isisystem' \
  -H 'Authorization: ServiceKey SU_CLAVE_SECRETA_AQUI' \
  -H 'Content-Type: application/json' \
  -d '{
    "codigo_empresa": "EMP01",
    "nombre_cliente": "Juan Perez",
    "identificacion": "1712345678",
    "email": "[email protected]",
    "telefono_1": "0991234567"
  }'

Paso 2: NoviSuite valida la autenticacion

• Verifica que el header Authorization empiece con ServiceKey
• Extrae la clave y compara con ISISYSTEM_SERVICE_KEY
• Si es valida → continua; si no → 401 Unauthorized

Paso 3: Pre-check contra MBA3

NoviSuite consulta MBA3 para verificar si el cliente ya existe:

• Si existe en MBA3 → Retorna 409 EXISTS_IN_MBA3 con los datos del cliente existente
• Si existe solo localmente → Retorna 409 EXISTS_LOCAL
• Si no existe en ningun lado → Continua con la creacion

Paso 4: Creacion en PostgreSQL local

Si el cliente no existe:

1. Crea el registro en credigestion_clients con:
   • mba3_synced = false (aun no sincronizado con MBA3)
   • source_system = "ISISYSTEM" (origen del request)
2. Devuelve 201 Created con el cliente creado

Paso 5: Sincronizacion con MBA3 (manual)

La sincronizacion hacia MBA3 no es automatica. Un administrador de NoviSuite la realiza manualmente despues usando:

POST https://credigestion-api.novicompu.com/api/v1/credigestion/clients/:codigo/sync-mba3

Respuestas Posibles

201 Created — Cliente creado exitosamente

{
  "success": true,
  "reason": "CREATED",
  "operation": "create",
  "client": {
    "id": "42",
    "codigo_cliente": null,
    "codigo_empresa": "EMP01",
    "nombre_cliente": "Juan Perez",
    "identificacion": "1712345678",
    "email": "[email protected]",
    "telefono_1": "0991234567",
    "mba3_synced": false,
    "source_system": "ISISYSTEM",
    "created_at": "2026-05-06T15:00:00.000Z",
    "updated_at": "2026-05-06T15:00:00.000Z"
  },
  "mba3_pre_check": {
    "checked_at": "2026-05-06T15:00:00.000Z",
    "found": false
  }
}

Nota: codigo_cliente sera null inicialmente porque MBA3 aun no ha asignado uno. Se poblara despues de la sincronizacion manual.

409 EXISTS_IN_MBA3 — Cliente ya existe en MBA3

{
  "success": false,
  "reason": "EXISTS_IN_MBA3",
  "mba3_client": {
    "codigo_cliente": "CLIE1001",
    "codigo_empresa": "EMP01",
    "nombre_cliente": "Juan Perez",
    "identificacion": "1712345678",
    "email": "[email protected]",
    "telefono_1": "0991234567"
  },
  "local_record": { ... },
  "mba3_pre_check": { "checked_at": "2026-05-06T15:00:00.000Z", "found": true },
  "message": "El cliente ya existe en MBA3",
  "hint": "Use el codigo_cliente devuelto para operar sobre el cliente existente"
}

Que hacer: Use el codigo_cliente retornado (CLIE1001 en el ejemplo) para operaciones futuras. No intente crear un duplicado.

409 EXISTS_LOCAL — Cliente ya existe localmente en NoviSuite

{
  "success": false,
  "reason": "EXISTS_LOCAL",
  "mba3_client": null,
  "local_record": {
    "id": "42",
    "codigo_cliente": null,
    "codigo_empresa": "EMP01",
    "identificacion": "1712345678",
    "mba3_synced": false,
    "source_system": "ISISYSTEM"
  },
  "mba3_pre_check": { "checked_at": "2026-05-06T15:00:00.000Z", "found": false },
  "message": "El cliente ya existe localmente en NoviSuite pero aun no fue sincronizado a MBA3",
  "hint": "Espere a la sincronizacion manual o consulte el registro local"
}

Que hacer: El cliente fue creado previamente pero aun no se sincronizo con MBA3. Espere a que el administrador de NoviSuite realice la sincronizacion.

400 Bad Request — Body invalido

{
  "status": "error",
  "statusCode": 400,
  "message": "Error de validacion",
  "errors": ["codigo_empresa es obligatorio", "identificacion es obligatorio"]
}

401 Unauthorized — Autenticacion fallida

{
  "status": "error",
  "statusCode": 401,
  "message": "ServiceKey invalida o faltante"
}

502 Bad Gateway — MBA3 rechazo la consulta

{
  "status": "error",
  "statusCode": 502,
  "message": {
    "message": "MBA3 rechaz la consulta del cliente",
    "upstreamMessage": "Detalle del error de MBA3..."
  }
}

504 Gateway Timeout — MBA3 no respondio

{
  "status": "error",
  "statusCode": 504,
  "message": "MBA3 no respondio a tiempo durante la consulta del cliente"
}

Resumen de Errores

HTTP	Caso	Accion recomendada
400	Body invalido o faltan campos obligatorios	Revisar payload y reenviar
401	Falta Authorization, ServiceKey invalida, o se envio Bearer	Verificar credenciales
409	Cliente ya existe (EXISTS_IN_MBA3 o EXISTS_LOCAL)	Usar codigo_cliente existente
502	MBA3 / Consulta Externa rechazo el pre-check	Contactar a NoviSuite
504	MBA3 / Consulta Externa no respondio antes del timeout	Reintentar despues de unos segundos

Regla de Duplicidad

NoviSuite valida que no exista un registro con la misma combinacion: identificacion + codigo_empresa. Si ya existe → retorna 409 Conflict.

Esto permite a ISISYSTEM reintentar de forma segura (idempotencia) sin crear duplicados.

Datos de Prueba QA

Credenciales

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

Checklist de Requisitos que NoviSuite Necesita de ISISYSTEM

Conectividad de Red

Item	Detalle	Estado
Whitelist de IP saliente	IP publica desde la que ms-credigestion llamara al WCF	Pendiente
Confirmacion de hosts y puertos	URL completa de Cartera y Central por ambiente	QA confirmado
TLS / certificados	Si el endpoint productivo va por HTTPS	Pendiente
VPN / tunel	Si se requiere VPN site-to-site o tunel adicional	Pendiente

Credenciales y Constantes

Variable	Valor QA	Estado
ISISYSTEM_USUARIO	POSNVC001	Entregado
ISISYSTEM_CODIGO_EMPRESA	000598	Confirmado
ISISYSTEM_TERMINAL	NOVISUITE-01	Pendiente confirmacion
ISISYSTEM_OTP_BYPASS	999999	Workaround vigente
ISISYSTEM_CARTERA_URL	http://186.5.126.42:8092/Cartera/ServicioCartera.svc	QA
ISISYSTEM_CENTRAL_URL	http://186.5.126.42:8092/Central/ServicioCentral.svc	QA

Documentacion Tecnica del WCF

• WSDL de cada servicio (ServicioCartera.svc?wsdl y ServicioCentral.svc?wsdl)
• Ejemplos reales de envelope SOAP request + response
• Politica de idempotencia: como identifica ISISYSTEM un reintento
• Politica de reverso: ventana de tiempo permitida y autorizaciones requeridas
• Catalogo de codigos de error de negocio (nNumeroError) con descripcion

Operacion y Soporte

• Punto de contacto tecnico de ISISYSTEM para incidentes (correo + Slack/Teams + horario)
• Canal para reportar errores upstream (ticketing, mesa de ayuda)
• Politica de cambios: como notifican a NoviSuite cuando cambia un endpoint, codigo de error o namespace XML
• Logs upstream: si se pueden solicitar trazas por numeroOperacion cuando hay discrepancia

Modulo de Consumo (Credito Directo)

Ademas de la gestion de clientes, NoviSuite permite realizar consumos de credito directo contra ISISYSTEM. Este modulo es usado por el punto de venta MBA3 y el dashboard de NoviSuite.

Resumen de Endpoints

Accion	Endpoint	Autenticacion
Consultar linea de credito	POST /api/v1/credigestion/consumo/cupo	Bearer JWT
Consultar opciones de financiacion	POST /api/v1/credigestion/consumo/financiacion	Bearer JWT
Generar autorizacion	POST /api/v1/credigestion/consumo/autorizacion	Bearer JWT
Registrar OTP	POST /api/v1/credigestion/consumo/otp	Bearer JWT
Confirmar consumo	POST /api/v1/credigestion/consumo/confirmar	Bearer JWT
Reversar autorizacion	POST /api/v1/credigestion/consumo/reverso	Bearer JWT
Reversar consumo confirmado	POST /api/v1/credigestion/consumo/reverso-consumo	Bearer JWT

Nota: El modulo de consumo usa Bearer JWT, no ServiceKey. Solo el modulo de clientes acepta ServiceKey para ISISYSTEM.

Arquitectura

NoviSuite traduce las llamadas REST/JSON del dashboard a SOAP/XML contra los servicios WCF de ISISYSTEM:

Dashboard/MBA3 ──REST/JSON──> NoviSuite (ms-credigestion) ──SOAP/XML──> ISISYSTEM WCF

ISISYSTEM no necesita implementar nada adicional para el modulo de consumo — NoviSuite consume los servicios WCF que ISISYSTEM ya expone.

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

Modulo de Pagos (Proximamente)

El modulo de pagos (consulta de deuda, aplicacion de pago y reverso de pago) esta en estado de especificacion y aun no esta implementado. Se documentara cuando el modulo exista.

Contacto

Para dudas tecnicas o soporte, contactar al equipo de NoviSuite.