Skip to content

Clientes

Esta guia documenta el contrato de integracion del modulo de clientes soportado por ms-credigestion, un microservicio NestJS que intermedia entre sistemas externos como ISISYSTEM, el dashboard de NoviSuite y el ERP MBA3.

ms-credigestion se encarga de:

  • Recibir solicitudes HTTP para crear o actualizar clientes
  • Validar autenticacion y formato basico del request
  • Persistir el cliente en PostgreSQL local primero (mba3_synced = false)
  • La sincronizacion hacia MBA3 se realiza manualmente despues
  • Exponer endpoints de consulta para uso interno del dashboard

Flujo general: ISISYSTEM → NoviSuite (ms-credigestion) → PostgreSQL local → (sync manual) → MBA3

DatoValor
Dominio produccionhttps://credigestion-api.novicompu.com
Puerto HTTP3005
Base de datos localcredigestion_service_development
Health checkGET /up
Integracion upstreamPOST /mba3api/clientes en MBA3

El servicio maneja dos esquemas distintos segun el endpoint:

EsquemaHeaderUso
ServiceKeyAuthorization: ServiceKey <ISISYSTEM_SERVICE_KEY>Sistemas externos como ISISYSTEM
Bearer JWTAuthorization: Bearer <token>Dashboard interno de NoviSuite

El endpoint POST /api/v1/credigestion/clients/from-isisystem esta protegido por un ServiceKeyGuard dedicado que solo acepta ServiceKey y rechaza Bearer explicitamente.

EndpointServiceKeyBearer JWT
POST /api/v1/credigestion/clients/existsSiSi
POST /api/v1/credigestion/clientsSiSi
POST /api/v1/credigestion/clients/from-isisystemSi (ServiceKey-only)No
PUT /api/v1/credigestion/clients/:codigoSiSi
GET /api/v1/credigestion/clientsNoSi
GET /api/v1/credigestion/clients/:codigoNoSi

Cuando el request entra con ServiceKey, el guard marca:

{ "source": "isisystem", "system": "ISISYSTEM" }

El servicio guarda source_system = "ISISYSTEM". Con JWT del dashboard, el valor sera dashboard.

AccionEndpointAutenticacion
Verificar existenciaPOST /api/v1/credigestion/clients/existsServiceKey o JWT
Crear clientePOST /api/v1/credigestion/clientsServiceKey o JWT
Crear desde ISISYSTEMPOST /api/v1/credigestion/clients/from-isisystemServiceKey solo
Actualizar clientePUT /api/v1/credigestion/clients/:codigoServiceKey o JWT
Listar clientesGET /api/v1/credigestion/clientsJWT solo
Obtener clienteGET /api/v1/credigestion/clients/:codigoJWT solo
Sincronizar con MBA3POST /api/v1/credigestion/clients/:codigo/sync-mba3JWT solo

Verifica si el cliente existe en la fuente de verdad MBA3 usando Consulta Externa.

Autenticacion: ServiceKey o Bearer JWT

{
"codigo_empresa": "EMP01",
"identificacion": "0917582967"
}
CampoTipoRegla
codigo_empresastringObligatorio, maximo 20
identificacionstringObligatorio, maximo 50
{
"success": true,
"exists": true,
"source": "MBA3_CONSULTA_EXTERNA",
"criteria": { "codigo_empresa": "EMP01", "identificacion": "0917582967" },
"client": {
"codigo_cliente": "CLIE1001",
"codigo_empresa": "EMP01",
"nombre_cliente": "Luis Fabricio Cardenas",
"identificacion": "0917582967",
"email": "[email protected]",
"telefono_1": "0939923127",
"telefono_2": null,
"direccion_1": "09 y ejemplo",
"inactivo": false
},
"local_record": {
"id": "15",
"codigo_cliente": "CLIE1001",
"codigo_empresa": "EMP01",
"identificacion": "0917582967",
"mba3_synced": true,
"source_system": "ISISYSTEM",
"created_at": "2026-04-14T00:00:00.000Z",
"updated_at": "2026-04-14T00:00:00.000Z"
}
}
{
"success": true,
"exists": false,
"source": "MBA3_CONSULTA_EXTERNA",
"criteria": { "codigo_empresa": "EMP01", "identificacion": "9999999999" },
"client": null,
"local_record": null
}
HTTPCaso
400Body invalido o faltan campos obligatorios
401Falta autorizacion, ServiceKey invalida, JWT invalido o expirado
502MBA3 o Consulta Externa rechazo la consulta
504Consulta Externa no respondio antes del timeout

Crea un cliente en PostgreSQL local. El registro se guarda con mba3_synced = false y la sincronizacion hacia MBA3 se realiza manualmente despues.

Autenticacion: ServiceKey o Bearer JWT

