README

Paquete open-source para Bagisto 2.5+ (Laravel / PHP 8.4+) diseñado específicamente para el mercado venezolano. Permite al comerciante fijar su catálogo de inventario en Dólares estadounidenses (USD), cumpliendo a la vez con la normativa legal de exhibir y cobrar en Bolívares (VES) a la tasa oficial del Banco Central de Venezuela (BCV) con vigencia por Fecha Valor.

🚀 Características Principales

Scraping Oficial del BCV: Extracción automática de la tasa oficial USD/VES y su correspondiente Fecha Valor desde el portal oficial del BCV.
Seguridad SSL Estricta (Zero Disabling): Resuelve la omisión de la CA intermedia de bcv.org.ve inyectando el certificado público Sectigo DV R36 sin desactivar verify=false.
Lógica de Fecha Valor: Las tasas publicadas por el BCV al final de la tarde (para el siguiente día hábil) se programan sin entrar en vigor prematuramente. Fines de semana y días feriados arrastran automáticamente la última tasa vigente.
Proveedor de Contingencia (Fallback): Si el portal del BCV presenta fallas o bloqueos de red, el sistema recurre automáticamente a DolarApi (ve.dolarapi.com).
Precio Dual en Todo el Frontend: Despliegue simultáneo del precio base y de referencia ($ 24.99 y Bs. 22.222,49 o Bs. 22.222,49 y Ref. $ 24.99) en catálogo, productos configurables, agrupados, mini-carrito, carrito de compras y checkout.
Congelamiento de Tasa por Pedido (bcv_order_rates): Auditoría inmutable de la tasa de cambio vigente en el momento exacto en que se genera la orden, protegiendo la contabilidad y el cálculo de reembolsos posteriores.
Panel de Control en Bagisto Admin:
- Ubicado en Configuración › Tasa Oficial BCV.
- Tarjetas de estado en tiempo real (Tasa Hoy, Tasa Futura Programada, Estado del Cron).
- DataGrid con histórico completo, filtros y badges de estado.
- Modal para registro de Tasa Manual de Respaldo auditada (usuario y motivo).
- Botón de sincronización forzada inmediata.
- Control de acceso granular integrado con Bagisto Bouncer (ACL).
Preparado para Laravel Cloud: Arquitectura stateless (todo el estado y el historial se gestionan en base de datos, sin dependencia de almacenamiento efímero local).

📋 Requisitos del Sistema

PHP: ^8.4 o ^8.5 (con extensiones curl, mbstring, bcmath, intl, pdo_mysql).
Bagisto: ^2.5.0 (Laravel ^13.0 o ^12.0|^11.0).
Base de Datos: MariaDB 10.11+ o MySQL 8.0+.
Zona Horaria de Negocio: America/Caracas (independiente de si el servidor corre en UTC).

📦 Instalación

1. Requerir el paquete vía Composer

composer require wilbere/bagisto-bcv

2. Configurar las monedas en Bagisto

Acceda al panel de administración de Bagisto: Configuración › Monedas.
Asegúrese de tener creada la moneda USD (Dólar estadounidense) y la moneda VES (Bolívar, código VES, símbolo Bs.).
En Configuración › Canales, edite su canal predeterminado:
- Moneda Base: USD.
- Monedas del Canal: active USD y VES.

3. Ejecutar el Asistente de Instalación

php artisan bcv:install

Este comando:

Ejecuta las migraciones de base de datos (bcv_exchange_rate_histories y bcv_order_rates).
Publica el archivo de configuración config/bcv.php.
Sincroniza la primera tasa oficial en vivo desde el BCV.

Si prefiere hacerlo manualmente:

php artisan vendor:publish --tag=bcv
php artisan migrate
php artisan bcv:update-rate --force

⚙️ Configuración

El archivo de configuración se encuentra en config/bcv.php. Puede personalizar variables en su archivo .env:

# Zona horaria comercial de Venezuela
BCV_TIMEZONE=America/Caracas

# Porcentaje máximo de variación tolerada por corrida antes de alertar
BCV_MAX_VARIATION_PERCENT=15.0

# Habilitar el scheduler automático del paquete
BCV_SCHEDULE_ENABLED=true

⚠️ Importante: Desactivar el actualizador nativo de Bagisto

Bagisto incluye un cron genérico para divisas. Para evitar que sobreescriba la tasa del BCV con tasas bancarias extranjeras:

En Bagisto Admin: Configuración › Tipos de cambio › Programar tipos de cambio.
Establezca el campo Frecuencia en Desactivado.

⏰ Programación del Cron (Scheduler)

El paquete programa automáticamente las siguientes tareas bajo la zona horaria America/Caracas:

Hora (Caracas)	Comando	Propósito
17:00 (5:00 PM)	`bcv:update-rate`	Primera consulta tras la publicación de la tasa del día siguiente por el BCV.
20:30 (8:30 PM)	`bcv:update-rate`	Segundo intento de respaldo por retrasos en el portal del BCV.
23:55 (11:55 PM)	`bcv:update-rate`	Último intento nocturno antes del cambio de día.
00:01 (Medianoche)	`bcv:sync-rate`	Sincroniza la tasa programada a la tabla activa de Bagisto (`currency_exchange_rates`).

Idempotencia: Si a las 17:00 ya se obtuvo la tasa para la fecha siguiente, las corridas de las 20:30 y 23:55 finalizan de inmediato sin realizar peticiones innecesarias al portal.

☁️ Despliegue en Laravel Cloud

wilbere/bagisto-bcv está optimizado para entornos de ejecución en contenedores efímeros como Laravel Cloud:

Persistencia 100% en Base de Datos: No se crean archivos de estado locales; los certificados intermedios se resuelven en memoria o desde el directorio del paquete.
Zona Horaria Implícita: Aunque el contenedor de Laravel Cloud se ejecute en UTC, todas las decisiones de negocio y comparaciones de fecha se evalúan bajo America/Caracas.
Scheduler: Asegúrese de activar el daemon Cron / Scheduled Tasks en la configuración del entorno de su aplicación en Laravel Cloud. Laravel ejecutará php artisan schedule:run cada minuto, disparando las tareas del paquete en las horas configuradas.

🛡️ Panel de Administración en Bagisto

Acceda a Configuración › Tasa Oficial BCV:

Tarjeta 1 - Tasa Vigente Hoy: Muestra la tasa en Bolívares que se está aplicando en este momento en el catálogo y checkout.
Tarjeta 2 - Próxima Tasa Programada: Muestra la cotización extraída por el BCV para el siguiente día hábil (Fecha Valor), indicando cuándo entrará en vigor.
Tarjeta 3 - Estado del Cron: Indica horarios de sincronización y fecha del último registro.
Botón "Sincronizar Ahora": Permite forzar una consulta inmediata a los proveedores.
Modal "Tasa Manual de Respaldo": En caso de indisponibilidad prolongada del BCV y APIs externas, un administrador autorizado puede fijar una tasa manual con registro de motivo y autor para fines de auditoría.
DataGrid: Permite buscar, filtrar y exportar el histórico de todas las tasas capturadas.

🧪 Pruebas Automatizadas

El paquete cuenta con una suite completa de pruebas unitarias y de integración desarrolladas con Pest:

# Pruebas unitarias y de integración con simulaciones (35 tests, 85 aserciones)
vendor/bin/pest

# Pruebas de integración en vivo contra los servicios reales del BCV y DolarApi
BCV_LIVE=1 vendor/bin/pest tests/Live

📄 Licencia

Este paquete es software de código abierto bajo la licencia MIT.

wilbere / bagisto-bcv

Package info

Security

Statistics