Gérez le cycle de vie des cartes avec l'API

Créez, mettez à jour, notifiez, désactivez et suivez les cartes Apple Wallet et Google Wallet avec l’API The Wallet Crew.

Gérez le cycle de vie des cartes avec l'API

L'API Wallet Crew gère une carte de la création à la suppression du Wallet. Elle prend en charge les mises à jour de carte, les notifications Wallet et les événements du cycle de vie pour Apple Wallet et Google Wallet.

Utilisez ce guide pour choisir l'action de cycle de vie appropriée. Utilisez le Référence de l'API pour les schémas, les paramètres et les réponses.

Exemples concrets

Un détaillant crée une carte de fidélité à l'aide d'un identifiant client CRM.
Une compagnie aérienne met à jour les informations de porte d'embarquement et envoie une actualisation du Wallet.
Une plateforme d'événements enregistre la suppression du Wallet via Carte:Uninstalled.

Avant de gérer une carte

Les cartes utilisent des identifiants pour relier chaque carte Wallet à des enregistrements externes. Ces identifiants permettent aux connecteurs de récupérer les dernières données sources lors du rendu.

Revue Données de la carte et synchronisation avant de concevoir une intégration. Utilisez Structure pour choisir des clés d'identifiant stables.

Modèle d'état de la carte

Wallet Crew ne dispose d'aucun champ d'état universel pour les cartes. Les données de la carte définissent l'état. Modèles Liquid associent ces données aux champs natifs du Wallet.

Apple Wallet prend en charge ces champs liés à l'état :

voided — un booléen qui marque la carte comme invalide dans le Wallet. Réglez-le sur false pour annuler la modification.
expirationDate — une date ISO 8601 qui définit quand la carte expire.

Google Wallet prend en charge ces champs liés à l'état :

state — l'un des ACTIVE, COMPLETED, EXPIRED, ou INACTIVE.
validTimeInterval — la fenêtre temporelle pendant laquelle la carte reste valide.

Mappez les champs pertinents dans les modèles Apple Wallet et Google Wallet. L'état affiché ne change qu'après un nouveau rendu de la carte.

Wallet Crew ne dispose d'aucun état de suppression logicielle ni d'archivage. L'API ne supprime pas les enregistrements de carte. Pour désactiver une carte, mettez à jour le champ d'état de la plateforme concernée.

Création d'une carte

Créez une carte via l'opération ci-dessous. Fournissez au moins un identifiant externe du système source.

Wallet Crew valide les identifiants via l'une de ces méthodes d'autorisation :

signature HMAC
Secret enregistré
Liste d'autorisation de sécurité
Carte.Write scope

Une carte requiert des données à la création. Wallet Crew récupère les données du connecteur à la demande lors du premier rendu de la carte. Incluez des données qui permettent à un connecteur de localiser l'enregistrement externe.

Create a new pass.

post

/api/{tenantId}/passes

Authorization: Requires Pass.Write scope OR valid identifier validation (HMAC signature, secret, or allowlisted unsigned).

Security: Each identifier must validate via: (1) HMAC (key.hmac), (2) registered secret (key.secret), (3) security allowlist, or (4) Pass.Write scope. Omit identifiers if JWT contains customer claims.

Pass Type: Template to use. Must match file in tenant server/passes/ config.

Use Cases: API-based pass creation; customer self-service with HMAC; bulk imports.

Example — create with HMAC-signed identifier:

POST /api/{tenantId}/passes?passType=loyalty
            
{
  "identifiers": {
    "shopify.customerId": "12345",
    "shopify.customerId.hmac": "{hmac-of-12345}"
  },
  "additionalData": { "loyaltyTier": "silver" }
}

Example — create with Pass.Write scope (no HMAC required):

POST /api/{tenantId}/passes?passType=loyalty
            
{
  "identifiers": { "shopify.customerId": "12345" },
  "additionalData": { "loyaltyTier": "silver" }
}

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Paramètres de requête

passTypestringOptionnel

