Skip to content
Referencia de API REST y SDKs

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.

Obtener claves API
Entorno interactivo — los fragmentos se actualizan mientras escribes
Resumen

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.

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.

Claves de producción (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Claves de sandbox (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Claves de escáner hardware
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
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.

Abrir especificación JSON OpenAPI 3.0
1. URL de especificación OpenAPI 3.0
https://passinstance.com/api/docs/openapi.json
2. Importar en Postman / Bruno

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.

200 OK / 201 CreatedÉxito
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Conceptos clave

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).

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
Imágenes Hero / StripApple: 375×123 px (3:1) | Google: 1032×336 px (aprox. 3:1)
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

Documentación integral de Plataforma y API

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.

Abrir el Centro de ayuda

Todo lo que necesitas para empezar a usar Passinstance con éxito.