Creacion de proveedores

Creacion de proveedores

Objetivo del proceso

Documentar el flujo tecnico de alta de proveedores en NoviSuite para asegurar que la captura en frontend, la validacion en backend y la integracion con MBA3 se ejecuten de forma consistente, trazable y segura.

El objetivo funcional es permitir que un usuario cree un proveedor desde NoviSuite y que dicho registro quede persistido en MBA3 usando el contrato JSON esperado por el ERP.

Flujo de datos (Arquitectura)

Componentes involucrados

Componente	Tecnologia	Responsabilidad
Formulario de proveedores	React	Captura la informacion del proveedor en 5 secciones: Informacion del Proveedor, Ubicacion, Contactos, Datos Bancarios y Condiciones de Pago.
Capa de validacion cliente	React	Ejecuta validaciones previas al envio y evita solicitudes con datos incompletos o mal formados.
API intermediaria	NestJS	Recibe el DTO del frontend, valida, transforma y adapta la data al esquema plano requerido por MBA3.
Adaptador ERP	NestJS + HTTP client	Invoca el endpoint de MBA3 para crear el proveedor y normaliza la respuesta.
ERP	MBA3 API	Registra el proveedor y devuelve el resultado de la operacion.

Diagrama del flujo

Secuencia end-to-end

1. El usuario ingresa al modulo Maestro de Proveedores en NoviSuite.
2. Completa el formulario distribuido en las secciones Informacion del Proveedor, Ubicacion, Contactos, Datos Bancarios y Condiciones de Pago.
3. React valida reglas de negocio antes del submit, por ejemplo formato de correo, estructura de RUC o Tax ID, campos obligatorios y consistencia minima de telefonos o cuentas.
4. El usuario hace clic en Crear Proveedor.
5. El frontend construye un payload interno y lo envia al backend de NestJS.
6. NestJS vuelve a validar el DTO recibido, transforma la estructura del frontend al esquema plano de MBA3 y asigna valores por defecto requeridos por el contrato.
7. NestJS envia una peticion POST al endpoint de MBA3 para registrar el proveedor.
8. MBA3 responde con exito o con error funcional o tecnico.
9. NestJS normaliza la respuesta hacia NoviSuite.
10. React muestra confirmacion de creacion o una alerta con el motivo del fallo.

Contrato de integracion con MBA3

• Metodo: POST
• Endpoint de referencia: /mba3api/proveedores
• Tipo de integracion: request-response sincrona
• Formato de salida desde NestJS: JSON plano con llaves exactas definidas por MBA3

Payload de referencia hacia MBA3

{
  "operacion": "0",
  "codigo_empresa": "EMP01",
  "codigo_proveedor": "PROV62",
  "nombre_proveedor": "Proveeodor 1",
  "rfc_ruc_ci_proveedor": "6222222222",
  "contacto": "099999999",
  "direccion_1": "Ecuador",
  "direccion_2": "",
  "codigo_pais": "",
  "codigo_estado": "",
  "codigo_ciudad": "",
  "codigo_sector": "",
  "codigo_postal_zip": "",
  "telefono_1": "",
  "telefono_2": "",
  "correo_electronico": "[email protected]",
  "fax": "",
  "terminos_de_pago": "",
  "limite_credito_1": "",
  "limite_credito_2": "",
  "codigo_tipo_proveedor": "",
  "codigo_moneda": "",
  "codigo_zona": "",
  "notas_memo": "",
  "localizacion": "L",
  "nombre_extenso_razon_social": "",
  "codigo_sucursal": "",
  "cuenta_contable_x_pagar": "",
  "nombre_del_banco": "",
  "cuenta_bancaria_1": "",
  "cuenta_bancaria_2": "",
  "aba_swift": "BOFAUS3N",
  "nombre_beneficiario": "",
  "codigo_transferencias": "",
  "codigo_transaccion": "",
  "definible_transferencia_1": "",
  "definible_transferencia_2": "",
  "definible_transferencia_3": "",
  "codigo_retenciones": "",
  "impuestos": "",
  "relacionada": "",
  "usar_nombre_alterno_en_impresion": "",
  "numero_exterior": "",
  "numero_interior": "",
  "nombre_colonia": "",
  "nombre_localizacion": "",
  "moneda_unica": "1",
  "proveedor_global": "Amazon",
  "grupo_impuestos": "",
  "codigo_regimen_fiscal": "",
  "fecha_de_creacion_del_registro": "2023-01-01",
  "cuenta_contable_reserva": ""
}

