Skip to content
Guide du centre d'aide · Gestion des passesPhase d'intégration 3
3 min de lectureVérifié 2026-11-16

Consulter & modifier les passes

Recherchez des passes via vues enregistrées et filtres ET/OU, vérifiez les appareils liés et modifiez les données.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé1 / 2
Éléments clés de l'interface

Liste des cartes émises & actions par ligne (Zoom)

Consultez l'onglet Passes pour inspecter les cartes tests, filtrer par statut ou installation et accéder au QR, aperçu, édition ou push.

Aperçu

Ouvrez Passes dans le tableau de bord (dans le répertoire global de l'espace de travail ou directement dans l'onglet Passes d'un modèle) ou interrogez /api/v1/passes pour inspecter, filtrer, auditer, mettre à jour et migrer les cartes émises en temps réel. Chaque modification des champs ou du modèle assigné se synchronise automatiquement vers les appareils Apple Wallet et Google Wallet enregistrés.

Filtres de recherche des passes et télémétrie par ligne
Filtres de recherche des passes et télémétrie par ligne

Architecture système : requêtes, mutations & changement de modèle

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE : RECHERCHE DE PASSES, PATCH & CHANGEMENT DE MODÈLE
ÉTAPE 01 CONSTRUCTEUR DE FILTRES / API REST (/api/v1/passes)
Recherche & filtres : GET/api/v1/passes?templateId=...&status=ACTIVE&...
Mise à jour partielle:PATCH/api/v1/passes/:id
Audit & chronologie : GET/api/v1/passes/:id/history & /timeline
Basculement modèle : POST/api/v1/passes/:id/switch-template/:targetTemplateId
ÉTAPE 02 MOTEUR DE REQUÊTE DATABASE & INDEXATION GIN
Index relationnels sur (customerId, templateId, status, externalId)
Filtrage structured JSON sous la milliseconde via l'index GIN attribute search index
Ajoute les différentiels immuables à pass audit log et à la chronologie Scan
ÉTAPE 03 PROPAGATION PUSH WALLET (WalletPropagationStatus)
Transitionne l'état de propagation : PENDINGQUEUEDSUCCEEDED
Apple Wallet : envoie un push HTTP/2 APNsl'appareil récupère .pkpass
Google Wallet : exécute un PATCH REST sur l'objet cloud walletobjects

1. Rechercher & filtrer des passes (GET /api/v1/passes)

Dans le tableau de bord, ouvrez Filtres pour combiner des groupes de conditions ET / OU entre colonnes système et attributs structured JSON personnalisés, puis enregistrez vos requêtes récurrentes en Vues enregistrées :

  • Identité & clés : serialNumber, externalId, bundleId, idempotencyKey ou id du passe.
  • Cycle de vie & statut : status (pass status), lifecycleStatus (PassLifecycleStatus), walletVoidStatus (WalletPropagationStatus) et disponibilité des artefacts (appleArtifactStatus, googleArtifactStatus).
  • État d'installation Wallet : Installed, Not Installed ou Removed sur les enregistrements Apple Wallet (iOS) et Google Wallet (Android).
  • Fenêtres temporelles : Plages de dates createdAt, updatedAt, expirationDate et lastScannedAt.
  • Attributs structured JSON personnalisés (attribute search index) : Filtres rapides de contenance et comparaison sur toute clé de pass.attributes (par exemple attributes.memberTier = "VIP" ou attributes.pointsBalance >= 1000).
Tiroir de filtres avancés avec constructeur ET/OU
Tiroir de filtres avancés avec constructeur ET/OU

Exemple : Rechercher des passes & consulter par 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 (retourne directement le passe actif non supprimé correspondant à externalId sans nécessiter de stocker nos UUID internes)
En-têtes
X-API-Key <API_KEY>

2. Mettre à jour un passe individuel (PATCH /api/v1/passes/:id)

La mise à jour d'un passe fusionne les nouvelles valeurs dans attributes, ajuste expirationDate ou barcodeValue, et place immédiatement en file une notification push vers tous les appareils où le passe est installé. Si un champ modifié possède un changeMessage contenant %@ sur le modèle, Apple Wallet affiche une bannière native sur l'écran verrouillé.

Requête HTTP

PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

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

Réponse 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. Consulter l'historique d'audit & la chronologie

Passinstance maintient deux flux d'audit complémentaires pour chaque enregistrement :

EndpointPortée & données retournées
GET /api/v1/passes/:id/historyRetourne la chronologie des mutations de champs et d'attributs (previousValue, newValue, changedBy, `source: 'API' \'SCANNER' \'DASHBOARD' \'WORKFLOW', timestamp`).
GET /api/v1/passes/:id/timelineRetourne le flux unifié cycle de vie et engagement, combinant émission, envois e-mail/SMS, installations Apple/Google, validations scanner, variations de solde et notifications push.

Exemple : Récupérer la chronologie d'un passe

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. Migration de modèle en direct (POST /api/v1/passes/:id/switch-template/:targetTemplateId)

Lorsqu'un client accède à un nouveau palier ou change de programme saisonnier, vous pouvez migrer une carte existante vers un autre modèle PUBLISHED sans modifier l'id, le serialNumber, l'authenticationToken ni les enregistrements d'appareils actifs.

POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

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

Important : Pour basculer un passe vers :targetTemplateId de manière transparente sur les appareils Apple Wallet, le modèle source et le modèle cible doivent partager le même passTypeIdentifier Apple (certificat Pass Type ID). Si le modèle cible utilise un autre Pass Type ID, iOS traitera le passe comme une nouvelle carte distincte au lieu de remplacer l'existante sur place.

Pour les transitions d'état et règles d'invalidation, consultez Cycle de vie & statuts des passes. Pour les mises à jour multi-enregistrements, consultez Opérations en masse.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.