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
Seguridad

Resumen — Cómo funciona la validación de pases

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

Canalización de 14 reglas

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Sincronización offline

GET /api/v1/scans/offline-dataset entrega instantáneas paginadas por cursor para terminales sin conexión

Emparejamiento de clave escáner

POST /api/v1/scanner-keys/from-link intercambia un token de emparejamiento + PIN por una x-scanner-key

Configuración de escáner

3 endpoints
GEThttps://api.passinstance.com/api/v1/validation/configsClave API
Configuración de escáner

Listar configuraciones de escáner

Liste todos los perfiles de configuración de escáner (app móvil, escáner web, TPV) y sus permisos de plantilla en su espacio de trabajo.

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 consulta2 opcional(es)

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Clave API
Configuración de escáner

Obtener configuración de escáner

Obtenga los detalles de una configuración de escáner específica, incluyendo plantillas permitidas, mensaje post-lectura y reglas.

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 configuración de escáner.

Ejemplo: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/validation/configsClave API
Configuración de escáner

Crear configuración de escáner

Cree un nuevo perfil de configuración de escáner con plantillas asignadas, acción de lectura predeterminada y mensaje de confirmación.

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

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Cuerpo de la solicitud2 obligatorio(s) • 2 opcional(es)
namestring
Obligatorio

Nombre descriptivo para la configuración del escáner.

Ejemplo: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Obligatorio

UUID de las plantillas autorizadas para validación bajo este perfil.

Ejemplo: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Códigos de estado de respuesta

Operaciones de escaneo

4 endpoints
GEThttps://api.passinstance.com/api/v1/validation/scansClave API
Operaciones de escaneo

Listar registros de escaneo

Consulte el registro paginado de auditoría de escaneos de pases filtrando por plantilla, pase, escáner, decisión e intervalo de fechas.

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 consulta3 opcional(es)

Códigos de estado de respuesta

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.

Ejemplo: PI-8891-JD-VIP

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/scans/prepareClave de escáner
Operaciones de escaneo

Preparar nonce de escaneo antirrepetición

Emita un nonce criptográfico antirrepetición de corta duración vinculado a un código de barras antes de ejecutar POST /api/v1/scans.

Encabezados1 obligatorio(s)
x-scanner-keystring
Obligatorio

Clave de configuración de escáner aprovisionada en el panel o mediante enlace de emparejamiento.

Ejemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Carga útil de solicitud con el valor del código escaneado al que vincular el nonce criptográfico.

Cuerpo de la solicitud1 obligatorio(s)
scannedBarcodeValuestring
Obligatorio

Cadena de código de barras o token NFC al que vincular el nonce antirrepetición.

Ejemplo: PI-8891-JD-VIP

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetClave de escáner
Operaciones de escaneo

Obtener conjunto de datos offline del escáner

Descargue un conjunto de instantáneas paginadas por cursor restringido a la x-scanner-key invocante para validación local sin conexión.

Encabezados1 obligatorio(s)
x-scanner-keystring
Obligatorio

Clave de configuración de escáner aprovisionada en el panel o mediante enlace de emparejamiento.

Ejemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Parámetros de consulta3 opcional(es)

Códigos de estado de respuesta