Documentación para desarrolladores de Passinstance
Cree integraciones de alto volumen con Apple Wallet (.pkpass) y Google Wallet. Emita, actualice, escanee y envíe notificaciones en tiempo real mediante APIs REST de nivel de producción.
La gestión de pases sigue un ciclo de vida de 6 etapas: 1. Plantilla (diseño base) → 2. Pase (registro firmado criptográficamente) → 3. Distribución (passAccessUrl segura) → 4. Registro en Wallet (el dispositivo se registra con APNs / Google Push) → 5. Actualizaciones en vivo (notificaciones en tiempo real) → 6. Telemetría de escaneo y canje (validación y webhooks).
1. PlantillaPOST /api/v1/templates
Diseño maestro, tipo de código de barras, colores de marca y campos de esquema
Conceptos clave
Mecánicas de pases y motor de fidelización
Asocie mecánicas con estado a plantillas en 8 soluciones listas para usar (Fidelización, Tarjetas de sellos, Cupones, Tarjetas regalo/prepago, Entradas, Membresías, Credenciales de empleado, Tarjetas VIP). Las reglas se ejecutan atómicamente al escanear o llamar a la API.
LOYALTY_PROGRAM
LOYALTY_PROGRAM y Niveles
Acumulación de puntos por escaneo (defaultChangeValue) con ascenso automático de nivel
STAMP_CARD
STAMP_CARD_ADD / DEDUCT
Controla posiciones de sellos (0..maximumValue) con onCap ('noop' | 'reset') y rewardClaimBehavior
PREPAID_CARD
Libro mayor PREPAID_CARD
Contabilidad de libro mayor prepago en unidades menores ISO 4217 con aplicación de disallowNegativeBalance
VALID_ONCE_PER_DAY
VALID_ONCE_PER_DAY y RENEW
Límites diarios por zona horaria y extensión automática de expirationDate al escanear
Gestión de pases
11 endpoints
POSThttps://api.passinstance.com/api/v1/passesClave API
Gestión de pases
Emitir un nuevo pase
Cree y emita un nuevo pase de Apple Wallet (.pkpass) y Google Wallet a partir de una plantilla con campos de cliente, código de barras y valores dinámicos.
Encabezados2 obligatorio(s) • 1 opcional(es)
X-API-Keystring
Obligatorio
Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.
Ejemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obligatorio
Debe ser application/json.
Ejemplo: application/json
Parámetros de consulta2 opcional(es)
Carga útil Carga útil de solicitud con ID de plantilla, número de serie único, valores del cliente y configuración opcional de código de barras.
Cuerpo de la solicitud1 obligatorio(s) • 15 opcional(es)
POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idClave API
Gestión de pases
Crear o actualizar pase por ID externo (Upsert)
Cree o actualice de forma idempotente un pase indexado por (customerId, externalId) para una sincronización fluida con CRM, TPV y comercio electrónico.
Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio
Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.
Ejemplo: pi_live_98a7b6c5d4e3f2a1
Carga útil de solicitud con templateId, externalId y atributos dinámicos del pase.
Cuerpo de la solicitud2 obligatorio(s) • 3 opcional(es)
templateIdstring (UUID)
Obligatorio
UUID de la plantilla de destino.
Ejemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Obligatorio
Identificador externo CRM/TPV estable único dentro de su espacio de trabajo.
PATCHhttps://api.passinstance.com/api/v1/passes/{id}Clave API
Gestión de pases
Actualizar pase y enviar push
Actualice campos dinámicos, colores o código de barras del pase y envíe automáticamente notificaciones push APNs y Google Wallet a los dispositivos instalados.
Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio
Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.
POSThttps://api.passinstance.com/api/v1/passes/{id}/useClave API
Gestión de pases
Aplicar acción de mecánica
Ejecute una operación atómica sobre la mecánica del pase: INCREMENT (tarjeta de sellos), DECREMENT, DEBIT (saldo prepago), CREDIT o VALIDATE (cupón de un solo uso).
Encabezados3 obligatorio(s)
X-API-Keystring
Obligatorio
Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.
Ejemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obligatorio
Debe ser application/json.
Ejemplo: application/json
Idempotency-Keystring
Obligatorio
UUID obligatorio para garantizar ejecución atómica y evitar deducciones duplicadas de saldo o sellos.
Resuelva la página pública personalizada de descarga de un pase por slug (GET /d/{slug}/info sin prefijo). Para consultas de gestión autenticadas utilice GET /api/v1/download-pages/slug/{slug}.
Parámetros de ruta1 obligatorio(s)
slugstring
Obligatorio
Slug personalizado único de la página de descarga alojada.
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsClave API
Notificaciones push
Enviar notificación en pantalla de bloqueo
Envíe una notificación push inmediata a un pase instalado de Apple Wallet (.pkpass) o Google Wallet. Para envíos programados o personalización de encabezado, utilice POST /api/v1/push-notifications/passes/{id}.
Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio
Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.
Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idUUID
Obligatorio
UUID único de instancia del pase que recibirá la notificación.
Ejemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
Carga útil de solicitud con el cuerpo del mensaje y título de encabezado opcional.
Cuerpo de la solicitud1 obligatorio(s) • 1 opcional(es)
messagestring
Obligatorio
Mensaje de texto que se mostrará en la pantalla de bloqueo del usuario.
Ejemplo: Your reward points have been updated! You now have 250 points.