{
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"codigo_cliente": "CLI001",
"email": "[email protected]",
"telefono_1": "0991234567",
"telefono_2": "022345678",
"direccion_1": "Av. Principal 123",
"codigo_vendedor": "VEN01",
"termino_pagos": "30",
"limite_credito_1": "5000.00",
"limite_credito_2": "0.00",
"codigo_sucursal": "PRI",
"localizacion": "L",
"lista_precios": "1",
"nivel_riesgo": "1",
"extra_fields": {
"lista_datos_1": "VIP",
"alfanumerico_1": "SEGMENTO-A"
}
}
CampoTipoRegla
codigo_empresastringObligatorio, maximo 20
nombre_clientestringObligatorio, maximo 255
identificacionstringObligatorio, maximo 50
CampoTipoRegla
codigo_clientestringMaximo 80
emailstringEmail valido, maximo 255
telefono_1stringMaximo 50
telefono_2stringMaximo 50
direccion_1text
codigo_vendedorstringMaximo 100
termino_pagosstringMaximo 100
limite_credito_1stringNumerico como string
limite_credito_2stringNumerico como string
codigo_sucursalstring
localizacionstring
lista_preciosstring
nivel_riesgostring
extra_fieldsobjectObjeto clave-valor
{
"success": true,
"operation": "create",
"client": {
"id": "1",
"codigo_cliente": "CLI001",
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0991234567",
"telefono_2": "022345678",
"direccion_1": "Av. Principal 123",
"codigo_vendedor": "VEN01",
"termino_pagos": "30",
"limite_credito_1": 5000,
"limite_credito_2": 0,
"mba3_synced": false,
"source_system": "ISISYSTEM",
"created_at": "2026-04-14T00:00:00.000Z",
"updated_at": "2026-04-14T00:00:00.000Z"
}
}
HTTPCaso
400Body invalido o faltan campos obligatorios
401Falta autorizacion, ServiceKey invalida, JWT invalido o expirado
409Ya existe localmente el cliente con identificacion + codigo_empresa

POST /api/v1/credigestion/clients/from-isisystem

Section titled “POST /api/v1/credigestion/clients/from-isisystem”

Entry point oficial de ISISYSTEM para crear clientes en NoviSuite. Realiza un pre-check obligatorio contra MBA3 antes de persistir y devuelve respuestas enriquecidas en caso de conflicto.

Autenticacion: ServiceKey (ServiceKey-only, NO acepta Bearer)

  1. ServiceKeyGuard valida Authorization: ServiceKey <ISISYSTEM_SERVICE_KEY> (rechaza Bearer con 401)
  2. Pre-check en paralelo: consulta MBA3 y registro local
  3. Decision:
    • Si MBA3 lo tiene → 409 EXISTS_IN_MBA3 con mba3_client y local_record
    • Si solo existe local → 409 EXISTS_LOCAL con local_record
    • Si no existe en ninguno → crea en PostgreSQL local con source_system = 'ISISYSTEM' y mba3_synced = false
  4. Devuelve 201 CREATED con mba3_pre_check adjunto
{
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0991234567",
"telefono_2": "022345678",
"direccion_1": "Av. Principal 123",
"extra_fields": {
"alfanumerico_1": "SEGMENTO-A"
}
}
CampoTipoRegla
codigo_empresastringObligatorio, maximo 20
nombre_clientestringObligatorio, maximo 255
identificacionstringObligatorio, maximo 50
{
"success": true,
"reason": "CREATED",
"operation": "create",
"client": {
"id": "42",
"codigo_cliente": null,
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0991234567",
"mba3_synced": false,
"source_system": "ISISYSTEM",
"created_at": "2026-04-29T15:00:00.000Z",
"updated_at": "2026-04-29T15:00:00.000Z"
},
"mba3_pre_check": {
"checked_at": "2026-04-29T15:00:00.000Z",
"found": false
}
}
{
"success": false,
"reason": "EXISTS_IN_MBA3",
"mba3_client": {
"codigo_cliente": "CLIE1001",
"codigo_empresa": "EMP01",
"nombre_cliente": "Luis Fabricio Cardenas",
"identificacion": "0917582967",
"email": "[email protected]",
"telefono_1": "0939923127",
"telefono_2": null,
"direccion_1": "09 y ejemplo",
"inactivo": false
},
"local_record": {
"id": "15",
"codigo_cliente": "CLIE1001",
"codigo_empresa": "EMP01",
"identificacion": "0917582967",
"mba3_synced": true,
"source_system": "ISISYSTEM",
"created_at": "2026-04-14T00:00:00.000Z",
"updated_at": "2026-04-14T00:00:00.000Z"
},
"mba3_pre_check": { "checked_at": "2026-04-29T15:00:00.000Z", "found": true },
"message": "El cliente ya existe en MBA3",
"hint": "Use el codigo_cliente devuelto para operar sobre el cliente existente"
}
{
"success": false,
"reason": "EXISTS_LOCAL",
"mba3_client": null,
"local_record": {
"id": "42",
"codigo_cliente": null,
"codigo_empresa": "EMP01",
"identificacion": "1723955199",
"mba3_synced": false,
"source_system": "ISISYSTEM",
"created_at": "2026-04-20T00:00:00.000Z",
"updated_at": "2026-04-20T00:00:00.000Z"
},
"mba3_pre_check": { "checked_at": "2026-04-29T15: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"
}
HTTPCaso
400Body invalido o faltan campos obligatorios
401Falta Authorization, ServiceKey invalida, o se envio Bearer
409Cliente ya existe (EXISTS_IN_MBA3 o EXISTS_LOCAL)
502MBA3 / Consulta Externa rechazo el pre-check
504MBA3 / Consulta Externa no respondio antes del timeout
Terminal window
curl -X POST 'https://credigestion-api.novicompu.com/api/v1/credigestion/clients/from-isisystem' \
-H 'Authorization: ServiceKey <ISISYSTEM_SERVICE_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0991234567"
}'

