Nippy API Platform

Ejemplos de lo que puedes preguntarle a tu agente

“Crea una ruleta de bienvenida: 70% seguir participando, 20% descuento del 10%, 10% unos audífonos”
“¿Qué ruletas tengo activas ahorita?”
“Agrega un premio físico: 50 mochilas Nippy para usar en ruletas”
“Muéstrame la configuración completa de la ruleta de mayo”
“¿Qué items de premio tengo disponibles con stock?”

Con Roulettes armas campañas de gamificación sin tocar la consola. Le dices a tu agente qué premios quieres, con qué probabilidad, y él configura todo. Antes de crear cualquier cosa te muestra un preview para que revises — nada se guarda hasta que tú digas que sí.

Siempre llama list_roulette_items antes de proponer una ruleta, para saber qué items físicos están disponibles con stock.

Tools de lectura

`roulettes_list_roulette_items`

Lista los items de premio físico disponibles para este negocio. Llámala primero antes de proponer cualquier ruleta. Sin parámetros. Respuesta: cada item incluye _id, name, available_stock, y si está enabled_in_rewards. Solo los items con available_stock > 0 y enabled_in_rewards = true deben usarse como premios físicos en una ruleta.

{
  "name": "roulettes_list_roulette_items",
  "arguments": {}
}

`roulettes_get_roulette`

Obtiene la configuración completa de una ruleta por su _id.

string

requerido

ID de la ruleta a consultar.

Respuesta: documento completo incluyendo gifts (con probabilidades, typeOfGift, item_id), typeOfRoulette, timers, términos, isActive y contadores (totalSpins).

{
  "name": "roulettes_get_roulette",
  "arguments": {
    "roulette_id": "664f1a2b3c4d5e6f7a8b9c0d"
  }
}

`roulettes_list_roulettes`

Lista las ruletas existentes de este negocio. Sin parámetros. Respuesta incluye: _id, name, isActive, typeOfRoulette, contadores (totalSpins), createdAt.

{
  "name": "roulettes_list_roulettes",
  "arguments": {}
}

Tools de escritura — Items

`roulettes_propose_item`

Genera un preview de un item de premio físico. No escribe a la base de datos. El country se hereda automáticamente del negocio.

string

requerido

Nombre del item.

integer

requerido

Cantidad de stock disponible para premios.

string

predeterminado:"''"

Descripción del item.

string

predeterminado:"'MXN'"

Moneda (código ISO 4217).

boolean

predeterminado:"true"

Si se debe llevar control de inventario de este item.

boolean

predeterminado:"true"

Si el item está habilitado para ser usado como premio en ruletas.

{
  "name": "roulettes_propose_item",
  "arguments": {
    "name": "Audífonos Bluetooth",
    "available_stock": 50,
    "description": "Audífonos inalámbricos marca Nippy",
    "currency": "MXN",
    "track_stock": true,
    "enabled_in_rewards": true
  }
}

`roulettes_create_item`

Crea un nuevo item de premio físico. Mismos parámetros que propose_item.

Solo llama esta tool después de mostrar al usuario el preview de propose_item y recibir confirmación explícita.

Respuesta: {"_id": "...", "name": "Audífonos Bluetooth", "status": "created"}

Tools de escritura — Ruletas

`roulettes_propose_roulette`

Genera un preview de la configuración de una ruleta. No escribe a la base de datos.

string

requerido

Nombre de la ruleta.

array

requerido

Lista de objetos de premio. Cada gift debe contener:

value (string, requerido): nombre mostrado en la rueda
message (string, requerido): mensaje mostrado al ganar
probability (float, requerido): peso relativo (e.g. 80 = 80% de peso relativo entre todos los gifts)
typeOfGift (object, requerido): {"name": "...", "_id": "..."} — tipo de premio. El agente consulta automáticamente el catálogo de tipos disponibles.
emoji (string, opcional): emoji decorativo
quantity (int, opcional): unidades disponibles. Requerido para premios físicos
item_id (string, opcional): _id de list_roulette_items — solo para premios físicos. No confundir con typeOfGift._id
guaranteedForFirstTimers (bool, opcional)
winInterval (int, opcional)
fallback (string, opcional)

integer

requerido

Tiempo de animación al ganar (segundos).

integer

requerido

Tiempo de animación al perder (segundos).

string

requerido

Texto mostrado cuando el usuario gana.

string

requerido

Texto mostrado cuando el usuario pierde.

string

requerido

Términos y condiciones de la ruleta.

integer

requerido

ID numérico del tipo de ruleta. Consulta nippy://roulettes/schema/gifts para opciones válidas.

string

requerido

Nombre del tipo de ruleta (e.g. "standard", "premium").

