shopit-back/app/Domains/Integration/documentacion

Dominio Integration

Modelo

• Integration: catálogo, URL base, integration_data_schema y requires_configuration.
• IntegrationInstance: configuración concreta con nombre. integration_data se cifra con EncryptedIntegrationData, se almacena en longText y nunca se devuelve en la API.
• ClientIntegration y WebsiteTypeIntegration: asociaciones a instancias. La clave compuesta verifica el código de la instancia y la unicidad permite una instancia por integración y propietario.

Editar una instancia compartida afecta a todos sus consumidores. Desvincularla solo elimina la asociación. Las instancias vinculadas no se pueden eliminar (HTTP 409); las instancias sin asociaciones se conservan hasta su eliminación explícita. El código de una integración o instancia no cambia después de crearla.

Resolución

BaseIntegrationService::forTenant() busca primero la asociación del cliente y después la del tipo de sitio del tenant. Selecciona una configuración completa, sin mezclar credenciales entre niveles. Si una configuración está presente pero es inválida, produce un error en vez de recurrir a otra instancia.

forClient() usa únicamente la asociación del cliente: sin un tenant concreto no se elige un tipo de sitio. Si no existe una instancia y requires_configuration es verdadero, se genera un error. Para correo opcional, MailService usa el mailer global si no encuentra una instancia; cuando la encuentra, construye un transporte SMTP aislado identificado como integration-smtp.

Telepagos utiliza una clave de caché basada en el ID de instancia y una huella del texto cifrado. Compartir instancia permite reutilizar el token. Guardar otras credenciales cambia la clave; la edición explícita elimina la anterior después del commit. Volver a configurar el servicio con forClient() o forTenant() carga la configuración actual.

Administración

Todas estas rutas llevan el prefijo /api, requieren auth:sanctum y el rol global admin mediante IntegrationPolicy. Los roles adminapp, scanner y user no administran credenciales compartidas.

Método	Ruta	Operación
CRUD	/integrations	Catálogo.
GET, POST	/integration-instances	Listar con paginación o crear.
GET, PUT, PATCH, DELETE	/integration-instances/{id}	Consultar, editar o eliminar.
GET	/clients/{client}/integrations[/{integration_code}]	Consultar asociaciones directas.
PUT	/clients/{client}/integrations/{integration_code}	Guardado compatible: crea una instancia nueva y reemplaza solo la asociación del cliente. Ejecuta el hook de configuración existente.
PUT	/clients/{client}/integrations/{integration_code}/instance	Asociar una instancia existente.
DELETE	/clients/{client}/integrations/{integration_code}	Desvincular.
GET	/website-types/{codigo}/integrations[/{integration_code}]	Consultar asociaciones del tipo de sitio.
PUT, DELETE	/website-types/{codigo}/integrations/{integration_code}	Asociar una instancia existente o desvincular.

Crear una instancia requiere integration_code, name e integration_data (objeto validado según el esquema del catálogo). Editar solo name conserva las credenciales. Enviar integration_data reemplaza el objeto completo y valida todo el esquema. El código de la instancia es inmutable.

Asociar requiere un payload como {"integration_instance_id": 12}. Se verifica que exista y pertenezca al código solicitado. La creación y edición explícita de instancias validan el esquema sin enviar mensajes ni llamar al proveedor. Para editar una configuración compartida se utiliza explícitamente el endpoint de la instancia.

Los nuevos endpoints usan resources con envoltorio data, sin credenciales. Las consultas históricas de cliente conservan su formato JSON e incluyen integration_instance sin credenciales.

Webhooks y contexto operativo

POST /webhooks/telepagos/{client} conserva su contrato público con el proveedor y la validación de pertenencia de las compras al cliente. Como no recibe un tenant, requiere una asociación directa al cliente. Para usar una instancia compartida en ese flujo, asociarla también al cliente; la herencia por tipo de sitio no se aplica a esa URL.

Notification consume MailService; Purchase consume Telepagos. Los tenants mantienen el contexto operativo y el branding.

Despliegue

Ejecutar php artisan migrate junto con este código. La migración 2026_09_04_000003 renombra requires_client_configuration a requires_configuration conservando sus valores. Los payloads del catálogo deben usar el nuevo nombre. Las migraciones previas trasladan el texto cifrado sin descifrarlo y no comparten instancias automáticamente.

Logging

Telepagos registra eventos en el canal diario telepagos. El nivel y la retención se configuran con TELEPAGOS_LOG_LEVEL y TELEPAGOS_LOG_DAYS. Se eliminan tokens y credenciales de las estructuras registradas.