bslsac / messenger-client
Official Laravel client for BSLSAC Messenger API
Requires
- php: ^8.3
- illuminate/config: ^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- phpunit/phpunit: ^11.5
This package is not auto-updated.
Last update: 2026-08-13 16:19:37 UTC
README
Cliente oficial para integración con BSLSAC el Messenger API.
Este paquete encapsula la comunicación con el servicio centralizado Messenger, proporcionando una interfaz simple para enviar notificaciones desde aplicaciones Laravel sin que los sistemas consumidores tengan que implementar lógica de seguridad, construcción de solicitudes HTTP o generación de firmas.
Descripción
BSLSAC Messenger Client fue creado para estandarizar la comunicación entre aplicaciones PHP y el Messenger API de BSLSAC.
El objetivo principal es separar responsabilidades:
- Las aplicaciones consumidoras únicamente definen la notificación que desean enviar.
- El paquete administra la comunicación segura.
- Messenger API administra la autenticación, procesamiento y entrega.
La aplicación consumidora no debe conocer detalles internos del protocolo como:
- generación de timestamps;
- construcción de cadenas de firma;
- generación de HMAC;
- creación de headers de seguridad;
- estructura interna de autenticación.
Características
Actualmente el paquete incluye:
- Cliente HTTP para Messenger API.
- Integración nativa con Laravel mediante Service Provider.
- DTO para construcción de notificaciones.
- Generación automática de timestamps.
- Autenticación mediante HMAC-SHA256.
- Generación automática de firmas digitales.
- Creación automática de headers de seguridad.
- Serialización automática del contenido.
- Configuración mediante variables de entorno independientes.
Requisitos
- PHP >= 8.2
- Laravel >= 10
- Composer
- Extensión OpenSSL habilitada.
Instalación
Instalar mediante Composer:
composer require bslsac/messenger-client
Laravel detectará automáticamente el Service Provider mediante Package Discovery.
Publicación de configuración
Después de instalar el paquete, publicar la configuración:
php artisan vendor:publish --tag=messenger-config
Esto generará:
config/messenger.php
Configuración
El paquete utiliza variables propias para evitar dependencia de configuraciones internas de Laravel.
Agregar al archivo .env:
SAC_MESSENGER_URL=http://localhost/messenger/public
SAC_MESSENGER_KEY=erp_main
SAC_MESSENGER_SECRET=your_secret_key
Variables de entorno
| Variable | Descripción |
|---|---|
| SAC_MESSENGER_URL | URL base del servicio Messenger API |
| SAC_MESSENGER_KEY | Identificador de la aplicación registrada |
| SAC_MESSENGER_SECRET | Secreto utilizado para generar firmas HMAC |
Configuración interna
Archivo:
config/messenger.php
Ejemplo:
return [
'url' => env('SAC_MESSENGER_URL'),
'key' => env('SAC_MESSENGER_KEY'),
'secret' => env('SAC_MESSENGER_SECRET'),
'security' => [
'timestamp_tolerance' => 300,
'signature_ttl' => 300,
],
];
Seguridad
Messenger utiliza autenticación mediante firma HMAC-SHA256.
Cada solicitud enviada al servicio Messenger contiene una firma generada utilizando:
HMAC-SHA256
La firma utiliza:
- secreto privado de la aplicación;
- método HTTP;
- ruta;
- timestamp;
- contenido del request.
Construcción de la firma
La cadena utilizada para generar la firma tiene la siguiente estructura:
METHOD|PATH|TIMESTAMP|BODY
Ejemplo:
POST|api/v1/notifications|1784049124|{"channel":"email","recipient":"test@test.com"}
La firma generada:
HMAC-SHA256(
cadena,
SAC_MESSENGER_SECRET
)
Headers generados
El paquete agrega automáticamente:
X-Application-Key
X-Timestamp
X-Signature
Ejemplo:
X-Application-Key: erp_main
X-Timestamp: 1784049124
X-Signature:
cc2100fe807c06faa900deab7a5fba6c091fc34f67e1b010cb4a0c21b1fb5dcd
Validaciones realizadas por Messenger API
Messenger valida cada solicitud recibida.
Validación de aplicación
Se verifica:
- existencia de la aplicación;
- credencial registrada;
- estado activo;
- fecha de expiración.
Validación de timestamp
Cada solicitud incluye un timestamp Unix.
Messenger valida que la diferencia entre cliente y servidor no exceda el límite permitido.
Esto evita solicitudes antiguas.
Ejemplo:
SAC_MESSENGER_TIMESTAMP
Validación HMAC
Messenger genera nuevamente la firma utilizando el secreto almacenado.
Comparación:
firma_cliente == firma_servidor
Si no coincide:
{
"success": false,
"code": "INVALID_SIGNATURE",
"message": "Invalid request signature."
}
Prevención de Replay Attack
Cada firma utilizada es registrada temporalmente.
Una misma firma no puede utilizarse nuevamente.
El registro contiene:
- aplicación;
- firma;
- timestamp;
- fecha de expiración.
Uso
Ejemplo básico:
use Sac\Messenger\DTO\Notification;
use Sac\Messenger\MessengerManager;
$notification = new Notification(
channel: 'email',
recipient: 'usuario@example.com',
type: 'password_reset',
payload: [
'template' => 1,
'data' => [
'name' => 'Carlos'
]
]
);
$response = app(MessengerManager::class)
->send($notification);
Estructura de una notificación
Ejemplo:
{
"channel": "email",
"recipient": "usuario@example.com",
"type": "password_reset",
"payload": {
"template": 1,
"data": {
"name": "Carlos"
}
}
}
DTO Notification
La notificación representa la información necesaria para Messenger:
| Campo | Descripción |
|---|---|
| channel | Canal de envío. Ejemplo: email |
| recipient | Destinatario |
| type | Tipo de notificación |
| payload | Información adicional del mensaje |
Arquitectura
El paquete sigue una arquitectura donde cada componente tiene una responsabilidad definida.
Aplicación Laravel
|
|
v
Messenger Laravel Client
|
|
v
Messenger API
|
|
v
Servicios de entrega
Responsabilidades
Aplicación consumidora
Responsable de:
- definir la notificación;
- indicar destinatario;
- definir canal;
- enviar datos necesarios.
No debe:
- generar firmas;
- manejar headers;
- construir requests manualmente.
Messenger Laravel Client
Responsable de:
- comunicación HTTP;
- generación de timestamp;
- construcción de firma;
- autenticación;
- serialización.
Messenger API
Responsable de:
- autenticación;
- validación;
- almacenamiento;
- procesamiento;
- entrega.
Manejo de secretos
Los secretos deben almacenarse únicamente mediante variables de entorno.
Ejemplo:
SAC_MESSENGER_SECRET=3d512e4830796cb4903950f5e807749e845abce8f0706146ea2e504a3e78dc54
Los secretos deben generarse utilizando valores aleatorios seguros.
Ejemplo:
bin2hex(random_bytes(32))
No utilizar valores predecibles.
Independencia de APP_KEY
El paquete no utiliza:
APP_KEY
de Laravel para autenticación.
La identidad criptográfica de Messenger es independiente:
SAC_MESSENGER_SECRET
Esto permite:
- cambiar APP_KEY de una aplicación Laravel;
- mantener integraciones existentes;
- separar seguridad del framework y seguridad entre servicios.
Compatibilidad
Diseñado para funcionar con:
- Laravel 10
- Laravel 11
- Laravel 12
- Laravel 13
Roadmap
Próximas mejoras:
- Reintentos configurables.
- Soporte para nuevos canales.
- Versionado estable.
- Mejoras de observabilidad.
- Publicación oficial mediante Composer. s
Versión
0.1.0
Primera versión funcional.
Incluye:
- Cliente HTTP.
- Service Provider.
- DTO Notification.
- Configuración propia.
- Firma HMAC-SHA256.
- Headers de seguridad.
- Comunicación segura con Messenger API.
Licencia
MIT