Concepts clés
Comprenez les concepts fondamentaux de l’API utilisés dans l’ensemble des guides développeur de The Wallet Crew.
Concepts clés
Cette page définit les concepts de la plateforme qui apparaissent dans les guides de l’API The Wallet Crew. C’est le moyen le plus rapide de s’aligner sur le périmètre du tenant, les identifiants de carte, et la différence entre la création de carte et la gestion de carte.
Exemples concrets
Une marque peut exploiter un tenant pour l’Europe et un autre tenant pour l’Amérique du Nord.
Une carte peut contenir à la fois un ID client CRM et un ID de billet comme identifiants externes.
Une intégration peut créer des cartes avec le SDK Cinto, puis les mettre à jour plus tard via l’API.
Tenant
Un tenant est la principale frontière d’isolation dans The Wallet Crew. Les données, la configuration, les identifiants d’accès et l’accès à l’API sont tous limités à un tenant.
En pratique, un tenant représente généralement une marque, une région ou un programme qui doit rester isolé des autres. Une clé émise pour un tenant ne peut pas lire ni modifier les données d’un autre tenant.
Chaque chemin d’API inclut l’identifiant du tenant comme paramètre de chemin.
Utilisez Infrastructure pour le modèle complet de tenant et d’environnement.
Clé d’API
Une clé d’API est un identifiant d’accès limité au tenant, utilisé pour authentifier les appels serveur à serveur.
La clé est envoyée dans l’ X-API-KEY en-tête. Les permissions associées à la clé contrôlent les opérations autorisées. Les permissions manquantes renvoient généralement 401 ou 403 selon l’endpoint et le flux d’autorisation.
Création de Carte vs gestion de carte
The Wallet Crew sépare la création de carte de la gestion de carte.
La création de carte se fait via le SDK Cinto ou via des connecteurs. C’est l’étape qui insère une nouvelle carte dans la plateforme.
L’API est surtout utilisée après cette étape. Les opérations courantes sont forcer un rafraîchissement, enregistrer un scan, envoyer une notification ou lire l’état de la carte.
Si un flux doit repartir de zéro, utilisez le flux d’inscription ou création de carte déclenchée par connecteur guide.
Modèle de Carte
Un modèle de carte définit la manière dont une carte est rendue dans Apple Wallet et Google Wallet. Il contrôle la mise en page, le mapping des champs, les images, les paramètres de code-barres et les valeurs dynamiques affichées.
Les modèles sont configurés dans le back-office avant l’émission ou la mise à jour des cartes. Un modèle ne représente pas une carte. Il représente la définition réutilisable partagée par de nombreuses cartes.
Lorsqu’une carte est actualisée, The Wallet Crew reconstruit l’artefact Wallet à partir des données de la carte, du modèle et des données du fournisseur.
Utilisez Comment une Carte est rendue pour le pipeline de rendu.
ID de Carte
passId est l’identifiant interne d’une carte dans The Wallet Crew.
Il est renvoyé par les opérations de la plateforme qui créent ou résolvent une carte. Certains endpoints utilisent passId pour les opérations directes sur une carte connue, comme l’envoi d’une notification à cette carte.
passId est stable dans The Wallet Crew. Il est utile pour la traçabilité et pour les opérations directes sur la carte.
Identifiants externes
Les identifiants externes relient une carte à des systèmes sources tels qu’un CRM, un moteur de fidélité, une plateforme e-commerce ou un système de billetterie.
Ces identifiants sont souvent le concept d’API le plus important, car ils permettent à The Wallet Crew de retrouver la bonne carte sans copier l’ensemble du dossier métier dans la plateforme. Les exemples typiques sont un ID client CRM, un numéro de fidélité, un ID de commande ou un ID de billet.
Une carte peut contenir plusieurs identifiants externes. C’est courant lorsque la même carte dépend de plus d’un système source.
Utilisez Structure pour le modèle complet des données de la carte.
Métadonnées et données supplémentaires
Les métadonnées et les données supplémentaires sont toutes deux stockées sur la carte, mais elles servent des rôles différents.
Les métadonnées sont utilisées pour la segmentation et le ciblage. Les données supplémentaires servent à enrichir la carte lorsqu’une valeur ne provient pas d’un fournisseur externe.
Cette distinction est importante car les mises à jour, le ciblage et le rendu dépendent du bon modèle de stockage.
FAQ
Un tenant est-il la même chose qu’un environnement ?
Non. Un tenant est un espace de travail client isolé. Un environnement est un stade de la plateforme comme la production ou le QA. Le même client peut avoir un tenant dans plusieurs environnements.
Mis à jour