Quioscos y escáneres

Dispositivos sin caja: un escáner en la entrada, una tablet donde los clientes se registran, un escáner de mostrador que entrega recompensas.

Da a cada dispositivo su propia clave con solo el permiso devices:write. Puede escanear tarjetas, registrar visitas, inscribir clientes y entregar recompensas, pero no puede listar socios ni enviar tickets. Si roban la tablet, revocas solo esa clave.

Escanea lo que sea

Envía a POST /v1/scans exactamente lo que produjo el escáner. Nosotros nos encargamos de los distintos formatos: un número de tarjeta, el QR de una tarjeta, un Code 128 con el prefijo de simbología ]C1, un Enter o Tab al final de un escáner que emula teclado, un enlace a la página de la tarjeta o un teléfono tecleado en un quiosco.

curl

curl https://loyaltyfy.io/api/v1/scans \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "]C14285324286429\r", "device_id": "door-1" }'

Respuesta · 200

{
  "object": "scan",
  "matched": true,
  "matched_by": "4285324286429",
  "device_id": "door-1",
  "mechanic": "stamps",
  "member": {
    "object": "member",
    "card_number": "4285324286429",
    "first_name": "Ana",
    "stamps": { "current": 1, "required": 5, "rewards_available": 0 },
    ...
  },
  "actions": [
    { "type": "visit", "method": "POST", "path": "/v1/visits" },
    { "type": "transaction", "method": "POST", "path": "/v1/transactions" }
  ]
}

actions enumera lo que este dispositivo puede hacer a continuación con este cliente, para que la pantalla muestre los botones correctos sin conocer las reglas del programa. Cuando el cliente tiene una recompensa pendiente, aparece una acción redeem_reward con la ruta a la que llamar.

JSON

"actions": [
  { "type": "visit", "method": "POST", "path": "/v1/visits" },
  { "type": "transaction", "method": "POST", "path": "/v1/transactions" },
  {
    "type": "redeem_reward",
    "method": "POST",
    "path": "/v1/members/4285324286429/rewards/redeem",
    "available": 1
  }
]

Sella una visita sin ticket

En los programas de sellos y de visitas basta con registrar la llegada: la puerta de un gimnasio, una estación de lavado, una barra de café sin caja. POST /v1/visits otorga la recompensa por visita del programa. Envía un external_id único por cada registro (por ejemplo, el nombre del dispositivo más un contador); las repeticiones se ignoran.

curl

curl https://loyaltyfy.io/api/v1/visits \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "door-1-2026-10-06-0042",
    "member": "4285324286429",
    "device_id": "door-1"
  }'

Respuesta · 201

{
  "object": "visit",
  "id": "feb2ad75-ac7b-4bb6-8b64-192323b7f6ea",
  "external_id": "door-1-2026-10-06-0042",
  "status": "completed",
  "amount": 0,
  "stamps_earned": 1,
  "reward_unlocked": false,
  "register_id": "door-1",
  "livemode": false,
  "created_at": "2026-10-06T18:17:28.209+00:00",
  "member": {
    "object": "member",
    "card_number": "4285324286429",
    "stamps": { "current": 2, "required": 5, "rewards_available": 0 },
    ...
  },
  ...
}

Los programas de cashback se ganan con dinero, no con visitas, así que una visita de un socio de cashback se rechaza con 400 visit_not_supported. Las actions de un escaneo nunca ofrecen visit a esos socios.

Para no sellar dos veces cuando un cliente escanea dos veces seguidas, construye el external_id a partir del socio y una franja horaria, por ejemplo door-1-4285324286429-2026-10-06T18: como mucho, un sello por hora.

Una tablet en la entrada pide el teléfono y el nombre, muestra las condiciones de privacidad y llama a POST /v1/members con consent: true solo después de que el cliente acepte. Luego muestra wallet.apple_url o wallet.google_url como QR: el cliente lo escanea y la tarjeta va directa a su wallet.

curl

curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kiosk-3-0193" \
  -d '{ "phone": "+306912345678", "first_name": "Eleni", "language": "el", "consent": true }'

# show response.wallet.apple_url or google_url as a QR on the kiosk screen

Si el teléfono ya está inscrito, la llamada devuelve el socio existente con 200, así que un cliente que perdió la tarjeta simplemente la recupera.

Quioscos y escáneres

Escanea lo que sea

Sella una visita sin ticket

Quiosco de registro