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. Pedidos, pagos y suscripciones de proveedores no forman parte de esta primera implementación.
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.
Diseño pendiente para ecommerce y SaaS
Un conector futuro debe separar ID de evento de ID de pedido/suscripción; validar firma sobre el cuerpo original; vincular secretos a la cuenta; persistir recepción antes de confirmar; deduplicar; tolerar eventos fuera de orden y conciliar con el proveedor. Los errores de mapeo deben quedar en revisión y los transitorios tener reintentos acotados.
Una renovación cobrada actualizaría una suscripción; una renegociación podría crear otro negocio según reglas explícitas. No se deben sumar ambos como dos ingresos del mismo hecho. El consentimiento de comunicaciones debe ser independiente del estado de cliente.
Estos puntos son criterios de diseño, no interfaces disponibles. Shopify, WooCommerce, Stripe, pagos, pedidos y suscripciones no están conectados por esta entrega. Contratos sigue en backlog.
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.