Validaciones en el Frontend

Antes de invocar el backend, React debe impedir el envio si falla cualquiera de las siguientes reglas:

Categoria	Regla recomendada	Resultado esperado
Campos obligatorios	Validar presencia de nombre del proveedor, identificacion fiscal, direccion principal, correo principal y cualquier campo marcado como obligatorio por negocio.	El usuario corrige el formulario antes del submit.
RUC o Tax ID	Validar longitud, patron numerico o alfanumerico y checksum cuando aplique segun el pais.	Evitar rechazos funcionales del ERP.
Correo electronico	Validar formato RFC basico y eliminar espacios al inicio o final.	Enviar un valor consistente a correo_electronico.
Telefonos	Limpiar caracteres no permitidos y restringir longitud maxima segun el contrato ERP.	Poblar telefono_1, telefono_2 y contacto sin caracteres inesperados.
Cuentas bancarias	Validar formato solo si el usuario captura datos bancarios o selecciona un metodo de pago que los requiera.	Evitar payloads parciales incoherentes.
Campos catalogo	Verificar que pais, estado, ciudad, moneda, zona, regimen fiscal y tipo de proveedor provengan de catalogos validos.	Enviar codigos compatibles con MBA3.
Numericos y montos	Normalizar valores numericos vacios a 0 cuando el contrato de MBA3 lo exija.	Evitar errores por conversion o rechazo de datos.
Fechas	Enviar formato YYYY-MM-DD.	Cumplir con fecha_de_creacion_del_registro.
Texto libre	Aplicar trim, limitar longitudes y remover valores null o undefined.	Enviar cadenas vacias cuando el campo sea opcional.
Contactos dinamicos	Seleccionar un contacto principal para el ERP cuando existan multiples contactos en UI.	Mapear correctamente los campos planos de MBA3.
Doble envio	Deshabilitar el boton mientras la solicitud este en curso.	Evitar registros duplicados.

Criterios tecnicos de normalizacion

• No enviar propiedades null ni undefined al adaptador de MBA3.
• Convertir el formulario a un DTO tipado antes de construir el payload del ERP.
• Si el frontend permite multiples contactos, definir un criterio explicito para el contacto principal, ya que MBA3 expone un conjunto plano de campos de contacto.
• Si MBA3 requiere que todos los campos numericos viajen con valor, NestJS debe homologar a 0 cualquier valor vacio antes de invocar el ERP.

Mapeo de datos (Data Mapping)

La siguiente tabla relaciona los campos visuales del formulario de NoviSuite con las llaves del JSON que espera MBA3. Se incluyen tambien valores por defecto, campos derivados y observaciones de transformacion.