Type of the pass to create. Must match a file in the tenant server/passes/ configuration.

Corps

Data payload for pass creation operations.

additionalDataobject · nullableOptionnel

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

extensionsobject · nullableOptionnel

Extensibility data related to this pass.

Réponses

200

Pass created successfully.

stringOptionnel

401

Identifiers cannot be validated and caller lacks Pass.Write scope.

post/api/{tenantId}/passes

POST /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "extensions": null,
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null
}

text

La création d'une carte ne récupère pas immédiatement les données du connecteur. La première installation ou le premier rendu déclenche cette récupération.

Mise à jour des données de la carte

Utilisez l'opération ci-dessous pour mettre à jour les données de la carte et demander une actualisation du Wallet. Les champs soumis fusionnent avec les données de carte existantes. Les champs omis restent inchangés. Une valeur vide ou null supprime le champ soumis.

Update a pass and optionally its type.

patch

/api/{tenantId}/passes

Authorization: Requires Pass.Write scope.

Identification: Use internal id (e.g., id=Ed34kg3oA47) or external identifiers with id. prefix (e.g., id.y2.customerId=1233332). Multiple identifiers must match exactly one pass.

Data: Merged with existing data. Empty/null removes fields; omitted fields unchanged.

Metadata: Set options.UpdateMetadata=true for recomputation (slower). Set options.BypassQueue=true for synchronous updates instead of queueing.

Type: Optionally convert pass to different type.

Use Cases: Update identifiers/metadata; push notifications; type conversion; bulk updates; urgent changes.

Example — update by platform pass ID:

PATCH /api/{tenantId}/passes?id=xK9mP2nQr7sT
            
{
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": true }
}

Example — update by external identifier:

PATCH /api/{tenantId}/passes?id.shopify.customerId=12345
            
{
  "identifiers": { "email": "[email protected]" },
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": false }
}

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Paramètres de requête

passTypestringOptionnel

type of the pass to update. type name should be one of the file in the server/passes/ tenant configuration.

Corps

Data payload for single pass update operations.

additionalDataobject · nullableOptionnel

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

passTypestring · nullableOptionnel

Optional pass type to convert the pass to.

updateMetadatabooleanOptionnelObsolète

Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update

Default: false

bypassQueuebooleanOptionnelObsolète

Indicates whether the push update should bypass the queue and run immediately. Queuing helps protect the system load and should only be bypassed when required.

Default: false

Réponses

200

Pass update enqueued or applied successfully.

Aucun contenu

404

No pass found matching the provided identifiers.

patch/api/{tenantId}/passes

PATCH /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null,
  "passType": null,
  "options": {
    "bypassQueue": false,
    "updateMetadata": true,
    "correlationId": null
  }
}

Aucun contenu

Comportement des notifications push

Mises à jour du backend et de l'appareil

Les mises à jour de carte opèrent à deux niveaux indépendants :

Mise à jour du backend — Wallet Crew met à jour l'enregistrement de la carte.
Notification de l'appareil — Wallet Crew notifie les plateformes Wallet lorsque des enregistrements actifs existent.

La mise à jour du backend s'effectue quel que soit l'état d'installation. La livraison sur l'appareil dépend du fait que la carte reste installée.

Notification de l'appareil

Après les mises à jour du backend, Wallet Crew tente de notifier Apple Wallet et Google Wallet. La notification dépend des enregistrements actifs :

Une carte installée peut recevoir une mise à jour via sa plateforme Wallet.
Une carte désinstallée n'a aucun enregistrement actif, donc aucune notification d'appareil n'est envoyée.
Une installation ultérieure reçoit la dernière version de la carte de Wallet Crew.

File d'attente et déduplication

Wallet Crew met les mises à jour en file d'attente par défaut avec bypassQueue : false. La file d'attente protège le débit du système et déduplique le travail. Si une autre mise à jour atteint la même carte avant l'exécution de la tâche en file d'attente, la file d'attente ignore la tâche précédente.

