Descripción general
Abra Pases en el panel (ya sea en el directorio global del espacio de trabajo o dentro de la pestaña Pases de una plantilla concreta) o consulte /api/v1/passes para inspeccionar, filtrar, auditar, actualizar y migrar registros de pases emitidos en tiempo real. Cada modificación en los campos de un pase o en la asignación de plantilla se sincroniza automáticamente con los dispositivos registrados de Apple Wallet y Google Wallet.

Arquitectura del sistema: consulta, mutación y cambio de plantilla
1. Búsqueda y filtrado de pases (GET /api/v1/passes)
En el panel, abra Filtros para combinar Grupos de condiciones AND / OR entre columnas del sistema y atributos structured JSON personalizados, y guarde sus consultas frecuentes como Vistas guardadas:
-
Identidad y claves:
serialNumber,externalId,bundleId,idempotencyKeyoiddel pase. -
Ciclo de vida y estado:
status(pass status),lifecycleStatus(PassLifecycleStatus),walletVoidStatus(WalletPropagationStatus) y disponibilidad de artefactos (appleArtifactStatus,googleArtifactStatus). -
Estado de instalación en el monedero:
Installed,Not InstalledoRemoveden registros de dispositivos Apple Wallet (iOS) y Google Wallet (Android). -
Ventanas temporales: Filtros por rango en
createdAt,updatedAt,expirationDateylastScannedAt. -
Atributos structured JSON personalizados (
attribute search index): Filtros de contención y comparación de alta velocidad frente a cualquier clave dentro depass.attributes(por ejemplo,attributes.memberTier = "VIP"oattributes.pointsBalance >= 1000).

Ejemplo: consultar pases y buscar por External ID
-
GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25 -
GET /api/v1/passes/by-external-id/crm_usr_44910(devuelve directamente el pase activo no eliminado que coincide conexternalIdsin almacenar UUID internos externamente)
2. Actualizar un pase individual (PATCH /api/v1/passes/:id)
Actualizar un pase fusiona los nuevos valores dentro de attributes, ajusta expirationDate o barcodeValue y encola una actualización push inmediata hacia todos los dispositivos donde el pase está instalado. Si un campo modificado tiene configurado en la plantilla un changeMessage con %@, Apple Wallet muestra una alerta nativa en la pantalla de bloqueo.
Solicitud HTTP
PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"attributes": {
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"barcodeAltText": "44910-PLATINUM",
"expirationDate": "2028-12-31 23:59"
}
Respuesta HTTP (200 OK)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"serialNumber": "PI-GOLD-2026-44910",
"externalId": "crm_usr_44910",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"updatedAt": "2026-11-15T17:30:00.000Z"
},
"statusCode": 200
}
3. Auditoría del historial del pase y línea temporal de eventos
Passinstance registra dos flujos de auditoría complementarios para cada registro de pase:
| Endpoint | Alcance y datos devueltos | |||
|---|---|---|---|---|
GET /api/v1/passes/:id/history | Devuelve las mutaciones cronológicas de campos y atributos (previousValue, newValue, changedBy, `source: 'API' \ | 'SCANNER' \ | 'DASHBOARD' \ | 'WORKFLOW', timestamp`). |
GET /api/v1/passes/:id/timeline | Devuelve el flujo unificado de ciclo de vida e interacción, combinando creación del pase, entregas por correo/SMS, instalaciones en Apple/Google, validaciones de escáner, cambios de saldo y notificaciones push. |
Ejemplo: obtener la línea temporal del pase
/api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
{
"success": true,
"data": {
"passId": "pass_01j8k9m2n3p4q5r6",
"events": [
{
"eventId": "evt_03",
"type": "ATTRIBUTE_UPDATED",
"summary": "pointsBalance changed from 500 to 1450",
"actor": "api_key:pi_live_99a8",
"createdAt": "2026-11-15T17:30:00.000Z"
},
{
"eventId": "evt_02",
"type": "WALLET_INSTALLED",
"platform": "APPLE_WALLET",
"deviceLibraryIdentifier": "dlib_8841209a",
"createdAt": "2026-11-15T15:10:05.000Z"
},
{
"eventId": "evt_01",
"type": "PASS_CREATED",
"summary": "Pass issued via REST API",
"createdAt": "2026-11-15T15:04:12.000Z"
}
]
},
"statusCode": 200
}
4. Migración en vivo de plantilla (POST /api/v1/passes/:id/switch-template/:targetTemplateId)
Cuando un cliente asciende a un diseño de nivel superior o cambia entre programas de temporada, puede migrar un pase existente a otra plantilla PUBLISHED sin cambiar su id, serialNumber, authenticationToken ni los registros activos en sus dispositivos.
POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"preserveAttributes": true,
"attributeOverrides": {
"vipLoungeAccess": "Unlimited"
},
"pushUpdateImmediately": true
}
Importante: Para cambiar un pase hacia
:targetTemplateIdsin fricciones en dispositivos Apple Wallet, tanto la plantilla de origen como la de destino deben compartir el mismopassTypeIdentifierde Apple (certificado Pass Type ID). Si la plantilla de destino utiliza un Pass Type ID distinto, iOS la tratará como una tarjeta independiente en lugar de reemplazar visualmente la tarjeta existente.
Para las transiciones de estado y reglas de anulación, consulte Ciclo de vida y estados del pase. Para actualizaciones sobre múltiples registros, consulte Operaciones por lotes.
