Bonuz — de ventas a lealtad

De clientes a socios · Documentación de instalación, configuración y uso

1) Resumen

TiendaPuntos & CanjesWhatsAppVideoChatFinanzasExcel Import

Bonuz es una solución de e‑commerce con fidelización nativa: registro de clientes, puntos y canjes, niveles (Plata/Oro/Diamante), mensajes por categoría, slot de video en recarga, chat (global y susurros), pedido por WhatsApp y panel de finanzas con filtros y exportación. 100% responsive.

2) Requisitos

  • Servidor: Linux + Apache o Nginx, HTTPS activo.
  • PHP: 8.1+ con extensiones: pdo_mysql, mbstring, openssl, json, curl, zip.
  • DB: MySQL/MariaDB 10+.
  • Límites sugeridos: memory_limit 256M, upload_max_filesize 16M, post_max_size 16M.

3) Estructura del paquete

/install/
  db.sql                # estructura + semillas DEMO (sin datos reales)
/config/
  .env.example          # copia a .env (ver sección 5)
/docs/
  index.html            # esta documentación
/tools/ (opcional)
  hash.php              # genera bcrypt para ADMIN_PASS_HASH (borrar tras usar)
/uploads/
  .htaccess             # sin índices y sin ejecución PHP
config/.htaccess        # deny all
README.md
LICENSE.txt

Si tu dump se llama /script/superca1_demo.sql, puedes mantenerlo, pero se recomienda renombrar a /install/db.sql para simplificar soporte y revisión.

4) Instalación rápida

4.1 Crear base de datos

  1. cPanel → MySQL® Database Wizard → crea DB y usuario → marca ALL PRIVILEGES.

4.2 Importar esquema y demo

  1. cPanel → phpMyAdmin → selecciona tu DB → pestaña Import.
  2. Choose file → selecciona install/db.sql (o script/superca1_demo.sql) → Go.

4.3 Configurar variables (.env)

  1. Copia config/.env.example → renómbralo a config/.env.
  2. Edita las claves de conexión y marca:
DB_HOST=localhost
DB_NAME=tu_db
DB_USER=tu_usuario
DB_PASS=tu_pass

APP_NAME="Bonuz"
CURRENCY_CODE="USD"
LOYALTY_COIN_NAME="Puntos"
LOYALTY_EARN_PER_USD=30
LOYALTY_REDEEM_USD_PER_POINT=1
LOYALTY_LEVELS="Plata:100,Oro:250,Diamante:500"

FX_ENABLED=false
FX_PROVIDER=none

# Genera el hash y pégalo aquí (ver tools/hash.php)
# ADMIN_PASS_HASH=$2y$...

4.4 Generar hash de administrador

  1. Sube /tools/hash.php temporalmente.
  2. Visítalo: https://TU_DOMINIO/tools/hash.php?p=TuClaveSegura → copia resultado $2y$...
  3. Pega en ADMIN_PASS_HASH de tu .env y borra tools/hash.php.

4.5 HTTPS y redirección

  • cPanel → SSL/TLS Status → AutoSSL.
  • cPanel → Domains → Force HTTPS Redirect en tu dominio/subdominio.

5) Configuración (.env)

  • APP_NAME: nombre visible en la cabecera y email.
  • CURRENCY_CODE: USD, EUR, etc. El símbolo se puede mapear en la vista.
  • LOYALTY_EARN_PER_USD: USD gastados por 1 punto (p. ej., 30).
  • LOYALTY_REDEEM_USD_PER_POINT: valor de 1 punto en USD (p. ej., 1).
  • LOYALTY_LEVELS: formato "Plata:100,Oro:250,Diamante:500".
  • FX_ENABLED/FX_PROVIDER: desactiva FX en demo (false/none).
  • ADMIN_PASS_HASH: hash bcrypt generado con tools/hash.php.

6) Seguridad

  • Autenticación con password_hash/password_verify (bcrypt).
  • /config/.htaccess con deny-all (impide leer .env por web).
  • /uploads/.htaccess: sin ejecución de PHP y sin listado de directorios.
  • Forzar HTTPS; no dejes instaladores ni herramientas en producción.
# /config/.htaccess
<IfModule mod_authz_core.c>
  Require all denied
</IfModule>
<IfModule !mod_authz_core.c>
  Deny from all
</IfModule>

# /uploads/.htaccess
Options -Indexes
<FilesMatch "\.(php|php\d+)$">
  Deny from all
</FilesMatch>

Demo pública: usa robots.txt para no indexar:

User-agent: *
Disallow: /

7) Uso del sistema (operativa)

7.1 Productos y categorías

  • Crear/editar productos, stock y visibilidad (disponible/no disponible).
  • Mensajes por categoría: “En oferta”, “Próximamente”, etc.

7.2 Fidelización (puntos, canjes, niveles)

  • Regla por defecto: 1 punto cada 30 USD; 1 punto = 1 USD.
  • Niveles por umbral de puntos: Plata/Oro/Diamante.
  • El admin confirma pagos y canjes; se registran en historial.

7.3 WhatsApp ordering

  • El cliente envía pedido con método de entrega y pago; llega prellenado a WhatsApp.

7.4 Video y anuncios

  • Slot de video en recarga (ideal para promociones o avisos globales).

7.5 Chat

  • Global con opción de “susurro”/privado y subida de archivos (según límites).

7.6 Finanzas

  • Totales, compras procesadas, filtros por día/fecha y exportación.

7.7 Importación por Excel

  • Descarga la plantilla, completa columnas obligatorias y sube el archivo.

8) FAQ / Errores comunes

“Error de conexión a DB” → revisa DB_HOST/DB_NAME/DB_USER/DB_PASS y privilegios.

“No sale candado (HTTPS)” → corre AutoSSL y activa Force HTTPS.

“WhatsApp no abre” → valida teléfono en formato internacional y esquemas https://wa.me/.

“No veo niveles/puntos correctos” → revisa variables de .env y confirma pagos/canjes en admin.

“¿Dónde va la DB?” → no va en carpetas; se importa en phpMyAdmin dentro del servidor MySQL.

9) Actualizaciones

  • Respalda DB y /config/.env.
  • Sube archivos nuevos y ejecuta migraciones si vienen en /install/migrations.
  • Purga cachés de tu hosting si aplica.

10) Soporte

Adsolutions — “Publicidad que mueve un mundo”
Horario: L–V 09:00–18:00 (CLT) · SLA 24 h
Email: Adsolutions@adsolutionsword.com · Web: adsolutionsword.com

11) Licencia y terceros

  • Licencia/EULA: ver LICENSE.txt incluido en el paquete.
  • Librerías de terceros (ejemplos): Bootstrap (MIT), jQuery (MIT), Chart.js (MIT).

12) Changelog

  • 1.0 — 12/09/2025: Versión inicial.