Actualiza un cliente existente en PostgreSQL local. El registro queda con mba3_synced = false hasta que se sincronice manualmente hacia MBA3.

Autenticacion: ServiceKey o Bearer JWT

ParamSignificado
codigoValor de codigo_cliente en el registro local

Todos los campos son opcionales. Solo se actualiza lo enviado.

{
"nombre_cliente": "Erick Marcillo Actualizado",
"email": "[email protected]",
"telefono_1": "0999999999",
"termino_pagos": "60",
"limite_credito_1": "8000.00",
"extra_fields": {
"texto_4": "Observacion comercial"
}
}
{
"success": true,
"operation": "update",
"client": {
"id": "1",
"codigo_cliente": "CLI001",
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo Actualizado",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0999999999",
"telefono_2": "022345678",
"direccion_1": "Av. Principal 123",
"codigo_vendedor": "VEN01",
"termino_pagos": "60",
"limite_credito_1": 8000,
"limite_credito_2": 0,
"mba3_synced": false,
"source_system": "ISISYSTEM",
"created_at": "2026-04-14T00:00:00.000Z",
"updated_at": "2026-04-14T01:00:00.000Z"
}
}
HTTPCaso
400Body invalido
401Autorizacion invalida
404No existe un cliente local con ese codigo_cliente

Lista clientes locales con paginacion y busqueda.

Autenticacion: solo Bearer JWT

ParamTipoDefaultDescripcion
pagenumber1Numero de pagina
per_pagenumber20Cantidad por pagina
searchstringBusca por nombre_cliente, identificacion o codigo_cliente
{
"clients": [
{
"id": "1",
"codigo_cliente": "CLI001",
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0991234567",
"telefono_2": null,
"direccion_1": null,
"codigo_vendedor": null,
"termino_pagos": null,
"limite_credito_1": null,
"limite_credito_2": null,
"mba3_synced": true,
"source_system": "ISISYSTEM",
"created_at": "2026-04-14T00:00:00.000Z",
"updated_at": "2026-04-14T00:00:00.000Z"
}
],
"pagination": {
"total_count": 1,
"total_pages": 1,
"current_page": 1,
"per_page": 20
}
}

Obtiene un cliente local por codigo_cliente.

Autenticacion: solo Bearer JWT

{
"client": {
"id": "1",
"codigo_cliente": "CLI001",
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"email": "[email protected]",
"telefono_1": "0991234567",
"telefono_2": null,
"direccion_1": null,
"codigo_vendedor": null,
"termino_pagos": null,
"limite_credito_1": null,
"limite_credito_2": null,
"mba3_synced": true,
"source_system": "ISISYSTEM",
"created_at": "2026-04-14T00:00:00.000Z",
"updated_at": "2026-04-14T00:00:00.000Z"
}
}

POST /api/v1/credigestion/clients/:codigo/sync-mba3

Section titled “POST /api/v1/credigestion/clients/:codigo/sync-mba3”

Sincroniza manualmente el cliente local hacia MBA3.

Autenticacion: solo Bearer JWT

Llama a /mba3api/clientes (operacion 0 = create / 1 = update segun el flag mba3_synced). Marca el cliente como sincronizado y guarda la respuesta de MBA3.


