Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.nippy.la/llms.txt

Use this file to discover all available pages before exploring further.

Las campañas son el contenedor central de toda la mecánica. Defines los premios disponibles, sus probabilidades, los límites por usuario y cuándo se activan.

​
Crear una campaña

POST https://ms.nippy.la/v1/public/campaigns
x-api-key: npk_live_xxx
x-business-id: tu-business-id
Content-Type: application/json

{
  "name": "Campaña Verano 2026",
  "webhookUrl": "https://tu-app.com/webhooks/nippy",
  "webhookSecret": "un-secret-seguro-min-16-chars",
  "spinsAllowed": 3,
  "cooldownMinutes": 60,
  "gifts": [
    {
      "name": "500 puntos",
      "type": "won_points",
      "pointsValue": 500,
      "probability": 60
    },
    {
      "name": "100 puntos",
      "type": "won_points",
      "pointsValue": 100,
      "probability": 30
    },
    {
      "name": "Perder",
      "type": "lost",
      "probability": 10
    }
  ]
}
Respuesta: 
{
  "campaignId": "camp-abc123",
  "businessId": "tu-business-id",
  "name": "Campaña Verano 2026",
  "status": "active",
  "createdAt": "2026-05-01T00:00:00.000Z"
}

​
Parámetros

​
name
string
requerido
Nombre interno de la campaña. Solo visible en tu consola.
​
webhookUrl
string
requerido
URL de tu backend donde Nippy enviará los eventos. Debe ser HTTPS.
​
webhookSecret
string
requerido
Secret para verificar la firma HMAC-SHA256 de los webhooks. Mínimo 16 caracteres.
​
spinsAllowed
number
predeterminado:"1"
Número máximo de spins por usuario. Usa -1 para ilimitado.
​
cooldownMinutes
number
predeterminado:"0"
Minutos de espera entre spins del mismo usuario. Usa 0 para sin cooldown.
​
gifts
array
requerido
Lista de premios disponibles. Las probabilidades deben sumar exactamente 100.

​
Tipos de premios

TipoDescripciónCampos adicionales
won_pointsAcredita puntos al usuariopointsValue (requerido)
lostNo gana nada — necesario para que las probabilidades sumen 100—
won_digitalPremio digital (código, voucher, etc.)name descriptivo
won_physicalPremio físico con inventario controladoname descriptivo
Las probabilidades de todos los gifts de una campaña deben sumar exactamente 100. Si no suman 100, la creación falla con un error de validación.

​
Crear reglas de activación

Las reglas definen qué evento de negocio dispara una mecánica automáticamente. Cuando el banco llama nippy.track(), el engine evalúa las reglas de la campaña y ejecuta la acción si se cumple la condición. 
POST https://ms.nippy.la/v1/public/campaigns/:campaignId/rules
x-api-key: npk_live_xxx
x-business-id: tu-business-id
Content-Type: application/json

​
Regla: desbloquear spin por compra mayor a $100

{
  "eventType": "card.purchase.completed",
  "condition": {
    "field": "value",
    "operator": "gt",
    "value": 100
  },
  "action": "unlock_spin"
}

​
Regla: acreditar puntos por compra mayor a $500

{
  "eventType": "card.purchase.completed",
  "condition": {
    "field": "value",
    "operator": "gte",
    "value": 500
  },
  "action": "grant_points",
  "pointsValue": 200
}

​
Operadores de condición disponibles

OperadorSignificado
gtMayor que
gteMayor o igual que
ltMenor que
lteMenor o igual que
eqIgual a

​
Acciones disponibles

AcciónDescripción
unlock_spinDispara un spin automático para el usuario. El resultado llega vía webhook spin.completed.
grant_pointsAcredita puntos directamente sin girar. Requiere el campo pointsValue.

​
Listar campañas

GET https://ms.nippy.la/v1/public/campaigns
x-api-key: npk_live_xxx
x-business-id: tu-business-id

[
  {
    "campaignId": "camp-abc123",
    "name": "Campaña Verano 2026",
    "status": "active",
    "totalSpins": 1420,
    "totalWins": 987,
    "startsAt": null,
    "endsAt": null
  }
]