# Aperçu des API v2 Comprendre le comportement des API dans l'espace de noms v2. L’API Stripe fournit deux espaces de noms qui contiennent plusieurs ensembles d’endpoints : - **API v1:** L’espace de noms `/v1` inclut la plupart des API Stripe existantes. - **API v2 :** l’espace de noms `/v2` comprend des endpoints qui utilisent des modèles de conception `/v2`. ## Différences clés entre les espaces de noms v1 et v2 | | API v1 | API v2 | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Envoyer des données à l’API** | Les requêtes utilisent le codage de formulaire (`application/x-www-form-urlencoded`), tandis que les réponses utilisent le codage JSON (`application/json`). | Les requêtes et les réponses utilisent le codage JSON (`application/json`). | | **Tester votre intégration** | Validez les API dans l’espace de noms `/v1` à l’aide d’environnements de test, qui sont isolés. | Validez les API dans l’espace de noms `/v2` à l’aide d’environnements de test, qui sont isolés. **Lire la suite :** [Environnements de test](https://docs.stripe.com/sandboxes.md) | | **Envoyer des requêtes idempotentes** | Lorsque vous renseignez un identifiant unique dans l’en-tête `Idempotency-Key` et que la requête a été traitée par l’API, elle renverra la dernière requête sauvegardée. | Lorsque vous renseignez un identifiant unique dans l’en-tête`Idempotency-Key`, l’API récupère toutes les requêtes en échec sans engendrer d’effet secondaire (toute modification superflue ou tout comportement observable résultant d’un appel à l’API). **Lire la suite :** [Idempotence](https://docs.stripe.com/api-v2-overview.md#idempotency) | | **Recevoir des événements de Stripe** | La plupart des événements émis depuis les API dans l’espace de noms `/v1` comprennent un aperçu de l’objet API dans leur charge utile. Certaines API dans l’espace de noms `/v1` génèrent des événements légers, qui contiennent une charge utile minimale non versionnée. | Les événements émis par les API dans l’espace de noms `/v2` sont les suivants : [événements légers](https://docs.stripe.com/event-destinations.md#events-overview). **Lire la suite :** [Destinations d’événements](https://docs.stripe.com/event-destinations.md) | | **Faire défiler une liste** | Spécifier l’ID d’un objet comme élément de départ d’une requête à l’API List. Utiliser les propriétés `starting_after`, `ending_before`, et `has_more` de la réponse de l’API pour parcourir une liste. | Spécifiez le token `page` pour les requêtes de liste à l’API. Utilisez les propriétés `previous_page_url` et `next_page_url` de la réponse de l’API afin de faire défiler une liste. **Lire la suite :** [Pagination de liste](https://docs.stripe.com/api-v2-overview.md#list-pagination) | | **Garanties de cohérences des listes** | Les listes principales sont immédiatement cohérentes (avec une haute latence de restitution). Certaines sous-listes deviendront finalement elles aussi cohérentes. | Les listes sont finalement cohérentes par défaut et la latence est plus faible. | | **Obtenir des données supplémentaires** | Utilisez le paramètre `expand` pour remplacer les ID des objets de l’API associé et dont les objets hérités sont entièrement développés. **Lire la suite :** [Développement des réponses](https://docs.stripe.com/expand.md) | Le paramètre `expand` n’est pas pris en charge. Certaines API de cet espace de noms peuvent fournir des champs supplémentaires dans leurs réponses à l’aide du [paramètre include](https://docs.stripe.com/api-includable-response-values.md). | | **Gérer les métadonnées** | Supprimer une paire clé-valeur en définissant la valeur sur une chaîne vide. | Supprimer une paire clé-valeur en définissant la valeur sur `null`. | ## SDK prenant en charge l’API v2 Tout [SDK côté serveur](https://docs.stripe.com/sdks.md#server-side-libraries) prend en charge les API de l’espace de noms { % code %}{ % $constant.values.v2.terms.namespace-v2 %}{ % /code %}. ### Utiliser l’API v2 avec la CLI Stripe Utilisez `stripe trigger` et `stripe listen` pour tester la gestion des événements de votre intégration. Pour accéder aux API dans l’`/v2`espace de noms en utilisant la CLI Stripe, utilisez la commande `stripe v2`. Par exemple, pour lister tous les [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md), vous pouvez utiliser `Stripe v2 core accounts list`. ## Gestion des versions du SDK, de la CLI et de l’API Les SDK et la CLI Stripe incluent automatiquement une version d’API pour chaque requête. Une fois que vous avez mis à jour la version de votre SDK ou de la CLI, Stripe met à jour simultanément la version de l’API de vos requêtes et réponses. #### Inclure la version Stripe sans SDK ou CLI Toutes les requêtes API envoyées à l’espace de noms de l’API `/v2` doivent inclure l’en-tête `Stripe-Version` pour spécifier la version sous-jacente de l’API. Voici un exemple de requête curl utilisant la version `2024-09-30.acacia` de l’API : ```bash curl -G https://api.stripe.com/v2/core/event_destinations \ -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2024-09-30.acacia" \ ``` ## Utiliser les API des espaces de noms v1 et v2 dans la même intégration Vous pouvez utiliser toutes les combinaisons d’API dans l’espace de noms `/v1` ou `/v2` dans la même intégration. #### Java ```java import com.stripe.StripeClient; StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}"); // Call a v2 API EventDestination eventDestination = stripe.v2().core().eventDestinations().retrieve("ed_123"); // Call a v1 API Customer customer = stripe.customers().retrieve("cus_123"); ``` Si vous n’utilisez pas un SDK officiel ni la CLI, renseignez toujours l’espace de noms dans l’URL de vos appels à l’API. Par exemple : ```bash # Call a v2 API curl https://api.stripe.com/v2/core/event_destinations # Call a v1 API curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd ``` ## Défilement de liste API dans l’espace de noms `/v2` (par exemple, `GET /v2/core/event_destinations`) contiennent une interface de pagination différente de celles de l’espace de noms `/v1`. - La propriété `previous_page_url` renvoie une URL permettant de récupérer la page précédente de la liste. S’il n’y a pas de page précédente, la valeur est `null`. - La propriété `next_page_url` envoie une URL permettant de récupérer la page suivante de la liste. S’il n’y a pas de page suivante, la valeur est`null`. Vous pouvez utiliser ces URL pour effectuer des requêtes sans utiliser nos SDK. À l’inverse, lorsque vous utilisez nos SDK, vous n’avez pas besoin d’utiliser ces URL, car les SDK gèrent automatiquement la pagination automatique. Vous ne pouvez pas modifier les filtres de liste après la première requête. #### Java ```java StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}"); EventDestinationListParams params = EventDestinationListParams.builder().build(); for (EventDestination eventDestination : stripe.v2().core().eventDestinations().list(params).autoPagingIterable()) { // process event destination object } ``` ## Utilisation des paramètres de requête dans les requêtes API Utilisez des filtres sur les endpoints de la liste pour limiter les résultats. Utilisez les paramètres [include](https://docs.stripe.com/api-includable-response-values.md) sur les endpoints GET pris en charge pour retourner des champs supplémentaires dans la réponse. Les filtres et les paramètres include permettent de transmettre un tableau de valeurs. Lorsque vous effectuez des requêtes API directes (sans utiliser de SDK côté serveur ou la CLI), vous devez toujours spécifier l’index de la valeur du tableau en notation avec des crochets, même si vous ne transmettez qu’une seule valeur. Par exemple, pour lister tous [Accounts](https://docs.stripe.com/api/v2/core/accounts.md) où la `applied_configuration` est définie sur `merchant`, transférez ce qui suit : ```bash curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.clover" \ ``` Pour lister tous les comptes où la configuration est définie sur `merchant` ou`customer`, utilisez la syntaxe suivante : ```bash curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant&applied_configurations[1]=customer -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.clover" \ ``` Vous pouvez utiliser la même technique pour les paramètres include. Par exemple, pour inclure plusieurs champs dans une réponse, utilisez la syntaxe suivante : ```bash curl -G https://api.stripe.com/v2/core/accounts/:id?include[0]=requirements&include[1]=defaults&include[2]=identity -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.clover" \ ``` Dans certains cas, un tableau est imbriqué dans un paramètre de requête. Par exemple, pour obtenir une liste de méthodes de virement, vous pouvez fournir un tableau de valeurs à filtrer sur le champ imbriqué `usage_status[payments]` : ```bash curl -G https://api.stripe.com/v2/money_management/payout_methods?usage_status[payments][0]=eligible&usage_status[payments][1]=invalid -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2025-12-15.preview" \ ``` ## Idempotence Les API de l’espace de noms `/v2` permettent une meilleure prise en charge des comportements idempotents en empêchant les effets indésirables involontaires lors de l’exécution répétée de requêtes sur la même clé d’idempotence. Lorsque l’API reçoit deux requêtes ayant la même clé d’idempotence : - Si la première requête a abouti, l’API ne procède pas à de nouvelles modifications et renvoie une nouvelle réponse. - Si la première requête a échoué (ou a échoué partiellement), l’API réexécute les requêtes ayant échoué et renvoie la nouvelle réponse. - Lors des rares occasions où une relance idempotente ne peut plus fonctionner, l’API renvoie un message d’erreur explicatif. Une requête est considérée comme une réémission idempotente d’une autre requête si les éléments suivants sont tous vrais : - Elles utilisent la même clé d’idempotence pour la même API - Elles se produisent au sein du même compte ou environnement de test - Elles surviennent à moins de 30 jours d’intervalle Pour spécifier une clé d’idempotence, utilisez l’en-tête `Idempotency-Key` et renseignez une valeur unique pour représenter l’opération (nous vous recommandons d’utiliser un UUID). Si aucune clé n’est renseignée, Stripe génère automatiquement un UUID. Toutes les requêtes API v2 `POST` et `DELETE` acceptent les clés d’idempotence et ont un comportement idempotent. Les requêtes `GET` étant idempotentes par nature, l’envoi d’une clé d’idempotence n’a aucun effet. ## Différences d’idempotence entre API v1 et API v2 Les idempotences API v1 et API v2 présentent quelques différences majeures : - API v1 prend uniquement en charge les relances idempotentes pour les requêtes `POST`. API v2 prend en charge toutes les requêtes `POST` et `DELETE`. - Une requête est considérée comme une réémission idempotente d’une autre requête car : - API v1 elles utilisent la même clé d’idempotence et se produisent à moins de 24 heures d’intervalle. - API v2 elles utilisent la même clé d’idempotence, la même API, se produisent au sein du même compte ou environnement de test et apparaissent en moins de 30 jours consécutifs. - Lorsque vous fournissez la même clé d’idempotence pour deux requêtes : - API v1 renvoie toujours la réponse précédemment enregistrée de la première requête de l’API, même s’il s’agissait d’une erreur. - API v2 tente de relancer les requêtes en échec sans engendrer d’effet indésirable (toute modification superflue ou tout comportement observable résultant d’un appel à l’API) et de fournir une réponse actualisée. ### Requêtes idempotentes À l’aide du SDK, fournissez une clé d’idempotence avec la propriété `idempotencyKey` dans les requêtes à l’API. Par exemple, pour effectuer une requête API avec une clé d’idempotence spécifique : #### Java ```java StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}"); String idempotencyKey = "unique-idempotency-key"; Example result = stripe.v2().examples().create( ExampleCreateParams.builder() .setName("My example") .build(), RequestOptions.builder() .setIdempotencyKey(idempotencyKey) .build()); ``` Si vous n’utilisez pas de SDK ni la CLI, les requêtes peuvent inclure l’en-tête `Idempotency-Key` : ```bash curl https://api.stripe.com/v2/examples \ -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: {{STRIPE_API_VERSION}}" \-H "Idempotency-Key: unique-idempotency-key" \ -d ``` ## Limites - Ce ne sont pas toutes les API `/v2` qui prennent en charge les [environnement de test du mode test](https://docs.stripe.com/testing-use-cases.md#compare). Vous pouvez toutefois toujours tester les endpoints `/v2` dans un environnement de test. - Actuellement, Stripe ne génère que des événements légers utilisant `/v2` des endpoints et des ressources. - Vous ne pouvez voir que les logs de requêtes générés par API v2 dans[Établi](https://docs.stripe.com/workbench.md), pas dans le Dashboard des développeurs.