Cashless

Dentro del recinto no circula dinero: la pulsera lleva saldo, se recarga y se gasta en las barras. Esta sección cubre cómo consultarlo y, si el organizador te lo autoriza, cómo recargarlo. Permisos: cashless.read para todo lo de lectura, cashless.write para recargar (requiere activación manual).

Todos los importes son enteros en céntimos. 2500 son 25,00 €. La moneda del evento está en GET /event.

Consultar una pulsera

Se direcciona por su código de radio, NFC o UHF, que es lo que tu aplicación tiene tras un escaneo:

curl https://api.ventry.es/v1/wristbands/04A2B1C3D4E580 \
  -H "Authorization: Bearer $VENTRY_KEY"

const wristband = await (
  await fetch("https://api.ventry.es/v1/wristbands/04A2B1C3D4E580", {
    headers: { Authorization: `Bearer ${process.env.VENTRY_KEY}` },
  })
).json();

console.log(wristband.balance);  // en céntimos

wristband = requests.get(
    "https://api.ventry.es/v1/wristbands/04A2B1C3D4E580",
    headers={"Authorization": f"Bearer {os.environ['VENTRY_KEY']}"},
    timeout=10,
).json()

print(wristband["balance"])  # en céntimos

$wristband = callVentry("GET", "/wristbands/04A2B1C3D4E580");

echo $wristband["balance"];  // en céntimos

{
  "object": "wristband",
  "id": "6a3d0712a1e963300ee2cc21",
  "nfc": "04A2B1C3D4E580",
  "uhf": "E28068940000501234567890",
  "status": "active",
  "balance": 4750,
  "promo_balance": 500,
  "attendee": { "name": "Ada Lovelace", "anonymous": false },
  "ticket": { "code": "TR-84213-001", "ticket_type": "Abono VIP" },
  "allowed_zones": [
    { "id": "6a3d2a67a1e963300ee2c99c", "name": "Recinto" },
    { "id": "6a3d2a6ea1e963300ee2c99d", "name": "Zona VIP" }
  ],
  "valid_days": ["6a3d0512...", "6a3d0518..."],
  "created_at": "2026-06-12T17:20:41.882Z",
  "updated_at": "2026-06-12T22:05:13.119Z"
}

Estados posibles:

`status`	Significado
`active`	Operativa
`blocked`	Bloqueada por el organizador
`lost`	Dada por perdida
`released`	Liberada al final del evento
`pending_review`	Doble acreditación sin resolver: no puede gastar

Las pulseras anónimas —las que se venden en el punto de recarga sin entrada asociada— devuelven attendee.name: null y anonymous: true. No tienen un titular identificado, y el nombre interno que llevan es sintético.

Saldo pagado y saldo regalado

Una pulsera lleva dos saldos:

balance: lo que pagó el asistente. Es el único que se le devuelve al final.
promo_balance: lo que le regaló el organizador (cortesías y bonificaciones de recarga). Se gasta en barra igual que el otro, pero no se devuelve nunca.

Lo que puede gastar es la suma de los dos. Si enseñas un saldo al asistente, enseña los dos por separado: «55 €, de ellos 5 € regalados y no reembolsables».

Saldo negativo

balance puede ser negativo. No es un error de tu lado: cuando un terminal cobra sin cobertura y la venta se sincroniza más tarde, la consumición ya se sirvió y VENTRY prefiere registrar el descubierto a descuadrar la caja. El descubierto está acotado por la política del evento.

Consumiciones

curl "https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/transactions?limit=50" \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "transaction",
      "id": "6a3d0911a1e963300ee2ce02",
      "status": "completed",
      "type": "cart",
      "payment_method": "wristband",
      "total": 750,
      "total_base": 682,
      "total_tax": 68,
      "tax_breakdown": [{ "tax_type": "IVA", "rate": 10, "base": 682, "amount": 68 }],
      "items": [
        {
          "product_id": "6a3d2b11a1e963300ee2ca02",
          "name": "Cerveza",
          "quantity": 2,
          "unit_price": 500,
          "charged_amount": 500,
          "included_quantity": 1
        }
      ],
      "wristband_id": "6a3d0712a1e963300ee2cc21",
      "day_id": "6a3d0512...",
      "device_id": "6a3d0620a1e963300ee2cb99",
      "occurred_at": "2026-06-12T21:14:55.301Z",
      "created_at": "2026-06-12T21:15:02.771Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fíjate en la diferencia entre quantity y charged_amount. En el ejemplo se sirvieron dos cervezas de 5,00 €, pero una estaba cubierta por una consumición incluida en el abono VIP (included_quantity: 1), así que sólo se cobraron 5,00 € al saldo. total es siempre lo realmente cobrado, no el valor nominal de lo servido. Si sumas unit_price * quantity para cuadrar caja, te saldrán ingresos que nunca existieron.