ColumnaTipoNullableDescripcion
idbigintNoIdentificador interno
codigo_clientevarchar(80) uniqueSiCodigo del cliente en MBA3
codigo_empresavarchar(20)NoEmpresa en MBA3
nombre_clientevarchar(255)NoNombre del cliente
identificacionvarchar(50)NoCedula, RUC o identificacion fiscal
emailvarchar(255)SiCorreo
telefono_1varchar(50)SiTelefono principal
telefono_2varchar(50)SiTelefono secundario
direccion_1textSiDireccion principal
codigo_vendedorvarchar(100)SiVendedor asociado
termino_pagosvarchar(100)SiTermino de pago
limite_credito_1decimal(14,2)SiLimite principal
limite_credito_2decimal(14,2)SiLimite secundario
codigo_sucursalvarchar(50)SiCodigo de sucursal
localizacionvarchar(50)SiLocalizacion
lista_preciosvarchar(50)SiLista de precios
nivel_riesgovarchar(50)SiNivel de riesgo
extra_fieldsjsonbSiCampos adicionales de MBA3
mba3_syncedbooleanNoSi MBA3 confirmo el proceso
mba3_responsejsonbSiRespuesta cruda de MBA3
mba3_synced_attimestampSiFecha de sincronizacion
source_systemvarchar(50)NoOrigen del request
created_attimestampNoFecha de creacion
updated_attimestampNoFecha de actualizacion

Antes de crear, el servicio valida que no exista un registro con la misma combinacion: identificacion + codigo_empresa. Si ya existe, devuelve 409 Conflict.


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

FamiliaCamposNotas
lista_datos_nlista_datos_1 a lista_datos_10Valores de lista
alfanumerico_nalfanumerico_1 a alfanumerico_10Texto alfanumerico
valor_nvalor_1 a valor_10Valores numericos
fecha_nfecha_1 a fecha_10Formato aaaa-mm-dd
booleano_nbooleano_1 a booleano_101=True / 0=False
texto_ntexto_1 a texto_10Texto libre (hasta 32000 chars)
{
"codigo_empresa": "EMP01",
"nombre_cliente": "Erick Marcillo",
"identificacion": "1723955199",
"extra_fields": {
"fecha_6": "2026-04-14",
"booleano_8": "1",
"texto_4": "Creado desde ISISYSTEM",
"valor_8": "1250.55"
}
}

API publicaPayload MBA3
codigo_empresacodigo_empresa
codigo_clientecodigo_cliente
nombre_clientenombre_cliente
identificacionidentificacion
telefono_1numero_telefono_1
telefono_2numero_telefono_2
direccion_1direccion_1
emailemail
codigo_vendedorcodigo_vendedor
termino_pagostermino_pagos
limite_credito_1limite_credito_1
limite_credito_2limite_credito_2
codigo_sucursalcodigo_sucursal
localizacionlocalizacion
lista_precioslista_precios
nivel_riesgonivel_riesgo

El servicio asigna automaticamente operacion: creacion = 0, actualizacion = 1.


El filtro global del servicio responde errores con este envelope:

{
"status": "error",
"statusCode": 400,
"message": "Error de validacion",
"errors": ["codigo_empresa es obligatorio"]
}
{
"status": "error",
"statusCode": 400,
"message": "Error de validacion",
"errors": ["codigo_empresa es obligatorio", "identificacion es obligatorio"]
}
{
"status": "error",
"statusCode": 409,
"message": "Ya existe un cliente con identificacion 1723955199 en la empresa EMP01"
}

Rechazo de MBA3 con HTTP 200 pero error_api: true

Section titled “Rechazo de MBA3 con HTTP 200 pero error_api: true”
{
"status": "error",
"statusCode": 502,
"message": {
"message": "MBA3 rechazo la creacion del cliente",
"upstreamMessage": "Error al procesar API CLIE1001 / Erick Marcillo El Codigo del Cliente ya Existe...",
"operation": "create"
}
}
{
"status": "error",
"statusCode": 504,
"message": "MBA3 no respondio a tiempo durante la creacion del cliente"
}

NODE_ENV=development
PORT=3005
DB_HOST=postgres
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=credigestion_service_development
AUTH_SERVICE_URL=http://ms-auth:3000
SERVICE_KEY=dev_service_key_change_me
ISISYSTEM_SERVICE_KEY=change_me_isisystem_key
MBA3_SERVICE_KEY=change_me_mba3_key
MBA_WEB_API_BASE_URL=http://192.168.80.190:8081
MBA_WEB_API_LOGIN_PATH=/login_Servicio
MBA_WEB_API_CODIGO=856
MBA_WEB_API_PWD=<password>
MBA_CLIENTS_API_PATH=/mba3api/clientes
MBA_CLIENT_OPERATION_CREATE=0
MBA_CLIENT_OPERATION_UPDATE=1
MBA_CONSULTA_EXTERNA_URL=http://192.168.80.201:8081
MBA_SERVICE_URL=http://ms-mba:3000
MBA_AUTH_TOKEN=<token>