Seccion UI	Campo visual o fuente	Llave MBA3	Regla de transformacion
Sistema	Operacion	operacion	Valor fijo 0 para creacion de proveedor.
Sistema	Empresa activa o tenant	codigo_empresa	Se toma de configuracion o contexto de compania.
Informacion del Proveedor	Codigo de proveedor	codigo_proveedor	Puede ser ingresado por usuario o generado por regla interna.
Informacion del Proveedor	Nombre del proveedor	nombre_proveedor	Campo principal visible en UI.
Informacion del Proveedor	RUC o Tax ID	rfc_ruc_ci_proveedor	Normalizar sin espacios ni caracteres no permitidos.
Informacion del Proveedor	Razon social	nombre_extenso_razon_social	Usar cuando difiere del nombre corto del proveedor.
Informacion del Proveedor	Tipo de proveedor	codigo_tipo_proveedor	Debe salir de catalogo homologado.
Informacion del Proveedor	Proveedor global	proveedor_global	Texto o identificador corporativo segun negocio.
Informacion del Proveedor	Grupo de impuestos	grupo_impuestos	Codigo de catalogo fiscal.
Informacion del Proveedor	Regimen fiscal	codigo_regimen_fiscal	Codigo homologado con ERP.
Informacion del Proveedor	Codigo de retenciones	codigo_retenciones	Codigo de catalogo.
Informacion del Proveedor	Impuestos	impuestos	Valor textual o lista codificada segun contrato ERP.
Informacion del Proveedor	Notas u observaciones	notas_memo	Texto libre con limite definido por MBA3.
Ubicacion	Direccion principal	direccion_1	Calle o direccion base.
Ubicacion	Direccion complementaria	direccion_2	Referencia adicional o secundaria.
Ubicacion	Pais	codigo_pais	Codigo de catalogo.
Ubicacion	Estado o provincia	codigo_estado	Codigo de catalogo dependiente del pais.
Ubicacion	Ciudad	codigo_ciudad	Codigo de catalogo dependiente del estado.
Ubicacion	Sector	codigo_sector	Codigo de sector o zona local.
Ubicacion	Codigo postal	codigo_postal_zip	Texto o alfanumerico segun pais.
Ubicacion	Localizacion	localizacion	Valor recomendado L para local o E para exterior.
Ubicacion	Nombre de localizacion	nombre_localizacion	Descripcion de la zona o localizacion.
Ubicacion	Numero exterior	numero_exterior	Valor textual.
Ubicacion	Numero interior	numero_interior	Valor textual.
Ubicacion	Colonia o barrio	nombre_colonia	Nombre descriptivo del sector.
Ubicacion	Codigo sucursal	codigo_sucursal	Sucursal contable o administrativa.
Contactos	Contacto principal	contacto	Si hay multiples contactos, usar el principal definido en UI.
Contactos	Telefono principal	telefono_1	Limpiar caracteres especiales no permitidos.
Contactos	Telefono secundario	telefono_2	Opcional.
Contactos	Correo electronico principal	correo_electronico	Validar formato antes del envio.
Contactos	Fax	fax	Opcional.
Contactos	Nombre alterno para impresion	usar_nombre_alterno_en_impresion	Valor textual segun configuracion del proceso.
Datos Bancarios	Cuenta contable por pagar	cuenta_contable_x_pagar	Codigo contable homologado.
Datos Bancarios	Nombre del banco	nombre_del_banco	Texto libre controlado.
Datos Bancarios	Cuenta bancaria 1	cuenta_bancaria_1	Cuenta principal.
Datos Bancarios	Cuenta bancaria 2	cuenta_bancaria_2	Cuenta secundaria opcional.
Datos Bancarios	ABA o SWIFT	aba_swift	Codigo bancario internacional.
Datos Bancarios	Beneficiario	nombre_beneficiario	Nombre asociado a la cuenta.
Datos Bancarios	Codigo de transferencias	codigo_transferencias	Codigo de catalogo o convenio bancario.
Datos Bancarios	Codigo de transaccion	codigo_transaccion	Identificador de tipo de transaccion.
Datos Bancarios	Definible transferencia 1	definible_transferencia_1	Campo parametrico opcional.
Datos Bancarios	Definible transferencia 2	definible_transferencia_2	Campo parametrico opcional.
Datos Bancarios	Definible transferencia 3	definible_transferencia_3	Campo parametrico opcional.
Datos Bancarios	Cuenta contable reserva	cuenta_contable_reserva	Cuenta contable alternativa o de reserva.
Condiciones de Pago	Terminos de pago	terminos_de_pago	Numero o codigo segun contrato.
Condiciones de Pago	Limite de credito 1	limite_credito_1	Si no aplica y el ERP lo exige, enviar 0.
Condiciones de Pago	Limite de credito 2	limite_credito_2	Si no aplica y el ERP lo exige, enviar 0.
Condiciones de Pago	Moneda	codigo_moneda	Codigo homologado.
Condiciones de Pago	Moneda unica	moneda_unica	Valor por defecto 1 segun el contrato provisto.
Condiciones de Pago	Zona	codigo_zona	Codigo de catalogo comercial o geografico.
Condiciones de Pago	Relacionada	relacionada	Indicador de relacion comercial o contable.
Sistema	Fecha de creacion	fecha_de_creacion_del_registro	Generada por sistema en formato YYYY-MM-DD.