boolean

predeterminado:"false"

Si la ruleta se activa inmediatamente. Recomendado: false hasta que el usuario confirme.

string

predeterminado:"'hours'"

Unidad de tiempo para la expiración: "hours", "days". Solo aplica si roulette_type_id lo soporta.

integer

predeterminado:"24"

Tiempo hasta que expira la ruleta, en la unidad de time_unit.

integer

predeterminado:"1"

Número máximo de premios que un usuario puede ganar en esta ruleta.

{
  "name": "roulettes_propose_roulette",
  "arguments": {
    "name": "Ruleta de Bienvenida Mayo 2026",
    "gifts": [
      {
        "value": "Audífonos Bluetooth",
        "message": "¡Ganaste unos Audífonos Bluetooth Nippy!",
        "probability": 10,
        "typeOfGift": {
          "name": "Fisico",
          "_id": "634f356e33e5c76785516a2d"
        },
        "emoji": "🎧",
        "quantity": 50,
        "item_id": "664f1a2b3c4d5e6f7a8b9c0d"
      },
      {
        "value": "10% descuento",
        "message": "¡Obtuviste 10% de descuento en tu próxima compra!",
        "probability": 30,
        "typeOfGift": {
          "name": "Porcentaje",
          "_id": "6342f530705c91dcbe8aba8b"
        },
        "emoji": "💰"
      },
      {
        "value": "Sigue participando",
        "message": "No ganaste esta vez. ¡Intenta de nuevo!",
        "probability": 60,
        "typeOfGift": {
          "name": "Perder",
          "_id": "634f356e33e5c76785516a2c"
        },
        "emoji": "😔"
      }
    ],
    "time_to_win": 5,
    "time_to_lose": 3,
    "text_to_win": "¡Felicidades!",
    "text_to_lose": "Sigue intentando",
    "terms_and_conditions": "Promoción válida del 1 al 31 de mayo de 2026. Aplican restricciones.",
    "roulette_type_id": 1,
    "roulette_type_name": "standard",
    "is_active": false,
    "time_to_expire": 24,
    "max_wins": 1
  }
}

`roulettes_create_roulette`

Crea una nueva ruleta para este negocio. Mismos parámetros que propose_roulette.

Solo llama esta tool después de mostrar al usuario el preview de propose_roulette y recibir confirmación explícita.

Respuesta: {"_id": "...", "name": "Ruleta de Bienvenida Mayo 2026", "status": "created"}

Detalles técnicos (avanzado)

Referencias de esquemas para el agente:

URI	Nombre	Descripción
`nippy://roulettes/schema/gifts`	`roulettes_gift_types`	Catálogo de valores `typeOfGift` y opciones de `typeOfRoulette`
`nippy://roulettes/schema/fields`	`roulettes_field_reference`	Campos de documentos de ruleta e items

IDs del catálogo de typeOfGift:

Tipo	`_id`
Porcentaje	`6342f530705c91dcbe8aba8b`
Perder	`634f356e33e5c76785516a2c`
Points	`68b86722b5a6eee84f241985`

Notas importantes

Los typeOfGift._id deben venir del catálogo oficial — no inventes IDs.
El item_id de un premio físico va en el campo item_id del gift, no en typeOfGift._id.
Siempre incluye al menos un slot de tipo “Perder”.
El country de items y ruletas se hereda automáticamente del negocio.
Mantén is_active: false hasta que el usuario explícitamente pida activar la ruleta.

Inicio

SDK

MCP

Roulettes

Ejemplos de lo que puedes preguntarle a tu agente

Tools de lectura

`roulettes_list_roulette_items`

`roulettes_get_roulette`

`roulettes_list_roulettes`

Tools de escritura — Items

`roulettes_propose_item`

`roulettes_create_item`

Tools de escritura — Ruletas

`roulettes_propose_roulette`

`roulettes_create_roulette`

Notas importantes

​Ejemplos de lo que puedes preguntarle a tu agente

​Tools de lectura

​roulettes_list_roulette_items

​roulettes_get_roulette

​roulettes_list_roulettes

​Tools de escritura — Items

​roulettes_propose_item

​roulettes_create_item

​Tools de escritura — Ruletas

​roulettes_propose_roulette

​roulettes_create_roulette

​Notas importantes

Ejemplos de lo que puedes preguntarle a tu agente

Tools de lectura

`roulettes_list_roulette_items`

`roulettes_get_roulette`

`roulettes_list_roulettes`

Tools de escritura — Items

`roulettes_propose_item`

`roulettes_create_item`

Tools de escritura — Ruletas

`roulettes_propose_roulette`

`roulettes_create_roulette`

Notas importantes