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.
Introducción — Descripción general de la API
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.
https://api.passinstance.com/api/v1https://staging-api.passinstance.com/api/v1Autenticació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.
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxxAuthorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxxx-scanner-key: scan_key_77a8b9c0d1e2f3a4...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.
export PASSINSTANCE_API_KEY="pi_test_..."POST /api/v1/passes con templateId y serialNumber
Extraer response.data.passAccessUrl de la respuesta 201 Created
Enviar URL por SMS/correo; el usuario toca "Añadir a Apple/Google Wallet"
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.
https://passinstance.com/api/docs/openapi.jsonHaga clic en Import en Postman, Insomnia o Bruno y pegue /api/docs/openapi.json para cargar las rutas
Defina baseUrl = https://api.passinstance.com y PASSINSTANCE_API_KEY = pi_test_...
Ejecute GET /api/v1/templates con X-API-Key: para validar su espacio de trabajo
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.
{
"success": true,
"data": { ... },
"errors": [],
"statusCode": 200
}Arquitectura y ciclo de vida del pase
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).
POST /api/v1/templatesDiseño maestro, tipo de código de barras, colores de marca y campos de esquema
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.
Firma criptográfica PKCS#7 mediante certificado Pass Type ID de Apple
Payload REST JWT de cuenta de servicio de Google Cloud
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_PROGRAMLOYALTY_PROGRAM y Niveles
Acumulación de puntos por escaneo (defaultChangeValue) con ascenso automático de nivel
STAMP_CARDSTAMP_CARD_ADD / DEDUCT
Controla posiciones de sellos (0..maximumValue) con onCap ('noop' | 'reset') y rewardClaimBehavior
PREPAID_CARDLibro mayor PREPAID_CARD
Contabilidad de libro mayor prepago en unidades menores ISO 4217 con aplicación de disallowNegativeBalance
VALID_ONCE_PER_DAYVALID_ONCE_PER_DAY y RENEW
Límites diarios por zona horaria y extensión automática de expirationDate al escanear
Centro de ayuda de Passinstance: Explore los 10 temas y 94 guías
Explore guías paso a paso, diagramas de arquitectura de flujos, esquemas de payloads JSON y recursos de solución de problemas en cada dominio.
Todo lo que necesitas para empezar a usar Passinstance con éxito.
Descubre cómo adaptar las tarjetas digitales Wallet a distintos objetivos.
Diseña, emite, organiza y mantén tus pases digitales en Wallet.
Entrega pases a clientes y mantén sus carteras siempre al día.
Configura plataformas Wallet, certificados y funciones NFC.
Valida pases, controla accesos y procesa recompensas de clientes.
Conecta Passinstance con tus sistemas actuales y automatiza flujos.
Supervisa el rendimiento, actividad y adopción de tus pases.
Administra organización, usuarios, suscripción y ajustes fiscales.
Encuentra respuestas, resuelve incidencias y solicita asistencia.
