> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/readme/key-concepts.md). # Concepts clés de l’API The Wallet Crew Découvrez les concepts fondamentaux de l’API The Wallet Crew, notamment les locataires, les identifiants de Carte, les identifiants externes, les modèles, les métadonnées et la gestion du cycle de vie des Cartes. ## Concepts clés des clés API de The Wallet Crew Cette page présente les concepts utilisés dans tous les guides de l'API The Wallet Crew. Elle explique le périmètre du tenant, les identifiants de Carte, les modèles, le stockage des données et la différence entre la création de Carte et la gestion de Carte.
Exemples concrets * Une marque peut gérer un tenant pour l'Europe et un tenant pour l'Amérique du Nord. * Une Carte peut contenir à la fois un ID client CRM et un ID de ticket comme identifiants externes. * Une intégration peut créer des Cartes avec le SDK Cinto, puis les mettre à jour plus tard via l'API.
### En un coup d'œil Chaque concept de cette page se rattache à une seule chose : une Carte, rattachée à un tenant. Le schéma montre comment ils se connectent. Lisez-le d'abord, puis utilisez les sections ci-dessous pour le détail de chaque élément. ```mermaid flowchart TB subgraph T["Tenant : frontière d'isolation"] P((Carte)) Tpl["Modèle de Carte
mise en page, champs, code-barres"] Ext["Identifiants externes
ID CRM, numéro de fidélité, ID de ticket"] Pid["passId
identifiant interne"] Meta["Métadonnées et données supplémentaires
segmentation, enrichissement"] P --- Tpl P --- Ext P --- Pid P --- Meta end SDK["SDK Cinto / connecteur"] -- crée --> P API["API avec X-API-KEY"] -- "actualiser, scanner, notifier, lire" --> P ``` ### Tenant Un tenant est la frontière d'isolation dans The Wallet Crew. Les données, la configuration, les identifiants et l'accès à l'API sont rattaché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 en tant que paramètre de chemin. Utilisez [Infrastructure](/developers-guides/fr/pass-architecture/infrastructure.md) pour le modèle complet de tenant et d'environnement. ### Clé API Une clé API est un identifiant rattaché à un tenant, utilisé pour authentifier les appels de serveur à serveur. La clé est envoyée dans le `X-API-KEY` en-tête. Les permissions associées à la clé contrôlent les opérations autorisées. {% hint style="warning" %} Une requête effectuée avec une clé qui n'a pas la permission requise renvoie `401` ou `403`, selon le point de terminaison et le flux d'autorisation. Vérifiez les exigences de permission du point de terminaison dans la référence de l'API. {% endhint %} ### 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 principalement utilisée après cette étape. Les opérations courantes sont de forcer une actualisation, d'enregistrer un scan, d'envoyer une notification ou de lire l'état de la Carte. Si un flux doit partir de zéro, utilisez [Parcours d’inscription](/developers-guides/fr/integration-guides/wallet/enrolment-flows.md) ou [Création de carte déclenchée par le connecteur](/developers-guides/fr/integration-guides/wallet/connector-triggered-pass-creation.md). ### 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 mappage des champs, les images, les paramètres du code-barres et les valeurs dynamiques affichées. Les modèles sont configurés dans le back-office avant que les Cartes ne soient émises ou mises à jour. Un modèle est une 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](/developers-guides/fr/pass-architecture/how-a-pass-is-rendered.md) 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 points de terminaison utilisent `passId` pour des 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 une Carte. ### Identifiants externes Les identifiants externes relient une Carte à des systèmes sources tels qu'un CRM, un moteur de fidélité, une plateforme de commerce électronique ou un système de billetterie. Ces identifiants sont souvent le concept d'API le plus important, car ils permettent à The Wallet Crew de trouver la bonne Carte sans copier l'intégralité 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 ticket. Une Carte peut contenir plusieurs identifiants externes. C'est courant lorsque la même Carte dépend de plusieurs systèmes sources. Utilisez [Structure](/developers-guides/fr/pass-architecture/structure.md) pour le modèle complet de 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 jouent des rôles différents : | Champ | Utilisé pour | | ----------------------- | ------------------------------------------------------------------------- | | Métadonnées | Segmentation et ciblage | | Données supplémentaires | Enrichissement 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 l'assurance qualité. Le même client peut avoir un tenant dans plusieurs environnements.
Les intégrations devraient-elles stocker passId ou des identifiants externes ? Les deux peuvent être utiles. Les identifiants externes constituent généralement le pont naturel avec les systèmes sources. `passId` est utile pour les opérations directes une fois qu'une Carte est connue dans The Wallet Crew.
Une Carte peut-elle utiliser plus d'un identifiant externe ? Oui. C'est une configuration courante lorsque les données proviennent de plusieurs systèmes.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.thewalletcrew.io/developers-guides/fr/readme/key-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.