API de pases de Wallet

Los pases de Wallet (Apple Wallet y Google Wallet) se emiten y gestionan desde el panel y los recorridos de Joryio. Esta API cubre el único paso que ocurre fuera de Joryio: registrar cuándo se escanea o canjea un pase en tu punto de venta.

Ese escaneo alimenta la fase Escaneado del embudo de adopción de Wallet y la tasa de escaneo en Analítica → Analítica de Wallet. Ni Apple ni Google avisan a Joryio cuando se usa un pase en la tienda, por lo que tu TPV (o una integración de middleware) debe enviar el escaneo aquí.

Autenticación

Todas las solicitudes usan una clave de API como token bearer y requieren el permiso wallet:write:

Authorization: Bearer jry_live_xxxxxxxxxxxxxxxxxxxx

Registrar un escaneo o canje de pase

POST /wallet-passes/scan

Campo	Tipo	Notas
serialNumber	string	Obligatorio. El ID único del pase, leído del código de barras o QR impreso en el pase.
properties	object	Opcional. Metadatos libres de canje (tienda, importe, cajero, etc.). Se almacenan tal cual en el evento pass.scanned resultante y están disponibles en analítica.

Ejemplo

TOKEN=jry_live_xxxxxxxxxxxxxxxxxxxx
BASE=https://api-eu1.joryio.com/api

curl -sX POST "$BASE/wallet-passes/scan" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serialNumber": "a1b2c3d4-e5f6-4789-abcd-1234567890ab",
    "properties": { "storeId": "store_42", "amount": 19.90, "currency": "EUR" }
  }'

Respuesta

{ "recorded": true }

recorded es false cuando no existe ningún pase con ese serialNumber en tu organización; en ese caso no se registra nada.

Notas

• Idempotente por pase para analítica. El embudo cuenta pases distintos, por lo que volver a escanear el mismo serialNumber sigue contando como un único pase escaneado. Cada llamada emite su propio evento pass.scanned, de modo que se conservan las properties de cada escaneo.
• Qué es el número de serie. serialNumber es el identificador de pase codificado en el código de barras o QR. Léelo en la caja y envíalo literalmente.
• Dónde aparece. Los escaneos alimentan el flujo de eventos pass.scanned y la fase Escaneado / tasa de escaneo en Analítica de Wallet. La tasa de escaneo se calcula como escaneados / descargados (una base limpia entre plataformas).
• Claves de varios espacios de trabajo. Si tu clave de API abarca varios espacios de trabajo, añade el encabezado X-Workspace-Id: <workspace-id>. Es opcional para una clave de un único espacio de trabajo.