Bloqueo de facturación para clientes con deuda
Objetivo
Implementar una validación previa a la generación de una factura que impida continuar con la operación cuando el cliente posea una deuda superior al límite definido por la organización.
Este caso demuestra cómo un BPROC puede incorporar lógica de negocio personalizada sin modificar el comportamiento estándar del ERP.
Problema de negocio
En muchas organizaciones el proceso de facturación continúa normalmente aunque el cliente posea deuda vencida o supere el límite de crédito establecido.
Como consecuencia:
-
El área comercial continúa operando sin conocer la situación financiera del cliente.
-
El área de Finanzas detecta el problema cuando la operación ya fue realizada.
-
Se incrementa el riesgo financiero y el trabajo administrativo posterior.
Solución propuesta
Antes de confirmar la generación de una factura, GO ejecuta un Guest Code mediante un BPROC.
El Guest Code consulta el saldo actual del cliente utilizando una API del ERP.
Si el saldo supera el límite configurado, devuelve una respuesta que impide continuar con la operación e informa al usuario el motivo.
Flujo de la solución
Usuario
↓
Factura de Venta
↓
BPROC Transacción
↓
Guest Code
↓
Consulta API SALDOSCLIE
↓
Evaluación de deuda
↓
Respuesta
Componentes utilizados
Guest Code
El Guest Code contiene la lógica de negocio de la validación.
Su responsabilidad es:
-
recibir la información enviada por el BPROC;
-
identificar el cliente involucrado en la operación;
-
consultar el saldo mediante la API correspondiente;
-
evaluar la condición definida por el negocio;
-
devolver el resultado al ERP.
En este caso se implementó un Guest Code denominado: clientecondeuda
El endpoint generado será utilizado posteriormente por el BPROC.
# Script para Finnegans GO Guest Code
# Validado con información del MCP
# Tipo de BProc: Pregrabación de Factura de Cliente
# Lógica: Consulta saldo del cliente vía API SALDOSCLIE.
#Si el saldo supera $1.000.000, bloquea el guardado y alerta al usuario.
from finnegans.scripting import request, HTTPResponse
from finnegans.bproc import BProcEvent
from finnegans.api import get_reporte, ApiException
from finnegans.logging import logger
MSG_DEUDA = "NO puedes guardar esta factura porque tenes deuda"
MSG_SIN_CLIENTE = "No se encontró el código de cliente en la factura."
MSG_ERROR_API = "No se pudo verificar el saldo del cliente."
LIMITE_SALDO = 1_000_000
def obtener_codigo_cliente(bproc: BProcEvent):
"""Retorna el código de cliente o None si el widget no existe."""
try:
return bproc.get_value("Cliente")
except KeyError:
logger.error("El payload del BProc no contiene la estructura de widgets esperada.")
return None
def consultar_saldo(codigo_cliente: str):
"""
Consulta SALDOSCLIE y retorna el saldo como float.
Retorna None si la API falla o no devuelve resultados.
"""
try:
resultados = get_reporte("SALDOSCLIE", {"CodigoCliente": codigo_cliente})
except ApiException as e:
logger.error(f"Error al consultar SALDOSCLIE para cliente {codigo_cliente}: {e}")
return None
if not resultados:
logger.info(f"Sin resultados en SALDOSCLIE para cliente {codigo_cliente}.")
return 0.0
try:
return float(resultados[0].get("Saldo", 0) or 0)
except (TypeError, ValueError):
logger.error("No se pudo convertir el saldo a número.")
return 0.0
def main():
#──1. Inicializar el evento de pregrabación ─────────────────────────────
bproc = BProcEvent(request.json())
# ── 2. Obtener el código del cliente ─────────────────────────────────────
codigo_cliente = obtener_codigo_cliente(bproc)
if not codigo_cliente:
logger.error(MSG_SIN_CLIENTE)
return HTTPResponse(400, body=MSG_DEUDA)
logger.info(f"Validando saldo para el cliente: {codigo_cliente}")
# ── 3. Consultar el saldo ────────────────────────────────────────────────
saldo = consultar_saldo(codigo_cliente)
if saldo is None:
logger.error(MSG_ERROR_API)
return HTTPResponse(500, body=MSG_ERROR_API)
logger.info(f"Saldo del cliente {codigo_cliente}: ${saldo:,.2f}")
# ── 4. Bloquear si supera el límite ──────────────────────────────────────
if saldo > LIMITE_SALDO:
logger.warning(f"Cliente {codigo_cliente} bloqueado. Saldo ${saldo:,.2f} > ${LIMITE_SALDO:,}")
return HTTPResponse(400, body=MSG_DEUDA)
# ── 5. Saldo aceptable → permitir la grabación ───────────────────────────
return bproc
API consultada
Para obtener la información financiera del cliente se utiliza la API: SALDOSCLIE
La consulta recibe como parámetro el código del cliente y devuelve la información necesaria para determinar el saldo actual.
La lógica implementada compara dicho saldo contra el límite definido para la validación.
Configuración del BPROC
Información general
Se crea un nuevo BPROC con las siguientes características.
Campo
Valor
Nombre
Alerta de Cliente
Código
AlertaCliente
Tipo
Transacción
Aplicación
Aplicación Custom
Descripción
Alerta cuando el cliente supera el límite de deuda permitido
Configuración de ejecución
El BPROC se configura para ejecutarse:
-
sobre Factura de Venta;
-
en modalidad PreGrabación;
-
únicamente durante el evento Crear.
La URL configurada corresponde al endpoint generado por el Guest Code.
¿Por qué se utiliza PreGrabación?
En este escenario la validación debe ejecutarse antes de que la factura sea almacenada.
Esto permite impedir la operación cuando no se cumplen las reglas definidas por el negocio.
Si la validación se realizara luego del guardado, la factura ya existiría en el sistema y el objetivo del control preventivo se perdería. Por este motivo es que no es posible utilizar un bproc de modo webhook.
Flujo de ejecución
-
El usuario intenta guardar una factura.
-
GO identifica el BPROC asociado al documento.
-
Se construye el payload con la información de la factura.
-
El payload se envía al Guest Code.
-
El Guest Code obtiene el código del cliente.
-
Se consulta la API SALDOSCLIE.
-
Se analiza el saldo devuelto.
-
El Guest Code responde al ERP indicando si la operación puede continuar.
Responsabilidad de cada componente
GO
-
Detecta el evento.
-
Construye el payload.
-
Invoca el Guest Code.
BPROC
-
Define cuándo debe ejecutarse la lógica.
-
Envía la información al servicio externo.
No contiene reglas de negocio.
Guest Code
-
Implementa la lógica funcional.
-
Consulta la API.
-
Evalúa la condición.
-
Devuelve el resultado.
Toda la inteligencia de la solución reside en este componente.
API
- Proporciona la información financiera necesaria para tomar la decisión.
Resultado
La validación se realiza antes de completar la operación.
Si el cliente supera el límite permitido, la factura no continúa con el proceso de guardado.
De esta manera, la organización incorpora una regla de negocio específica sin modificar el código estándar del ERP, aprovechando la combinación de BPROC y Guest Code como mecanismo de extensión.