Recomendaciones de transformacion en NestJS

• Implementar un mapper dedicado, por ejemplo SupplierMba3Mapper, separado del controller.
• Centralizar valores por defecto como operacion, localizacion y moneda_unica en configuracion o constantes.
• Mantener un DTO interno para el formulario y un DTO externo exclusivo para MBA3.
• Registrar logs con identificador de correlacion, pero sin exponer datos sensibles completos en consola.

Manejo de errores (Error Handling)

NestJS debe actuar como capa de contencion entre NoviSuite y MBA3. El frontend no debe recibir errores crudos del ERP, sino una respuesta controlada, trazable y orientada a usuario.

Estrategia recomendada

1. Validar el request en frontend y nuevamente en NestJS.
2. Envolver la llamada a MBA3 en un servicio de integracion con try/catch y timeout explicito.
3. Interpretar el codigo HTTP y el cuerpo de error devuelto por MBA3.
4. Traducir el fallo a un contrato de error estandar para NoviSuite.
5. Registrar el detalle tecnico en logs y devolver al frontend un mensaje entendible con codigo de seguimiento.

Matriz de errores sugerida

Escenario	Origen	Accion en NestJS	Respuesta sugerida al frontend
Campos requeridos faltantes	React o NestJS	Rechazar antes de invocar MBA3.	400 Bad Request con detalle por campo.
RUC, email o formato invalido	React o NestJS	Rechazar validacion.	422 Unprocessable Entity con mensaje funcional.
Codigo de proveedor duplicado	MBA3	Traducir error funcional del ERP.	409 Conflict indicando que el proveedor ya existe.
Catalogo invalido	MBA3	Propagar error de negocio normalizado.	422 Unprocessable Entity con detalle del campo homologado.
Timeout o indisponibilidad de MBA3	Red o ERP	Capturar excepcion HTTP y marcar integracion no disponible.	504 Gateway Timeout o 502 Bad Gateway.
Error interno no controlado	NestJS	Loggear excepcion y ocultar detalle sensible.	500 Internal Server Error con mensaje generico.

Contrato de error recomendado

{
  "success": false,
  "code": "MBA3_VALIDATION_ERROR",
  "message": "No fue posible crear el proveedor en MBA3.",
  "details": [
    {
      "field": "rfc_ruc_ci_proveedor",
      "message": "El RUC enviado no cumple con el formato esperado."
    }
  ],
  "upstreamStatus": 422,
  "correlationId": "8f3a2f82-5e0f-4a1d-9f72-4d89d7f43b6d",
  "timestamp": "2026-04-01T10:30:00Z"
}

Comportamiento esperado en la UI

• Si MBA3 responde con exito, NoviSuite debe mostrar una notificacion de confirmacion al usuario.
• Si MBA3 responde con error funcional, React debe resaltar el problema y mostrar un mensaje accionable.
• Si el error es tecnico o de conectividad, React debe mostrar una alerta generica con el identificador de correlacion para soporte.
• El formulario no debe perder la informacion capturada cuando ocurra un error recuperable.

Resultado esperado

Cuando el flujo esta correctamente implementado, NoviSuite valida los datos del proveedor, los transforma al contrato de MBA3 y devuelve al usuario una confirmacion de alta o un error controlado, manteniendo trazabilidad completa entre frontend, backend y ERP.