Définissez bypassQueue : true pour les mises à jour synchrones urgentes. Utilisez-le pour des changements tels que les mises à jour du statut d'embarquement qui doivent atteindre le Wallet immédiatement.

Nouveau rendu sur l'appareil

Une notification ne met pas directement à jour une propriété. Lorsqu'un appareil reçoit une notification, son Wallet demande la dernière version de la carte. Wallet Crew récupère des données fraîches du connecteur avant de renvoyer cette version.

Les mises à jour du backend persistent. Cela permet des mises à jour sûres pendant qu'une carte est désinstallée.

Pour les mappages de modèles et les champs de carte, voir Mettre à jour les données de carte dans les modèles.

Envoi d'une notification autonome

Envoyez une notification textuelle sans modifier les données de la carte avec l'opération ci-dessous. La notification apparaît dans l'application Wallet indépendamment d'une mise à jour des données.

Utilisez content pour une chaîne simple. Utilisez localizedContent pour un objet indexé par des codes de langue ISO 639. Utilisez un seul format de contenu par requête.

Send a notification to the pass identified by its pass identifier

put

/api/{tenantId}/passes/{passId}/notification

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

passIdstringRequis

The internal identifier of the pass

tenantIdstringRequis

Corps

contentstring · nullableOptionnel

Could be null if LocalizedContent is specified

localizedContentobject · nullableOptionnel

Localized notification content by language code. Key: ISO 639-1 code or "iso2-region" (e.g., "en", "en-US"). Value: The notification content for that language.

Réponses

200

Aucun contenu

404

Not Found

put/api/{tenantId}/passes/{passId}/notification

PUT /api/{tenantId}/passes/{passId}/notification HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 92

{
  "content": null,
  "localizedContent": null,
  "options": {
    "updateData": false,
    "correlationId": null
  }
}

Aucun contenu

Suppression du Wallet

Lorsqu'un utilisateur final supprime une carte, la plateforme Wallet notifie Wallet Crew. Apple envoie une requête HTTP DELETE à la route d'enregistrement Apple. Google envoie un message avec eventType = "del".

Wallet Crew envoie Carte:Uninstalled lorsque le dernier enregistrement actif atteint zéro. La suppression d'une carte de l'un de deux iPhones n'envoie pas l'événement.

La charge utile du webhook comprend :

passId, passType, identifiants, et métadonnées
appareil et deviceIdentifier — Google définit deviceIdentifier sur null
registrationInformation.activeRegistrationCount et registrationInformation.totalRegistrationCount

Wallet Crew transmet l'événement via le point de terminaison de webhook configuré. La requête comprend X-NEOSTORE-EVENTNAME: Carte:Uninstalled.

La suppression d'une carte d'un Wallet ne supprime pas son enregistrement dans Wallet Crew. La carte peut être réinstallée ultérieurement.

Configurez la livraison du point de terminaison et validez les signatures dans Webhooks.

FAQ

La mise à jour des données de carte modifie-t-elle immédiatement une carte installée ?

Non. La mise à jour crée une nouvelle version de carte et déclenche une actualisation du Wallet. Apple Wallet ou Google Wallet demande alors cette version.

Une carte peut-elle être supprimée via l'API ?

Non. L'API ne supprime pas les enregistrements de carte. Définissez les champs d'état spécifiques à la plateforme pour désactiver une carte.

Pourquoi une mise à jour du Wallet n'a-t-elle pas été distribuée ?

La distribution push nécessite un enregistrement de fournisseur actif. Confirmez que la carte a été installée sur la plateforme Wallet concernée.

Puis-je utiliser les mises à jour échouées pour détecter les cartes désinstallées ?

Non. Les mises à jour n'échouent pas lorsqu'une carte est désinstallée. Wallet Crew traite avec succès la mise à jour du backend. Aucun push vers l'appareil n'est envoyé lorsque la carte n'a aucun enregistrement actif.

Vérifiez l'état d'installation avec le point de terminaison des détails de la carte. Sinon, écoutez les événements Carte:Installed et Carte:Uninstalled.

Mis à jour il y a 17 jours