Modelo técnico de Negocios y Clientes 360
Distingue entidades, permisos, trazabilidad y límites del módulo frente a la API pública y futuros conectores.
Esta guía describe el modelo implementado de Negocios y Clientes 360. No añade endpoints al contrato público v1. Las pantallas actuales usan sesión autenticada y protección CSRF; no deben tratarse como una API externa mediante token Bearer.
Entidades y fuentes de verdad
- Contacto: identidad de una persona dentro de la cuenta.
- Organización: identidad empresarial; no es la cuenta cliente de PerformLead.
- Oportunidad: interés y seguimiento operativo asociado a un flujo.
- Negocio: destinatario persona o empresa, flujo, responsable, etapa, moneda, estimación y cierre comercial.
- Relación de cliente: referencia única al tipo e ID de identidad en la cuenta, responsable, clasificación y contexto.
- Tarea de relación: actividad interna pendiente/completada con fecha y resultado.
- Propuesta: versión con fotografía de destinatario y partidas.
Los participantes son vínculos de rol, no destinatarios adicionales a efectos de sumar ventas.
Separación de estados y valores
La clasificación de una relación no reemplaza el estado de un negocio. El cierre comercial tampoco actualiza automáticamente la etapa operativa de una oportunidad. Consultar Clientes 360 no crea tareas duplicadas ni convierte importes históricos.
Las cantidades comerciales usan unidades menores enteras y dos decimales para las monedas soportadas por este módulo. Los totales se separan por moneda; desconocido es distinto de cero. No reutilices esta regla como especificación universal para monedas de un futuro proveedor de pagos.
Autorización y concurrencia
La cuenta se resuelve desde el contexto autorizado; cambiar un ID o el segmento de URL no concede acceso. Se comprueban pertenencia, rol, flujo y responsable según la operación. Asignar una relación abre su identidad al responsable, no los negocios ajenos.
Las escrituras relevantes usan transacciones, bloqueo y revisión de versión. Las altas de negocio y tarea usan claves de creación y validan que un reintento conserve el mismo contenido. Una clave repetida con contenido distinto debe rechazarse, no actualizar otro objeto silenciosamente. Una propuesta conserva su fotografía aunque cambie la identidad.
Los errores de validación o versión se resuelven revisando el estado; no deben entrar en reintentos ilimitados. No interpretes una respuesta de autorización como falta de existencia y crees un duplicado.
Rutas de interfaz, no contrato de integración
Las rutas de navegación relativas a una cuenta son /{cuenta}/administracion/negocios, /{cuenta}/administracion/negocios/configuracion y /{cuenta}/administracion/clientes-360. Requieren sesión y permisos; no pegues cookies de un administrador en integraciones externas ni expongas CSRF como una credencial compartida.
La proyección interna de datos del negocio incluye tipo de destinatario y referencia de contacto cuando corresponde. Es información del módulo autenticado, no una promesa de nuevos recursos en OpenAPI. Para sistemas externos usa únicamente los endpoints y alcances presentes en la referencia pública vigente.
Checklist antes de integrar
- Confirmar recurso disponible y versión del contrato público, sin inferirlo de una pantalla.
- Definir identidad, cuenta, destino y permisos mínimos.
- Distinguir dato recibido, objeto creado y resultado financiero.
- Probar duplicados, conflicto de versión, otro responsable y otra cuenta en un entorno autorizado.
- Comprobar monedas, vacíos, cero y eventos fuera de orden si el adaptador los admite.
- Registrar evidencia sin secretos ni datos personales; acordar conciliación y soporte.
La comprobación de estos módulos no certifica automáticamente cada endpoint histórico ni cada integración de terceros. No se publica aquí ninguna credencial, URL privada de webhook o ficha real.