Clientes
Clientes
Section titled “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.
Proposito
Section titled “Proposito”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
Datos Base del Servicio
Section titled “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 upstream | POST /mba3api/clientes en MBA3 |
Autenticacion
Section titled “Autenticacion”El servicio maneja dos esquemas distintos segun el endpoint:
| Esquema | Header | Uso |
|---|---|---|
ServiceKey | Authorization: ServiceKey <ISISYSTEM_SERVICE_KEY> | Sistemas externos como ISISYSTEM |
Bearer JWT | Authorization: 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.
Reglas de Acceso
Section titled “Reglas de Acceso”| Endpoint | ServiceKey | Bearer JWT |
|---|---|---|
POST /api/v1/credigestion/clients/exists | Si | Si |
POST /api/v1/credigestion/clients | Si | Si |
POST /api/v1/credigestion/clients/from-isisystem | Si (ServiceKey-only) | No |
PUT /api/v1/credigestion/clients/:codigo | Si | Si |
GET /api/v1/credigestion/clients | No | Si |
GET /api/v1/credigestion/clients/:codigo | No | Si |
Origen del Request (source_system)
Section titled “Origen del Request (source_system)”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.
Resumen de Endpoints
Section titled “Resumen de Endpoints”| Accion | Endpoint | Autenticacion |
|---|---|---|
| Verificar existencia | POST /api/v1/credigestion/clients/exists | ServiceKey o JWT |
| Crear cliente | POST /api/v1/credigestion/clients | ServiceKey o JWT |
| Crear desde ISISYSTEM | POST /api/v1/credigestion/clients/from-isisystem | ServiceKey solo |
| Actualizar cliente | PUT /api/v1/credigestion/clients/:codigo | ServiceKey o JWT |
| Listar clientes | GET /api/v1/credigestion/clients | JWT solo |
| Obtener cliente | GET /api/v1/credigestion/clients/:codigo | JWT solo |
| Sincronizar con MBA3 | POST /api/v1/credigestion/clients/:codigo/sync-mba3 | JWT solo |
POST /api/v1/credigestion/clients/exists
Section titled “POST /api/v1/credigestion/clients/exists”Verifica si el cliente existe en la fuente de verdad MBA3 usando Consulta Externa.
Autenticacion: ServiceKey o Bearer JWT
{ "codigo_empresa": "EMP01", "identificacion": "0917582967"}Campos Obligatorios
Section titled “Campos Obligatorios”| Campo | Tipo | Regla |
|---|---|---|
codigo_empresa | string | Obligatorio, maximo 20 |
identificacion | string | Obligatorio, maximo 50 |
Respuesta Exitosa (existe en MBA3)
Section titled “Respuesta Exitosa (existe en MBA3)”{ "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", "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" }}Respuesta Exitosa (no existe)
Section titled “Respuesta Exitosa (no existe)”{ "success": true, "exists": false, "source": "MBA3_CONSULTA_EXTERNA", "criteria": { "codigo_empresa": "EMP01", "identificacion": "9999999999" }, "client": null, "local_record": null}Errores
Section titled “Errores”| HTTP | Caso |
|---|---|
400 | Body invalido o faltan campos obligatorios |
401 | Falta autorizacion, ServiceKey invalida, JWT invalido o expirado |
502 | MBA3 o Consulta Externa rechazo la consulta |
504 | Consulta Externa no respondio antes del timeout |
POST /api/v1/credigestion/clients
Section titled “POST /api/v1/credigestion/clients”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", "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" }}Campos Obligatorios
Section titled “Campos Obligatorios”| Campo | Tipo | Regla |
|---|---|---|
codigo_empresa | string | Obligatorio, maximo 20 |
nombre_cliente | string | Obligatorio, maximo 255 |
identificacion | string | Obligatorio, maximo 50 |
Campos Opcionales
Section titled “Campos Opcionales”| Campo | Tipo | Regla |
|---|---|---|
codigo_cliente | string | Maximo 80 |
email | string | Email valido, maximo 255 |
telefono_1 | string | Maximo 50 |
telefono_2 | string | Maximo 50 |
direccion_1 | text | — |
codigo_vendedor | string | Maximo 100 |
termino_pagos | string | Maximo 100 |
limite_credito_1 | string | Numerico como string |
limite_credito_2 | string | Numerico como string |
codigo_sucursal | string | — |
localizacion | string | — |
lista_precios | string | — |
nivel_riesgo | string | — |
extra_fields | object | Objeto clave-valor |
Respuesta Exitosa (201 Created)
Section titled “Respuesta Exitosa (201 Created)”{ "success": true, "operation": "create", "client": { "id": "1", "codigo_cliente": "CLI001", "codigo_empresa": "EMP01", "nombre_cliente": "Erick Marcillo", "identificacion": "1723955199", "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" }}Errores
Section titled “Errores”| HTTP | Caso |
|---|---|
400 | Body invalido o faltan campos obligatorios |
401 | Falta autorizacion, ServiceKey invalida, JWT invalido o expirado |
409 | Ya 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)
Workflow
Section titled “Workflow”ServiceKeyGuardvalidaAuthorization: ServiceKey <ISISYSTEM_SERVICE_KEY>(rechaza Bearer con401)- Pre-check en paralelo: consulta MBA3 y registro local
- Decision:
- Si MBA3 lo tiene →
409 EXISTS_IN_MBA3conmba3_clientylocal_record - Si solo existe local →
409 EXISTS_LOCALconlocal_record - Si no existe en ninguno → crea en PostgreSQL local con
source_system = 'ISISYSTEM'ymba3_synced = false
- Si MBA3 lo tiene →
- Devuelve
201 CREATEDconmba3_pre_checkadjunto
{ "codigo_empresa": "EMP01", "nombre_cliente": "Erick Marcillo", "identificacion": "1723955199", "telefono_1": "0991234567", "telefono_2": "022345678", "direccion_1": "Av. Principal 123", "extra_fields": { "alfanumerico_1": "SEGMENTO-A" }}Campos Obligatorios
Section titled “Campos Obligatorios”| Campo | Tipo | Regla |
|---|---|---|
codigo_empresa | string | Obligatorio, maximo 20 |
nombre_cliente | string | Obligatorio, maximo 255 |
identificacion | string | Obligatorio, maximo 50 |
Respuesta 201 CREATED (cliente creado)
Section titled “Respuesta 201 CREATED (cliente creado)”{ "success": true, "reason": "CREATED", "operation": "create", "client": { "id": "42", "codigo_cliente": null, "codigo_empresa": "EMP01", "nombre_cliente": "Erick Marcillo", "identificacion": "1723955199", "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 }}Respuesta 409 EXISTS_IN_MBA3
Section titled “Respuesta 409 EXISTS_IN_MBA3”{ "success": false, "reason": "EXISTS_IN_MBA3", "mba3_client": { "codigo_cliente": "CLIE1001", "codigo_empresa": "EMP01", "nombre_cliente": "Luis Fabricio Cardenas", "identificacion": "0917582967", "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"}Respuesta 409 EXISTS_LOCAL
Section titled “Respuesta 409 EXISTS_LOCAL”{ "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"}Errores
Section titled “Errores”| HTTP | Caso |
|---|---|
400 | Body invalido o faltan campos obligatorios |
401 | Falta Authorization, ServiceKey invalida, o se envio Bearer |
409 | Cliente ya existe (EXISTS_IN_MBA3 o EXISTS_LOCAL) |
502 | MBA3 / Consulta Externa rechazo el pre-check |
504 | MBA3 / Consulta Externa no respondio antes del timeout |
Ejemplo curl
Section titled “Ejemplo curl”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" }'PUT /api/v1/credigestion/clients/:codigo
Section titled “PUT /api/v1/credigestion/clients/:codigo”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
Parametro de Ruta
Section titled “Parametro de Ruta”| Param | Significado |
|---|---|
codigo | Valor de codigo_cliente en el registro local |
Todos los campos son opcionales. Solo se actualiza lo enviado.
{ "nombre_cliente": "Erick Marcillo Actualizado", "telefono_1": "0999999999", "termino_pagos": "60", "limite_credito_1": "8000.00", "extra_fields": { "texto_4": "Observacion comercial" }}Respuesta Exitosa
Section titled “Respuesta Exitosa”{ "success": true, "operation": "update", "client": { "id": "1", "codigo_cliente": "CLI001", "codigo_empresa": "EMP01", "nombre_cliente": "Erick Marcillo Actualizado", "identificacion": "1723955199", "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" }}Errores
Section titled “Errores”| HTTP | Caso |
|---|---|
400 | Body invalido |
401 | Autorizacion invalida |
404 | No existe un cliente local con ese codigo_cliente |
GET /api/v1/credigestion/clients
Section titled “GET /api/v1/credigestion/clients”Lista clientes locales con paginacion y busqueda.
Autenticacion: solo Bearer JWT
Query Params
Section titled “Query Params”| Param | Tipo | Default | Descripcion |
|---|---|---|---|
page | number | 1 | Numero de pagina |
per_page | number | 20 | Cantidad por pagina |
search | string | — | Busca por nombre_cliente, identificacion o codigo_cliente |
Respuesta Exitosa
Section titled “Respuesta Exitosa”{ "clients": [ { "id": "1", "codigo_cliente": "CLI001", "codigo_empresa": "EMP01", "nombre_cliente": "Erick Marcillo", "identificacion": "1723955199", "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 }}GET /api/v1/credigestion/clients/:codigo
Section titled “GET /api/v1/credigestion/clients/:codigo”Obtiene un cliente local por codigo_cliente.
Autenticacion: solo Bearer JWT
Respuesta Exitosa
Section titled “Respuesta Exitosa”{ "client": { "id": "1", "codigo_cliente": "CLI001", "codigo_empresa": "EMP01", "nombre_cliente": "Erick Marcillo", "identificacion": "1723955199", "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.
Modelo de Datos: credigestion_clients
Section titled “Modelo de Datos: credigestion_clients”| Columna | Tipo | Nullable | Descripcion |
|---|---|---|---|
id | bigint | No | Identificador interno |
codigo_cliente | varchar(80) unique | Si | Codigo del cliente en MBA3 |
codigo_empresa | varchar(20) | No | Empresa en MBA3 |
nombre_cliente | varchar(255) | No | Nombre del cliente |
identificacion | varchar(50) | No | Cedula, RUC o identificacion fiscal |
email | varchar(255) | Si | Correo |
telefono_1 | varchar(50) | Si | Telefono principal |
telefono_2 | varchar(50) | Si | Telefono secundario |
direccion_1 | text | Si | Direccion principal |
codigo_vendedor | varchar(100) | Si | Vendedor asociado |
termino_pagos | varchar(100) | Si | Termino de pago |
limite_credito_1 | decimal(14,2) | Si | Limite principal |
limite_credito_2 | decimal(14,2) | Si | Limite secundario |
codigo_sucursal | varchar(50) | Si | Codigo de sucursal |
localizacion | varchar(50) | Si | Localizacion |
lista_precios | varchar(50) | Si | Lista de precios |
nivel_riesgo | varchar(50) | Si | Nivel de riesgo |
extra_fields | jsonb | Si | Campos adicionales de MBA3 |
mba3_synced | boolean | No | Si MBA3 confirmo el proceso |
mba3_response | jsonb | Si | Respuesta cruda de MBA3 |
mba3_synced_at | timestamp | Si | Fecha de sincronizacion |
source_system | varchar(50) | No | Origen del request |
created_at | timestamp | No | Fecha de creacion |
updated_at | timestamp | No | Fecha de actualizacion |
Regla de Duplicidad
Section titled “Regla de Duplicidad”Antes de crear, el servicio valida que no exista un registro con la misma combinacion: identificacion + codigo_empresa. Si ya existe, devuelve 409 Conflict.
Campos Extendidos (extra_fields)
Section titled “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
Section titled “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
Section titled “Ejemplo”{ "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" }}Mapeo entre API Publica y MBA3
Section titled “Mapeo entre API Publica y MBA3”| API publica | Payload MBA3 |
|---|---|
codigo_empresa | codigo_empresa |
codigo_cliente | codigo_cliente |
nombre_cliente | nombre_cliente |
identificacion | identificacion |
telefono_1 | numero_telefono_1 |
telefono_2 | numero_telefono_2 |
direccion_1 | direccion_1 |
email | email |
codigo_vendedor | codigo_vendedor |
termino_pagos | termino_pagos |
limite_credito_1 | limite_credito_1 |
limite_credito_2 | limite_credito_2 |
codigo_sucursal | codigo_sucursal |
localizacion | localizacion |
lista_precios | lista_precios |
nivel_riesgo | nivel_riesgo |
El servicio asigna automaticamente operacion: creacion = 0, actualizacion = 1.
Formato Global de Errores
Section titled “Formato Global de Errores”El filtro global del servicio responde errores con este envelope:
{ "status": "error", "statusCode": 400, "message": "Error de validacion", "errors": ["codigo_empresa es obligatorio"]}Casos Tipicos
Section titled “Casos Tipicos”Error de Validacion de DTO
Section titled “Error de Validacion de DTO”{ "status": "error", "statusCode": 400, "message": "Error de validacion", "errors": ["codigo_empresa es obligatorio", "identificacion es obligatorio"]}Duplicado Local
Section titled “Duplicado Local”{ "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" }}Timeout contra MBA3
Section titled “Timeout contra MBA3”{ "status": "error", "statusCode": 504, "message": "MBA3 no respondio a tiempo durante la creacion del cliente"}Variables de Entorno
Section titled “Variables de Entorno”NODE_ENV=developmentPORT=3005
DB_HOST=postgresDB_PORT=5432DB_USER=postgresDB_PASSWORD=passwordDB_NAME=credigestion_service_development
AUTH_SERVICE_URL=http://ms-auth:3000SERVICE_KEY=dev_service_key_change_meISISYSTEM_SERVICE_KEY=change_me_isisystem_keyMBA3_SERVICE_KEY=change_me_mba3_key
MBA_WEB_API_BASE_URL=http://192.168.80.190:8081MBA_WEB_API_LOGIN_PATH=/login_ServicioMBA_WEB_API_CODIGO=856MBA_WEB_API_PWD=<password>MBA_CLIENTS_API_PATH=/mba3api/clientesMBA_CLIENT_OPERATION_CREATE=0MBA_CLIENT_OPERATION_UPDATE=1MBA_CONSULTA_EXTERNA_URL=http://192.168.80.201:8081MBA_SERVICE_URL=http://ms-mba:3000MBA_AUTH_TOKEN=<token>