# Référence de l’API
Tous les services exposés par la plateforme The Wallet Crew sont accessibles via l'API et documentés dans cette référence de l'API.
Les points de terminaison sont regroupés par catégories. Chaque catégorie correspond à un domaine fonctionnel de la plateforme, comme les opérations sur les cartes, les opérations sur le profil client ou l'administration du locataire.
Exemples concrets
* Créer ou mettre à jour des cartes depuis un CRM, une plateforme e-commerce, un système de billetterie ou un point de vente.
* Enregistrer des webhooks pour synchroniser des événements (carte créée, installée, mise à jour) vers une plateforme de données.
* Interroger l'adoption et l'utilisation via l'API Insights (logs, événements, métriques).
* Automatiser les tâches d'administration du locataire (utilisateurs, rôles, permissions) via des appels API.
## Spécification OpenAPI
La définition de l'API The Wallet Crew suit le **Spécification OpenAPI**. La référence de l'API est rendue à partir de cette définition OpenAPI et constitue la source de vérité pour les points de terminaison, les charges utiles, les réponses, les scopes et les valeurs de limitation par défaut.
{% hint style="info" %}
Ajouter des boutons “Open API reference” et “Download OpenAPI spec” nécessite les URL cibles pour l'environnement sélectionné.
{% endhint %}
## Comment la référence de l'API est organisée
La référence de l'API regroupe les points de terminaison par **étiquette**. Dans la documentation The Wallet Crew, chaque étiquette est traitée comme une catégorie d'API.
La liste des catégories peut évoluer avec le temps à mesure que de nouvelles fonctionnalités sont ajoutées. L'intention reste stable : une catégorie équivaut à une capacité produit claire.
## Catégories d'API
Les catégories les plus courantes sont listées ci-dessous.
#### Passes
Points de terminaison utilisés pour créer, lire, mettre à jour et désactiver des passes. Cela inclut les points de terminaison liés à “Add to Wallet” et les vues hébergées utilisées dans les flux de distribution.
Guide connexe : [Comment créer des passes via l'API dans The Wallet Crew](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/develop/guides/wallet/how-to-create-passes-via-api-in-the-wallet-crew).
#### Clients
Points de terminaison utilisés pour créer/mette à jour un profil client, récupérer les données client, et (dans certaines configurations) authentifier les clients pour les appels à portée client.
#### Webhooks
Points de terminaison utilisés pour enregistrer et gérer les abonnements webhook, afin que des systèmes externes puissent recevoir des événements en temps réel de The Wallet Crew.
Guide connexe : [Webhook](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/develop/guides/webhook).
#### Insights
Points de terminaison utilisés pour interroger les données d'utilisation (logs, événements, métriques). Cette API est généralement utilisée pour les rapports, la surveillance et les pipelines d'analyse.
Guide connexe : [API Insights](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/develop/guides/insights-api).
#### Locataire et administration
Points de terminaison utilisés pour gérer la configuration du locataire et le contrôle d'accès, tels que utilisateurs, rôles, permissions, secrets et opérations au niveau système. Ces points de terminaison sont généralement restreints aux identités admin et/ou aux clés API à portée limitée.
#### Utilitaires et contenu
Points de terminaison de support utilisés dans plusieurs fonctionnalités, tels que la génération de codes-barres, la récupération d'actifs publics, le contenu mis en cache ou la vérification d'email. La disponibilité dépend de la configuration du locataire et des modules activés.
## Authentification
Les API The Wallet Crew prennent en charge deux méthodes d'authentification :
#### OAuth 2.0 (jeton Bearer)
OAuth 2.0 est utilisé pour les flux d'authentification basés sur les administrateurs et les utilisateurs. Les appels utilisent l'en-tête HTTP standard :
```http
Authorization: Bearer
```
#### Clé API (`X-API-KEY`)
Les clés API sont l'option la plus simple pour les appels serveur à serveur (backend, middleware d'intégration, tâches planifiées). Les appels utilisent l'en-tête :
```http
X-API-KEY:
```
Les clés API sont générées depuis la console d'administration. Voir [Comment générer une clé API](https://docs.thewalletcrew.io/configure/platform/api-key).
Pour la version intégrée au document du même guide, voir [API Key](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/configure/platform/api-key).
{% hint style="warning" %}
Les clés API sont des secrets. Elles doivent rester côté serveur. Elles ne doivent pas être intégrées dans des applications mobiles ou du code frontend.
{% endhint %}
## Routage par locataire (`tenantId` dans l'URL)
Tous les points de terminaison à portée locataire incluent un `tenantId` paramètre de chemin. C'est ainsi que les requêtes sont routées et isolées par locataire.
Schéma typique :
```http
/api/{tenantId}/...
```
Exemple :
```http
POST /api/{tenantId}/passes?passType={passType}
```
## Limitation et quotas
La limitation API est configurable par point de terminaison et par locataire. Cela protège la plateforme contre les abus et aide à prévenir les effets de voisin bruyant dans un environnement multi-locataire.
Les valeurs de limitation par défaut sont documentées dans la définition de l'API elle-même (OpenAPI). Lorsqu'un locataire utilise des paramètres de limitation personnalisés, la limite effective peut différer de la valeur par défaut documentée.
## Versioning et politique de changement
L'API The Wallet Crew n'utilise pas le versioning dans l'URL (pas de `/v1`, `/v2`, …). L'API est conçue pour rester stable dans le temps.
Lorsqu'un changement incompatible est nécessaire, les marques impactées sont prévenues à l'avance. Cet avis inclut la portée du changement, le calendrier et les étapes d'atténuation.
## FAQ
Quand utiliser OAuth 2.0 vs X-API-KEY?
Les clés API sont généralement le choix par défaut pour les intégrations backend car elles sont faciles à faire tourner et peuvent être restreintes en portée. OAuth 2.0 est typiquement utilisé lorsque les appels sont effectués au nom d'un utilisateur administrateur authentifié ou lorsqu'une session basée sur OAuth existe déjà.
Pourquoi est-ce que tenantId requis dans chaque URL ?
La plateforme est multi-locataire. Le `tenantId` identifie quel locataire possède les données et la configuration utilisées pour traiter la requête. Il applique également l'isolation des locataires.
Y a-t-il une version d'API contre laquelle se verrouiller ?
Non. Il n'y a pas de versioning dans l'URL. La stabilité est gérée par des changements rétrocompatibles lorsque possible, et par une notification directe lorsque des changements incompatibles sont requis.