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 API de Passinstance permite a los desarrolladores emitir, distribuir, actualizar y validar dinámicamente pases digitales para Apple Wallet (iOS) y Google Wallet (Android). Todas las solicitudes API deben realizarse por HTTPS y devuelven un sobre de respuesta API estandarizado con códigos de estado legibles por máquina.
URL base de Producción
Activo
https://api.passinstance.com/api/v1
URL base de Sandbox Staging
https://staging-api.passinstance.com/api/v1
Formato de solicitud y respuestaapplication/json (UTF-8) con sobre de respuesta estándar
Zona horaria del servidorEurope/Berlin (marcas de tiempo ISO 8601)
Seguridad
Autenticación — Claves API y autorización
Use X-API-Key: <key> o Authorization: ApiKey <key> en los endpoints compatibles con claves API. Bearer se reserva para JWT de acceso. Mantenga las credenciales en el servidor.
Invariante de seguridad:Solo servidor a servidor. Nunca incluya claves secretas en el frontend.
Inicio rápido
Inicio rápido — Primera solicitud API
Cree su primer pase funcional en menos de 5 minutos. Configure el encabezado de su clave API, llame a POST /api/v1/passes con un templateId válido y entregue la passAccessUrl devuelta al usuario final.
Paso 1: Configurar clave
export PASSINSTANCE_API_KEY="pi_test_..."
Paso 2: Emitir pase
POST /api/v1/passes con templateId y serialNumber
Paso 3: Obtener URL
Extraer response.data.passAccessUrl de la respuesta 201 Created
Paso 4: Distribuir
Enviar URL por SMS/correo; el usuario toca "Añadir a Apple/Google Wallet"
Recursos
Colección Postman — Importar y probar solicitudes API
Importe la especificación OpenAPI 3.0 de Passinstance (/api/docs/openapi.json) directamente en Postman, Insomnia o Bruno para probar endpoints, inspeccionar esquemas y generar clientes HTTP tipados.
Haga clic en Import en Postman, Insomnia o Bruno y pegue /api/docs/openapi.json para cargar las rutas
3. Configurar entorno
Defina baseUrl = https://api.passinstance.com y PASSINSTANCE_API_KEY = pi_test_...
4. Verificar conectividad
Ejecute GET /api/v1/templates con X-API-Key: para validar su espacio de trabajo
Operaciones y FAQ
FAQ — Preguntas frecuentes y manejo de errores
Cada respuesta usa el sobre de respuesta API estándar. Corrija los errores 4xx antes de reintentar; espere ante respuestas 5xx y 429 usando el encabezado Retry-After.
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
Guías de plataforma
Matriz Apple Wallet vs. Google Wallet
Passinstance firma automáticamente paquetes .pkpass para iOS y genera objetos JWT firmados para Google Wallet. Los recursos gráficos, códigos de barras y activadores se adaptan sin problemas a ambos sistemas.
Apple WalletiOS · .pkpass
Firma en Apple Wallet
Firma criptográfica PKCS#7 mediante certificado Pass Type ID de Apple
Google WalletAndroid · JWT
Emisor Google Wallet
Payload REST JWT de cuenta de servicio de Google Cloud
Paridad multiplataforma (una sola llamada REST)iOS + Android
Códigos de barras universalesCódigo QR y PDF417 compatibles de forma nativa en ambas plataformas móviles
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 plantillas
7 endpoints
GEThttps://api.passinstance.com/api/v1/templatesClave API
Gestión de plantillas
Listar todas las plantillas
Recupere una lista paginada de plantillas de pases pertenecientes al contexto de cliente autenticado.
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/templates/{id}/publishClave API
Gestión de plantillas
Publicar borrador de plantilla
Promueva una revisión en borrador (rowKind: DRAFT) a PUBLISHED, marque changesToPush: true y encole actualizaciones en segundo plano APNs y Google Wallet para todos los pases activos.
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)
idstring (UUID)
Obligatorio
UUID de la plantilla a publicar.
Ejemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Carga útil de solicitud que controla la publicación inmediata o programada y la propagación push a wallets.
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.
Cada lectura de código de barras o NFC ejecuta una canalización determinista de 14 reglas (estado, vencimiento, franjas horarias, geofencing, mecánicas, límites de tasa, antirrepetición) con nonces criptográficos opcionales y sincronización sin conexión.
Nonce antirrepetición
POST /api/v1/scans/prepare emite un nonce criptográfico antirrepetición efímero vinculado al código de barras
POSThttps://api.passinstance.com/api/v1/scansClave de escáner
Operaciones de escaneo
Procesar escaneo de código de barras / NFC
Valide un código de barras óptico, QR o lectura NFC de Apple VAS / Google Smart Tap desde un terminal o escáner móvil a través del motor de validación de 14 reglas.
Encabezados2 obligatorio(s) • 2 opcional(es)
x-scanner-keystring
Obligatorio
Clave de configuración de escáner aprovisionada en el panel o mediante enlace de emparejamiento.
Ejemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Obligatorio
Debe ser application/json.
Ejemplo: application/json
Carga útil Carga útil de solicitud con el código escaneado, nonce antirrepetición opcional, metadatos de canal/protocolo y contexto de operador.
Cuerpo de la solicitud1 obligatorio(s) • 8 opcional(es)
scannedBarcodeValuestring
Obligatorio
Cadena sin procesar leída desde QR, PDF417, CODE128, AZTEC o lectura NFC.
Verifique X-Webhook-Signature como HMAC-SHA256 sobre el cuerpo original de la solicitud con el secreto de su suscripción. Compare en tiempo constante y procese los eventos de forma idempotente.
Encabezado de firma
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Encabezado de marca temporal
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Protección contra repeticiones
Compruebe que X-Webhook-Id coincide con eventId firmado, elimine eventos duplicados y valide la marca temporal firmada según su política contra repeticiones.
Devuelva HTTP 200 OK en menos de 5.000 ms para confirmar la recepción
Clave pública de verificación
GET /api/v1/webhooks/public-key devuelve la clave pública activa para verificar firmas
POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClave API
Resumen y endpoints
Crear suscripción de webhook
Registre un endpoint HTTPS para recibir notificaciones en tiempo real firmadas con HMAC sobre emisión, actualización, escaneo y desinstalación de pases.
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 la URL HTTPS de destino y matriz de elementos tipos de eventos webhook.
Cuerpo de la solicitud2 obligatorio(s) • 5 opcional(es)
urlstring (HTTPS URL)
Obligatorio
URL de su servidor (debe comenzar por https://, máx. 2048 caracteres).
Cómo funcionan los Pull Webhooks y sus limitaciones
Consuma eventos de pases y escaneos en tiempo real mediante webhooks Push firmados HMAC-SHA256 (con retroceso exponencial y disyuntores) o sondeo Pull Webhook para redes protegidas por firewall, además de flujos sin código.
Resiliencia Push Webhook
5 reintentos con retroceso exponencial con fluctuación; disyuntor abierto tras 10 fallos consecutivos
Sondeo Pull Webhook
GET /api/v1/webhook-payload y POST /api/v1/webhook-payload/acknowledge para redes privadas
GEThttps://api.passinstance.com/api/v1/webhook-payloadClave API
Webhooks basados en Pull
Consultar eventos pull-webhook en cola
Recupere cargas útiles de eventos webhook pendientes mediante HTTPS GET saliente para redes privadas o restringidas por firewall sin abrir puertos entrantes.
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>.