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,
  "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 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 manual 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.

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 }
  },
  "topups": {
    "count": 1904,
    "total": 3402000,
    "by_method": { "cash": 1201000, "card": 2151000, "manual": 50000 }
  },
  "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.

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 negativo

Consumiciones

Recargas y retiradas

Recargar saldo

Conciliación

​Consultar una pulsera

​Saldo negativo

​Consumiciones

​Recargas y retiradas

​Recargar saldo

​Conciliación

Consultar una pulsera

Saldo negativo

Consumiciones

Recargas y retiradas

Recargar saldo

Conciliación