> For the complete documentation index, see [llms.txt](https://gubo.gitbook.io/gubo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gubo.gitbook.io/gubo-docs/engagement/economy.md).

# Economy Plugin

El plugin de Economía añade un sistema completo de monedas virtuales a tu servidor, con tienda de roles y gestión de balances.

***

## 📑 Contenido

* [Características Principales](#caracteristicas-principales)
* [Sistema de Monedas](#sistema-de-monedas)
* [La Tienda](#la-tienda)
* [Roles Temporales](#roles-temporales)
* [Comandos](#comandos)
* [Integración con Donaciones](#integracion-con-donaciones)
* [Integración con Prioridad de Tickets](#integracion-con-prioridad-de-tickets)
* [Configuración](#configuracion)
* [Casos de Uso](#casos-de-uso)
* [Mejores Prácticas](#mejores-practicas)
* [Solución de Problemas](#solucion-de-problemas)

***

## 🎯 Características Principales

### 💎 Plan Premium (Exclusivo)

⚠️ **El plugin de Economía es exclusivo del Plan Premium**

* ✅ **Sistema de monedas** por usuario
* ✅ **Tienda de roles** permanentes y temporales
* ✅ **Gestión de balances** para administradores
* ✅ **Integración con donaciones** (conversión automática de dinero real)
* ✅ **Prioridad en tickets** según balance
* ✅ **Logging completo** de todas las transacciones
* ✅ **Expiración automática** de roles temporales

***

## 💵 Sistema de Monedas

### ¿Qué son las Coins?

Las **coins** (monedas) son la divisa virtual de tu servidor. Los usuarios las pueden:

* 📥 Recibir de donaciones reales
* 🎁 Recibir de administradores
* 🛒 Gastar en la tienda de roles
* 📊 Usar para prioridad en tickets

### Balance de Usuario

Cada usuario tiene su propio balance individual que se mantiene en tu servidor.

**Ver tu balance:**

```
/balance
```

**Ver el balance de otro usuario:**

```
/balance usuario:@Usuario
```

**Información mostrada:**

* 💰 Cantidad actual de coins
* 🏆 Ranking en el servidor (próximamente)

***

## 🛒 La Tienda

### Tipos de Productos

#### 🎭 Roles Permanentes

**Características:**

* Se asignan para siempre
* El usuario los conserva incluso si se va y vuelve
* No se pueden recomprar (una sola vez)

**Usos comunes:**

* Roles VIP
* Roles de donador
* Roles de nivel/rango
* Acceso a canales exclusivos

***

#### ⏰ Roles Temporales

**Características:**

* Se asignan por un tiempo limitado
* Expiran automáticamente
* Se pueden renovar/extender comprando de nuevo
* El tiempo se acumula si ya tienes el rol

**Usos comunes:**

* Membresías temporales
* Acceso premium por tiempo limitado
* Boost temporal de beneficios
* Eventos especiales

***

### Comprar en la Tienda

**Método 1: Ver la tienda completa**

El administrador publica la tienda con:

```
/shop-publish
```

Esto muestra todos los productos disponibles con botones de compra.

**Método 2: Dashboard** (próximamente)

Podrás ver y comprar desde el dashboard web.

***

### Proceso de Compra

1. **Hacer clic en "Comprar"**
   * Se abre un mensaje de confirmación
   * Muestra precio y detalles del producto
2. **Revisar información**
   * Precio en coins
   * Tipo de rol (permanente/temporal)
   * Duración (si es temporal)
   * Tu balance actual
3. **Confirmar compra**
   * Haz clic en "Confirmar"
   * Si tienes suficientes coins, se completa la compra
   * Si no tienes suficientes, recibes un mensaje de error
4. **Recibir el rol**
   * El rol se asigna automáticamente
   * Recibes un mensaje de confirmación
   * Tu nuevo balance se muestra

***

### Advertencias de Compra

**Ya tienes este rol permanente:**

* ⚠️ No puedes comprar un rol que ya tienes permanentemente
* El botón de compra no funcionará

**Ya tienes este rol temporal:**

* ⚠️ Si compras de nuevo, el tiempo se extiende (no reemplaza)
* Ejemplo: Tienes 2 días restantes, compras 7 días más = 9 días totales

***

## ⏱️ Roles Temporales

### Ver tus Roles Temporales

```
/temp-roles
```

**Información mostrada:**

* 🎭 Nombre del rol
* ⏰ Tiempo restante (días y horas)
* 📅 Fecha de expiración exacta

### Renovar un Rol

Para renovar un rol temporal antes de que expire:

1. Busca el producto en la tienda
2. Cómpralo de nuevo
3. El tiempo se añadirá a tu tiempo restante actual

### Expiración Automática

Cuando un rol temporal expira:

* 🔄 El bot lo remueve automáticamente
* 📢 Recibes una notificación por DM (si está habilitado)
* 📊 Se registra en los logs del servidor

***

## ⚡ Comandos

### Para Usuarios

#### `/balance [usuario]`

Ver el balance de coins.

**Permisos:** Ninguno

**Ejemplos:**

```
/balance
/balance usuario:@Amigo
```

***

#### `/temp-roles`

Ver tus roles temporales activos.

**Permisos:** Ninguno

**Ejemplo:**

```
/temp-roles
```

***

### Para Administradores

#### `/economy-grant usuario cantidad [razón]`

Otorgar o remover coins de un usuario.

**Permisos:** Administrador

**Parámetros:**

* `usuario` (requerido): Usuario a modificar
* `cantidad` (requerido): Coins a añadir o remover
  * Positivo: añade coins
  * Negativo: remueve coins
* `razón` (opcional): Motivo de la transacción

**Ejemplos:**

```
/economy-grant @Usuario 1000 Ganador del evento
/economy-grant @Usuario -500 Penalización por spam
/economy-grant @Usuario 5000 Donación manual
```

***

#### `/shop-publish`

Publicar el catálogo completo de la tienda.

**Permisos:** Gestionar Roles

**Uso:**

```
/shop-publish
```

**Qué hace:**

1. Elimina publicaciones anteriores en el canal
2. Crea un mensaje por cada producto
3. Cada mensaje tiene:
   * Emoji del producto
   * Nombre y descripción
   * Precio en coins
   * Stock disponible (si aplica)
   * Duración (si es temporal)
   * Botón de compra

**Dónde publicar:**

* Crea un canal dedicado (#tienda o #shop)
* Configúralo para que solo el bot pueda enviar mensajes
* Los usuarios solo pueden reaccionar/usar botones

***

## 💸 Integración con Donaciones

### Conversión Automática

Cuando un usuario dona dinero real, se convierte automáticamente a coins según los **exchange rates** configurados.

**Ejemplo de configuración:**

* 1 USD = 100 coins
* 1 EUR = 110 coins
* 1 MXN = 5 coins

**Proceso:**

1. Usuario dona $10 USD vía Stripe/PayPal/MercadoPago
2. El webhook recibe la notificación
3. Se calcula: $10 × 100 = 1000 coins
4. Se añaden 1000 coins al balance del usuario
5. El usuario recibe un DM confirmando

Para más detalles, consulta la [Guía del Plugin de Donaciones](/gubo-docs/engagement/donations.md).

***

## 🎫 Integración con Prioridad de Tickets

### Prioridad por Balance

Los usuarios con más coins pueden recibir prioridad en los tickets de soporte.

**Configuración:**

1. Activa el plugin de [Prioridad de Tickets](/gubo-docs/inicio/readme.md#plugins-y-funcionalidades)
2. Configura un umbral de coins en el dashboard
3. Ejemplo: Usuarios con 1000+ coins = prioridad

**Efecto:**

* Los tickets se marcan como "⭐ PRIORIDAD"
* El staff puede priorizar su atención
* No afecta el orden de cola (solo sugiere)

***

## ⚙️ Configuración

### En el Dashboard

Accede a <https://gubo.com.ar> > Tu Servidor > Economía

#### Configuración General

| Opción                  | Descripción                       | Predeterminado |
| ----------------------- | --------------------------------- | -------------- |
| **Plugin Habilitado**   | Activa el sistema de economía     | Desactivado    |
| **Nombre de la Moneda** | Ej: "coins", "créditos", "puntos" | coins          |
| **Símbolo**             | Emoji para mostrar                | 💰             |
| **Balance Inicial**     | Coins que reciben usuarios nuevos | 0              |

#### Configuración de la Tienda

**Añadir Producto:**

1. Haz clic en "Añadir Producto"
2. Configura:

| Campo           | Descripción                 | Requerido     |
| --------------- | --------------------------- | ------------- |
| **ID Interno**  | Identificador único         | ✅             |
| **Nombre**      | Nombre visible del producto | ✅             |
| **Descripción** | Descripción breve           | ❌             |
| **Precio**      | Costo en coins              | ✅             |
| **Rol**         | Rol de Discord a asignar    | ✅             |
| **Tipo**        | Permanente o Temporal       | ✅             |
| **Duración**    | Horas (si es temporal)      | Solo temporal |
| **Stock**       | Cantidad disponible         | ❌             |
| **Emoji**       | Emoji para la tienda        | ❌             |
| **Habilitado**  | Si se muestra en la tienda  | ✅             |

#### Configuración de Donaciones

| Opción             | Descripción                    |
| ------------------ | ------------------------------ |
| **Exchange Rates** | Tasas de conversión por moneda |
| **Plataformas**    | Stripe, PayPal, Mercado Pago   |

Ver [Guía de Donaciones](/gubo-docs/engagement/donations.md) para detalles completos.

***

## 💡 Casos de Uso

### 1. Servidor de Comunidad Gaming

**Configuración:**

* Nombre: "GG Points"
* Símbolo: 🎮

**Productos:**

* 🌟 Rol VIP (permanente) - 5000 points
* ⚡ Boost Semanal (7 días) - 500 points
* 🎨 Color Personalizado (30 días) - 1000 points

**Obtención:**

* Ganar torneos
* Participación activa (manual)
* Donaciones

***

### 2. Servidor de Creadores de Contenido

**Configuración:**

* Nombre: "Supporter Coins"
* Símbolo: ⭐

**Productos:**

* 💎 Supporter (permanente) - 2000 coins
* 🎥 Early Access (30 días) - 800 coins
* 🎤 Rol Destacado (7 días) - 300 coins

**Obtención:**

* Solo por donaciones reales
* Exchange: $1 = 100 coins

***

### 3. Servidor Educativo

**Configuración:**

* Nombre: "Créditos Académicos"
* Símbolo: 📚

**Productos:**

* 🏆 Estudiante Destacado (permanente) - 10000 créditos
* 📖 Acceso a Recursos (30 días) - 500 créditos
* 💬 Tutorías Prioritarias (7 días) - 200 créditos

**Obtención:**

* Completar tareas/proyectos (otorgado manualmente)
* Participación en eventos
* Ayudar a otros estudiantes

***

### 4. Servidor de Desarrollo/Tech

**Configuración:**

* Nombre: "DevTokens"
* Símbolo: 💻

**Productos:**

* 🚀 Pro Developer (permanente) - 15000 tokens
* 🔧 Beta Tester (30 días) - 2000 tokens
* 🎯 Code Reviewer (14 días) - 1000 tokens

**Obtención:**

* Contribuciones al proyecto
* Reportar bugs
* Ayudar en soporte

***

## ✅ Mejores Prácticas

### Para Administradores

1. **Balancea los precios**
   * Los roles más exclusivos deben costar más
   * Considera el esfuerzo/dinero necesario para obtener coins
   * Prueba y ajusta según feedback
2. **Ofrece variedad**

* Mix de roles permanentes y temporales
  * Diferentes rangos de precio
  * Opciones para todos los presupuestos

3. **Sé transparente**
   * Comunica claramente cómo obtener coins
   * Publica los exchange rates si usas donaciones
   * Explica las diferencias entre roles
4. **Monitorea la economía**
   * Revisa las transacciones regularmente
   * Ajusta precios si hay inflación o deflación
   * Controla que no se abuse del sistema
5. **Actualiza la tienda**

* Añade productos nuevos periódicamente
  * Remueve productos que nadie compra
  * Crea ofertas especiales temporales

### Para Usuarios

1. **Ahorra para lo que quieres**
   * Revisa la tienda antes de gastar
   * Considera roles temporales para probar
   * No gastes todo de inmediato
2. **Entiende los tipos de rol**
   * Permanentes: inversión a largo plazo
   * Temporales: prueba o uso específico
   * Lee las descripciones
3. **Aprovecha las renovaciones**
   * Renueva roles temporales antes de que expiren
   * El tiempo se acumula
4. **Pregunta si tienes dudas**
   * Usa los tickets si no entiendes algo
   * Verifica tu balance regularmente
   * Reporta cualquier problema

***

## 🛠️ Solución de Problemas

### ❌ No puedo comprar un producto

**Posibles causas:**

1. **Balance insuficiente**
   * ✅ No tienes suficientes coins para comprar este producto
   * ✅ Verifica tu balance con `/balance`
   * ✅ Obtén más coins antes de intentar comprar
2. **Ya tienes el rol**
   * ℹ️ No puedes comprar roles permanentes que ya posees
   * ✅ Verifica tus roles actuales en tu perfil
3. **Producto sin stock**
   * ℹ️ El producto agotó su stock configurado
   * ✅ Espera a que un administrador lo reabastezca
4. **Plugin deshabilitado**
   * ✅ Verifica que el plugin de Economía esté activo en el servidor
   * ✅ Contacta a un administrador si no funciona

***

### ❌ No recibí el rol después de comprar

**Soluciones:**

1. **Permisos del bot**
   * ✅ El bot necesita el permiso "Gestionar Roles"
   * ✅ El rol del bot debe estar por encima del rol a asignar en la jerarquía
   * ✅ Contacta a un administrador para verificar los permisos
2. **Rol eliminado**
   * ✅ Verifica que el rol aún exista en el servidor
   * ✅ Contacta a un administrador para que lo reconfigure
3. **Refresco necesario**
   * ✅ Sal y vuelve a entrar al servidor
   * ✅ Reinicia la aplicación de Discord
   * ✅ Si persiste el problema, contacta a un administrador

***

### ❌ Mi rol temporal no expiró

**Soluciones:**

1. **Todavía tiene tiempo**
   * ✅ Verifica el tiempo restante con `/temp-roles`
   * ℹ️ La expiración puede tomar hasta 1 hora después del tiempo indicado
2. **Sistema de expiración detenido**
   * ✅ Contacta al soporte técnico de GUBO
   * ✅ Proporciona detalles del rol y tiempo de expiración esperado

***

### ❌ No puedo publicar la tienda

**Soluciones:**

1. **Permisos insuficientes**
   * ✅ Necesitas el permiso "Gestionar Roles" en el servidor
   * ✅ Pide a un administrador que te otorgue los permisos necesarios
2. **Tienda vacía**
   * ℹ️ No hay productos configurados en el Dashboard
   * ✅ Añade productos en el Dashboard antes de publicar
3. **Permisos del bot en el canal**
   * ✅ El bot necesita permiso de "Enviar Mensajes" en el canal
   * ✅ El bot necesita permiso de "Gestionar Mensajes" en el canal
   * ✅ Verifica los permisos específicos del canal

***

### ❌ Las donaciones no dan coins

**Soluciones:**

1. **Plugin de donaciones desactivado**
   * ✅ Activa el [plugin de donaciones](/gubo-docs/engagement/donations.md) en el Dashboard
   * ✅ Asegúrate de haber guardado los cambios
2. **Exchange rates no configurados**
   * ✅ Configura las tasas de conversión en el Dashboard
   * ✅ Define cuántas coins equivalen a cada moneda (USD, EUR, MXN, etc.)
3. **Webhooks no configurados**
   * ✅ Revisa la [configuración de webhooks](/gubo-docs/engagement/donations.md#configuracion-de-webhooks)
   * ✅ Verifica que las plataformas de pago estén correctamente conectadas

***

## 📊 Comparativa Plan Free vs Premium

| Característica             | Free | Premium 💎 |
| -------------------------- | ---- | ---------- |
| Sistema de monedas         | ❌    | ✅          |
| Tienda de roles            | ❌    | ✅          |
| Roles permanentes          | ❌    | ✅          |
| Roles temporales           | ❌    | ✅          |
| `/balance`                 | ❌    | ✅          |
| `/economy-grant`           | ❌    | ✅          |
| `/shop-publish`            | ❌    | ✅          |
| `/temp-roles`              | ❌    | ✅          |
| Integración con donaciones | ❌    | ✅          |
| Prioridad en tickets       | ❌    | ✅          |
| Logging de transacciones   | ❌    | ✅          |
| Expiración automática      | ❌    | ✅          |

***

## 📞 Soporte

Si tienes problemas con el plugin de Economía:

1. ✅ Revisa esta guía completa
2. ✅ Consulta la sección de [Solución de Problemas](#solucion-de-problemas)
3. ✅ Verifica la configuración en el Dashboard
4. ✅ Confirma que tienes el Plan Premium activo
5. ✅ Contacta al soporte técnico de GUBO

***

**Última actualización:** Enero 2026

**Versión de la guía:** 1.0.0

***