Download the PHP package wilbere/bagisto-bcv without Composer

Bagisto BCV: Motor Multimoneda Dinámico y Tasa Oficial BCV

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

2. Configurar las monedas en Bagisto

1. Acceda al panel de administración de Bagisto: Configuración › Monedas.
2. Asegúrese de tener creada la moneda USD (Dólar estadounidense) y la moneda VES (Bolívar, código VES, símbolo Bs.).
3. 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

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:

⚙️ Configuración

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

⚠️ 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:

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:

1. 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.
2. 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.
3. 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:

📄 Licencia

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