Guide du développeur

Commencez avec les API The Wallet Crew, l’authentification et les principaux parcours d’intégration.

Guide du développeur

Cette section se concentre sur les intégrations API avec The Wallet Crew. Elle couvre l'authentification, la référence API, une première requête et les principaux chemins à suivre ensuite.

Ouvrir la référence API Démarrer le quickstart

Exemples concrets

Créer une Carte de fidélité après l'inscription ou le paiement.
Mettre à jour les champs de la Carte après un événement CRM, billetterie ou POS.
Transmettre les événements du cycle de vie du Wallet vers un backend, un CRM ou une pile d'analyse.

Commencez ici

La plupart des projets développeur suivent le même chemin.

Obtenir des identifiants

Générez une clé API depuis la console d'administration dans Paramètres → Sécurité → Clés API.

Pour la plupart des premières intégrations, la clé API est envoyée dans le X-API-KEY .

Ouvrir la référence de l’API

Utilisez la référence API pour inspecter les points de terminaison, les corps de requête, les schémas de réponse et des exemples en direct.

Ouvrir la référence API

Faire une première requête

Commencez avec une Carte existante. C'est le moyen le plus rapide de valider l'accès au tenant, l'authentification et le comportement de mise à jour sans mêler la logique de création au premier test.

Continuer avec Premiers pas avec l’API.

Étendre l'intégration

Une fois que le premier appel de gestion fonctionne, passez aux flux de création, aux mises à jour, aux webhooks, aux scans et au reporting.

Authentification

Le principal point d'entrée développeur utilise une clé API. Générez la clé depuis la console d'administration, puis envoyez-la dans le X-API-KEY .

Certaines API à portée de tenant peuvent utiliser d'autres modèles d'authentification ou des scopes supplémentaires. Dans ce cas, le guide du point de terminaison ou la référence fait foi.

Pour une première intégration, commencez avec les API documentées autour de X-API-KEY. C'est le chemin habituel pour la gestion des Cartes, les webhooks, les scans et la référence API interactive.

Quickstart

Le flux de validation le plus rapide consiste à commencer avec une Carte déjà existante, à déclencher un appel de gestion, puis à confirmer le résultat sur cette Carte.

L'appel initial le plus courant est une actualisation de Carte :

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

Cela valide la portée du tenant, l'authentification par clé API et le pipeline de mise à jour sur une vraie Carte. Utilisez Premiers pas avec l’API pour la configuration de bout en bout.

S'il n'existe pas encore de Carte, commencez par Flux d'inscription ou Création de Carte déclenchée par un connecteur.

Référence de l’API

Utilisez la référence API lorsque la forme exacte de la charge utile, le schéma de réponse ou le comportement du point de terminaison comptent.

Points d'entrée principaux

Guides du développeur

Ces pages couvrent les principaux modèles d'intégration.

Concepts clés pour la portée du tenant, les identifiants, les modèles et les bases du cycle de vie de la Carte.
Premiers pas avec l’API pour les premiers appels à portée de tenant sur des Cartes déjà existantes.
Flux d'inscription pour la création de Carte pendant des parcours d'inscription hébergés ou personnalisés.
Création de Carte déclenchée par un connecteur pour l'émission pilotée par la source, basée sur les événements en amont.
Mettre à jour les données de Carte dans les modèles pour mettre à jour les données de Carte et les afficher dans les modèles.
Moteur de templates pour la syntaxe DotLiquid prise en charge, les filtres personnalisés et la balise minify .
Webhooks pour la diffusion d'événements en temps réel.
API de scan pour l'ingestion des scans de codes-barres et de QR codes.
API Insights pour les requêtes sur les journaux, les événements et les métriques.
Connecteurs personnalisés pour la logique d'intégration côté tenant.

Étapes suivantes courantes

Une fois la première requête réussie, l'étape suivante dépend généralement de l'objectif de l'intégration.

Si des Cartes existent déjà, commencez par Premiers pas avec l’API.
Si l'émission de Carte démarre dans une inscription, un paiement ou un formulaire hébergé, utilisez Flux d'inscription.
Si l'émission de Carte démarre à partir d'un événement du système source, utilisez Création de Carte déclenchée par un connecteur.
Pour garder le contenu du Wallet à jour, poursuivez avec Mettre à jour les données de Carte dans les modèles.
Pour notifier d'autres systèmes en temps réel, utilisez Webhooks.

FAQ

Comment l'authentification est-elle récupérée ?

Générez une clé API depuis la console d'administration, puis envoyez-la dans X-API-KEY pour les principales API de la plateforme documentées dans le flux de quickstart.

Où se trouve la référence API ?

Utilisez Référence de l’API pour le principal point d'entrée API.

Quel est le meilleur premier appel API ?

Une mise à jour forcée sur une Carte existante est généralement le meilleur premier appel, car elle valide l'accès au tenant, l'authentification et le chemin de mise à jour sans dépendre d'un flux de création.