Skip to content
Guía del Centro de ayuda · Gestión de pasesFase de incorporación 3
3 min de lecturaVerificado 2026-11-16

Consultar y actualizar pases

Busca pases mediante vistas guardadas y filtros Y/O, revisa dispositivos activos y edita atributos.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado1 / 2
Elementos clave de la interfaz

Listado de pases emitidos y acciones (Ampliado)

Abre Passes para revisar pases de prueba, filtrar por ciclo o instalación y usar código QR, ver, editar y notificación push.

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.

Filtros de búsqueda de pases y telemetría por fila
Filtros de búsqueda de pases y telemetría por fila

Arquitectura del sistema: consulta, mutación y cambio de plantilla

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CONSULTA DE PASES, MUTACIÓN PATCH Y CAMBIO DE PLANTILLA
ETAPA 01 CONSTRUCTOR DE FILTROS DEL PANEL / API REST (/api/v1/passes)
Búsqueda y filtro: GET/api/v1/passes?templateId=...&status=ACTIVE&...
Actualiz. parcial: PATCH/api/v1/passes/:id
Auditoría/Timeline:GET/api/v1/passes/:id/history y /timeline
Cambio plantilla: POST/api/v1/passes/:id/switch-template/:targetTemplateId
ETAPA 02 MOTOR DE CONSULTAS DATABASE E ÍNDICE GIN DE ATRIBUTOS
Índices relacionales en (customerId, templateId, status, externalId)
Filtrado structured JSON submilisegundo mediante índice GIN attribute search index
Registra diferencias inmutables de campo en línea temporal pass audit log/Scan
ETAPA 03 PROPAGACIÓN PUSH AL MONEDERO (WalletPropagationStatus)
Transición de estado de propagación: PENDINGQUEUEDSUCCEEDED
Apple Wallet: Envía push despertar APNs HTTP/2dispositivo descarga .pkpass
Google Wallet: Ejecuta PATCH REST sobre recurso walletobjects en la nube

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, idempotencyKey o id del 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 Installed o Removed en registros de dispositivos Apple Wallet (iOS) y Google Wallet (Android).
  • Ventanas temporales: Filtros por rango en createdAt, updatedAt, expirationDate y lastScannedAt.
  • Atributos structured JSON personalizados (attribute search index): Filtros de contención y comparación de alta velocidad frente a cualquier clave dentro de pass.attributes (por ejemplo, attributes.memberTier = "VIP" o attributes.pointsBalance >= 1000).
Panel lateral de filtros avanzados con generador de condiciones AND/OR
Panel lateral de filtros avanzados con generador de condiciones AND/OR

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 con externalId sin almacenar UUID internos externamente)
Cabeceras
X-API-Key <API_KEY>

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

JSON
{
  "attributes": {
    "pointsBalance": 1450,
    "memberTier": "Platinum"
  },
  "barcodeAltText": "44910-PLATINUM",
  "expirationDate": "2028-12-31 23:59"
}

Respuesta HTTP (200 OK)

JSON
{
  "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:

EndpointAlcance y datos devueltos
GET /api/v1/passes/:id/historyDevuelve las mutaciones cronológicas de campos y atributos (previousValue, newValue, changedBy, `source: 'API' \'SCANNER' \'DASHBOARD' \'WORKFLOW', timestamp`).
GET /api/v1/passes/:id/timelineDevuelve 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

GET /api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
JSON
{
  "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

JSON
{
  "preserveAttributes": true,
  "attributeOverrides": {
    "vipLoungeAccess": "Unlimited"
  },
  "pushUpdateImmediately": true
}

Importante: Para cambiar un pase hacia :targetTemplateId sin fricciones en dispositivos Apple Wallet, tanto la plantilla de origen como la de destino deben compartir el mismo passTypeIdentifier de 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.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.