Errores de Negocio — /business-errors
El transporte funcionó — HTTP 200, RFC ejecutada, INSERT aceptado — y aun así el mensaje no hizo lo
que debía. El destino respondió “orden no liberada”, “CPF inválido”, “período contable cerrado”. Para
el CMS, técnicamente, fue un éxito.
Los Errores de Negocio corrigen esa lectura: son reglas que miran el contenido de lo que entró o de lo que volvió y dicen “esto fue una falla”.
Sin esa clasificación, un destino que rechaza todo aparece en los paneles como 100% de éxito — y el problema solo se descubre cuando alguien echa de menos el dato, días después.
Anatomía de una regla
| Campo | Rol |
|---|---|
| Aplicación | La Aplicación dueña de la regla. Una regla nunca atraviesa Aplicaciones |
| Dónde vale la regla | Definiciones elegidas, o toda la Aplicación |
| Código del Error | Opcional. El código del sistema de origen, para agrupar en los informes |
| Términos de Búsqueda | Qué buscar en el payload. Varios términos separados por ; |
| Validar contra | Entrada, Salida o Ambos |
| Motivo | Texto libre explicando por qué ese error suele ocurrir |
| Bloquea Interfaz | Si lo detecta, detiene la interfaz entera |
| Activo | Enciende/apaga la regla sin borrarla |
Dónde vale la regla: Definiciones elegidas o toda la Aplicación
Una regla vale para varias Definiciones a la vez, incluso de Interfaces distintas de la misma Aplicación. “Período contable cerrado” suele ser el mismo texto en toda integración financiera, y no hace falta registrarlo una vez por Definición.
| Alcance | Qué cubre |
|---|---|
| Definiciones elegidas | Solo las que marques en la lista |
| Toda la Aplicación | Todas las Definiciones de la Aplicación, incluidas las creadas después |
Con Toda la Aplicación, el CMS mantiene los vínculos solo: una Definición nueva — creada a mano, por import, por pack o por asistente — ya nace cubierta por la regla. En la lista, esas reglas traen la etiqueta Aplicación.
Un Error de Negocio nunca atraviesa Aplicaciones. “Toda la Aplicación” es el alcance máximo, y por eso la Aplicación se elige antes que todo en el formulario.
En una regla de alcance Toda la Aplicación no existe “desvincular solo de esta Definición”: la próxima sincronización devolvería el vínculo. Para sacarla de circulación, cambia el alcance o elimina la regla.
Términos de búsqueda: OR, no AND
ordem_error;quantidade=0 significa “cualquiera de estos”. Basta con que un término aparezca en
el payload para que el mensaje se clasifique. Un solo término se comporta exactamente como antes de
que existiera la separación por ;.
La comparación es por contenido literal (substring), no por expresión regular — es lo que permite pegar el fragmento del mensaje de error del sistema de origen y que funcione.
Lo que queda grabado en el mensaje es el texto entero del campo Términos de Búsqueda, no el término que coincidió. Por ese texto agrupa el informe de Errores de Negocio — editar el campo después cambia el agrupamiento de los mensajes nuevos.
Validar contra: entrada, salida o ambos
| Dirección | Mira |
|---|---|
| Entrada | El payload que la interfaz recibió |
| Salida | El retorno que el destino devolvió |
| Ambos | Los dos |
La mayoría de las reglas son de Salida — ahí vive la respuesta del destino. Entrada es útil para rechazar temprano un mensaje mal formado, antes de gastar una llamada al destino.
Algunos tipos de Recolección no tienen lado de entrada — una suscripción MQTT, por ejemplo, es recepción pasiva. Ahí, una regla de Entrada simplemente nunca coincide; no genera error ni aviso.
Bloqueo de interfaz
Este es el mecanismo que diferencia al CMS de un simple log de errores.
Marcando Bloquea Interfaz, el primer mensaje que coincida con la regla detiene la interfaz.
Los mensajes siguientes quedan en la cola, intactos, esperando. El bloqueo queda registrado con origen
ERRO_NEGOCIO, el texto de la regla y el ID del mensaje que lo causó.
Por qué esto es deseable: sin el bloqueo, un destino en estado inválido — período cerrado, maestro faltante, sistema en mantenimiento lógico — recibiría cientos de mensajes que va a rechazar uno por uno. Todos se vuelven error, todos necesitan reprocesarse después, y el historial queda contaminado.
Cómo liberar
El desbloqueo se registra con su origen:
| Origen | Cuándo |
|---|---|
| Manual | Alguien liberó la interfaz en la pantalla de Interfaces o en la Danger Zone |
| Reprocesamiento | El mensaje que causó el bloqueo se reprocesó con éxito |
| Cancelación | El mensaje que causó el bloqueo fue cancelado |
Los dos últimos son el camino normal: resuelva la causa y la interfaz se libera sola. Todo el historial queda en el informe de Bloqueo de Interfaces.
Bloquear es una decisión de negocio, no técnica. “CPF inválido” casi nunca debe bloquear — es un problema de ese mensaje. “Período contable cerrado” casi siempre debe — ningún mensaje va a pasar hasta que alguien abra el período.
Reglas automáticas
Algunas reglas no se escriben aquí: el CMS las mantiene sincronizadas desde otra pantalla, y aparecen en la lista con la etiqueta AUTO. En ellas, el único campo editable es Bloquea Interfaz — el resto pertenece a la pantalla de origen.
| Etiqueta AUTO generada por | Origen |
|---|---|
| Tags OPC UA obligatorias | Tags de Lectura de la Recolección / Tags de Escritura de la Entrega, marcadas “obligatorio” |
| Tags Modbus obligatorias | Ídem, en el adaptador Modbus |
| Payload de Entrada obligatorio | Campos marcados “obligatorio” en el popup Parámetros Función SAP de una Entrega SAP RFC |
La lógica de esas reglas está invertida respecto a las normales: en vez de “este término apareció”, verifican “estos valores están presentes”. Un valor nulo, vacío o cero cuenta como ausente — lo que en un PLC es exactamente el caso a tratar: una tag que no fue escrita en este ciclo devuelve cero, no error.
Esto resuelve un problema real de planta: el PLC responde con éxito y devuelve cero en todas las tags porque la pieza aún no pasó. Sin esa regla, el CMS grabaría una medición de cero como si fuera una lectura válida.
Qué pasa con el mensaje
El mensaje clasificado queda con estado Error Negocio y guarda el texto de la regla que coincidió y el motivo registrado. Aparece en:
- Mensajes con Error, donde puede reprocesarse en lote;
- en el informe de Errores de Negocio, agrupado por aplicación, interfaz y definición;
- en la alerta Error de Negocio, si hay una configurada — ver Alertas.
Permiso
La Herramienta es /business-errors. Como las demás pantallas agrupadas por Aplicación, exige además
que el usuario vea la Aplicación y la Interfaz correspondientes.