shopit-back/app/Domains/Integration/documentacion/README.md

Dominio Integration

Propósito

Gestiona integraciones externas disponibles y su configuración por cliente. Un cliente puede agrupar múltiples tenants que comparten las mismas credenciales. Incluye correo y pagos mediante Telepagos.

Modelo y seguridad

• Integration: definición global de una integración.
• ClientIntegration: configuración y credenciales de una integración para un cliente.
• EncryptedIntegrationData: cast que protege los datos sensibles persistidos.
• ClientIntegrationService: consulta y configura integraciones del cliente.

Servicios externos

• BaseIntegrationService: resuelve el cliente desde el tenant operativo y carga exclusivamente la configuración del cliente.
• MailService: envío de correo usando la integración configurada.
• TelepagosIntegrationService: autenticación, caché de token, generación de QR y consulta de cobros.
• TelepagosWebhookService: procesa notificaciones recibidas desde Telepagos.

Endpoints

• CRUD global bajo /integrations.
• Consulta y configuración por cliente bajo /clients/{client}/integrations.
• POST /webhooks/telepagos/{client} para notificaciones del proveedor.

Dependencias y reglas

Se integra con Client, Tenant y con el checkout de Purchase. Notification utiliza MailService. El tenant conserva el contexto operativo y de branding, pero nunca es dueño de credenciales. Las credenciales no se exponen en respuestas ni logs; los webhooks deben validar su contrato antes de alterar una compra.