Recargas y retiradas

curl "https://api.ventry.es/v1/topups?day=6a3d0512...&direction=topup&limit=200" \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "topup",
      "id": "6a3d0a02a1e963300ee2cf13",
      "direction": "topup",
      "amount": 2000,
      "previous_balance": 2750,
      "new_balance": 4750,
      "payment_method": "card",
      "status": "completed",
      "wristband_id": "6a3d0712a1e963300ee2cc21",
      "day_id": "6a3d0512...",
      "device_id": "6a3d0633a1e963300ee2cba7",
      "occurred_at": "2026-06-12T20:02:19.550Z",
      "created_at": "2026-06-12T20:02:19.812Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

direction: "withdraw" son devoluciones de saldo al asistente. amount es siempre positivo; el sentido lo da direction.

Recargar saldo

Sólo si tienes cashless.write. Pensado para integradores que cobran la recarga en su propia plataforma —una app de recarga online, por ejemplo— y necesitan reflejarla en VENTRY.

curl -X POST https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/topups \
  -H "Authorization: Bearer $VENTRY_KEY" \
  -H "Idempotency-Key: recarga-99312" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2500 }'

// Llamar SÓLO después de que tu pasarela confirme el cobro.
await fetch("https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/topups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENTRY_KEY}`,
    // Derivada del pago, no aleatoria: sobrevive a un reinicio del proceso.
    "Idempotency-Key": `recarga-${payment.id}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 2500 }),  // céntimos
});

# Llamar SÓLO después de que tu pasarela confirme el cobro.
requests.post(
    "https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/topups",
    headers={
        "Authorization": f"Bearer {os.environ['VENTRY_KEY']}",
        # Derivada del pago, no aleatoria: sobrevive a un reinicio del proceso.
        "Idempotency-Key": f"recarga-{payment.id}",
    },
    json={"amount": 2500},  # céntimos
    timeout=30,
)

<?php
// Llamar SÓLO después de que tu pasarela confirme el cobro.
callVentry("POST", "/wristbands/04A2B1C3D4E580/topups", [
    "headers" => [
        // Derivada del pago, no aleatoria: sobrevive a un reinicio del proceso.
        "Idempotency-Key: recarga-{$payment->id}",
        "Content-Type: application/json",
    ],
    "body" => json_encode(["amount" => 2500]),  // céntimos
]);

{
  "object": "topup_result",
  "id": "6a3d0b41a1e963300ee2d022",
  "amount": 2500,
  "previous_balance": 4750,
  "new_balance": 7250,
  "replayed": false
}

Cobra tú primero, recarga después. VENTRY no cobra nada: se limita a añadir saldo. Llama a este endpoint sólo cuando tu pasarela haya confirmado el pago, nunca antes.El movimiento se registra con método de pago online y contra el dispositivo virtual de tu API key, así que aparece en el cierre de caja del evento. El organizador tiene que poder verlo para cuadrar: el dinero lo tienes tú.

Si la pulsera no admite recargas —está en revisión, o liberada— la respuesta es 422 topup_failed.

Bonificaciones de recarga

El organizador puede regalar saldo por recargar: «recarga 50 € y te regalamos 5 €». Las reglas se configuran en el panel, y lo que vale es el escalón más alto alcanzado; si coinciden varias reglas, la que más regala. El regalo va a promo_balance. Para que funcione bien, el asistente tiene que ver el regalo antes de pagar:

Pide el regalo de los importes que ofreces. code (entrada o pulsera) aplica el tope por persona, si la regla lo tiene.

curl "https://api.ventry.es/v1/topup-bonuses/quote?amounts=2000,5000&code=TR-84213-001" \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "topup_bonus_quote",
  "data": [
    {
      "amount": 2000,
      "bonus_amount": 100,
      "rule": { "id": "6a3d4c11a1e963300ee2d101", "name": "Recarga más" },
      "next": { "amount": 5000, "bonus_amount": 500 }
    },
    {
      "amount": 5000,
      "bonus_amount": 500,
      "rule": { "id": "6a3d4c11a1e963300ee2d101", "name": "Recarga más" },
      "next": null
    }
  ]
}

next es el siguiente escalón que mejora el regalo, para animar a recargar más: «añade 30 € y te regalamos 5 €».

Enséñalo junto al importe y cobra.
Al recargar, manda lo que enseñaste y cuándo:
{ "amount": 5000, "bonus_amount": 500, "bonus_rule": "6a3d4c11a1e963300ee2d101", "granted_at": "2026-06-01T10:15:00Z" }
La regla se comprueba en granted_at, así que una recarga pagada antes del evento conserva su regalo aunque la entregues cuando la promoción ya terminó. Se concede como mucho lo que la regla permite para ese importe; la respuesta dice cuánto se dio en bonus_amount y deja el saldo regalado en new_promo_balance.

Si guardas recargas para entregarlas más tarde (por ejemplo, las que se pagan antes del evento y se entregan al acreditarse), pásalas en pending_rules al presupuestar: una entrada por recarga pendiente con regalo. Cuentan para el tope por persona, y así no prometes un regalo que al entregar ya no toque.

GET /topup-bonuses lista las reglas activas del canal online, con sus escalones y fechas, por si quieres anunciarlas.

Conciliación

Para volcar la facturación a tu propio sistema:

curl "https://api.ventry.es/v1/reports/sales-summary?day=6a3d0512..." \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "sales_summary",
  "day_id": "6a3d0512...",
  "currency": "EUR",
  "sales": {
    "count": 4182,
    "total": 3187450,
    "total_tax": 289768,
    "by_method": { "wristband": 2984200, "card": 203250, "cash": 0, "external_card": 0 }
  },
  "topups": {
    "count": 1904,
    "total": 3402000,
    "by_method": { "cash": 1201000, "card": 2151000, "online": 40000, "manual": 10000 }
  },
  "courtesy": { "count": 35, "total": 70000 },
  "withdrawals": { "count": 112, "total": 89400 },
  "unconsumed_balance": 124600
}

Estas cifras salen de la misma función que alimenta el cierre de caja del panel de VENTRY, así que coinciden exactamente con lo que ve el organizador. topups son sólo recargas pagadas. El saldo que regala el organizador (cortesías, bonificaciones) va aparte en courtesy: mueve saldo, pero no es dinero ingresado. En GET /topups, cada recarga lo indica con nature.

Agrupa siempre por occurred_at

Una venta hecha a las 22:00 sin cobertura y sincronizada a las 02:00 lleva occurred_at de las 22:00. Si agrupas por created_at, la facturación de la noche del viernes aparecerá partida entre viernes y sábado.

Solapa la ventana al sincronizar

Por lo mismo: retrocede unas horas respecto a tu última pasada y deduplica por id. Ver Paginación.

unconsumed_balance no es ingreso

Es el saldo que queda en las pulseras sin gastar. Parte se devolverá al asistente y parte no. No lo sumes a las ventas.

Si tu clave está limitada a días concretos

GET /reports/sales-summary sin day responde 422 day_required. Es deliberado: devolverte un total recortado en silencio parecería el total del evento y no lo sería. Pide cada día por separado.

Empezar

Fundamentos

Casos de uso

Próximamente

Consultar una pulsera

Saldo pagado y saldo regalado

Saldo negativo

Consumiciones

Recargas y retiradas

Recargar saldo

Bonificaciones de recarga

Conciliación

​Consultar una pulsera

​Saldo pagado y saldo regalado

​Saldo negativo

​Consumiciones

​Recargas y retiradas

​Recargar saldo

​Bonificaciones de recarga

​Conciliación

Consultar una pulsera

Saldo pagado y saldo regalado

Saldo negativo

Consumiciones

Recargas y retiradas

Recargar saldo

Bonificaciones de recarga

Conciliación