4.4 KiB
Dominio Integration
Modelo
Integration: catálogo, URL base,integration_data_schemayrequires_configuration.IntegrationInstance: configuración interna concreta con nombre.integration_datase cifra conEncryptedIntegrationData, se almacena enlongTexty nunca se devuelve en la API.ClientIntegrationyWebsiteTypeIntegration: asociaciones a instancias. La clave compuesta verifica el código de la instancia y la unicidad permite una instancia por integración y propietario.
Las instancias no se administran directamente por HTTP. Cada configuración enviada desde un cliente o tipo de sitio crea una instancia interna nueva y reemplaza únicamente la asociación de ese propietario. Al reemplazar o desvincular una instancia, esta se elimina si ya no tiene asociaciones con ningún cliente ni tipo de sitio; las instancias compartidas se conservan mientras tengan al menos una asociación.
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. 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 configuraciones.
| Método | Ruta | Operación |
|---|---|---|
| GET | /clients/{client}/integrations[/{integration_code}] |
Consultar asociaciones directas. |
| PUT | /clients/{client}/integrations/{integration_code} |
Configurar: crea una instancia interna nueva y reemplaza solo la asociación del cliente. Ejecuta el hook de configuración existente. |
| DELETE | /clients/{client}/integrations/{integration_code} |
Desvincular. |
| GET | /website-types/{codigo}/integrations[/{integration_code}] |
Consultar asociaciones del tipo de sitio. |
| PUT | /website-types/{codigo}/integrations/{integration_code} |
Configurar: crea una instancia interna nueva y reemplaza solo la asociación del tipo de sitio. |
| DELETE | /website-types/{codigo}/integrations/{integration_code} |
Desvincular. |
Los dos PUT reciben integration_data, un objeto completo validado según el esquema de la integración. La integración debe existir previamente en el catálogo interno. No hay endpoints públicos para administrar el catálogo ni las instancias directamente.
Las respuestas y consultas incluyen metadatos de integration_instance, pero nunca sus credenciales. La configuración del cliente conserva su mensaje de respuesta histórico; la del tipo de sitio usa un resource con envoltorio data.
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.