API et utilisation avancée
Découvrez des stratégies avancées d'utilisation des horloges de simulation dans le Dashboard et l'API.
Vous pouvez créer une horloge de simulation distincte d’un abonnement afin d’effectuer des simulations avancées. Dans ce scénario, vous devez d’abord créer l’horloge de simulation, puis y ajouter différents cas de test.
Vous n’êtes pas prêt(e) à tester une intégration complète ? Consultez notre guide pour effectuer des simulations sur des abonnements.
![Découvrez configurer une horloge de simulation pour simuler l'expiration d'un abonnement.](https://b.stripecdn.com/docs-statics-srv/assets/test-clock-lifecycle.b711b9cf4feb52351e27958b8b924cb3.png)
Cycle de vie d’une horloge de simulation
Suivez ces étapes pour commencer à utiliser des horloges de simulation :
- Créez une horloge de simulation
- Configurez votre simulation
- Avancez la date et l’heure de l’horloge
- Observez et traitez les modifications
- Modifiez la simulation
- Supprimer l’horloge
Vous pouvez avancer la date et l’heure de l’horloge, observer les changements et mettre à jour la simulation autant que nécessaire pour tester différents cas.
Créer une horloge et définir une date et une heure![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Pour lancer une simulation, créez une horloge et définissez sa date de départ, qui sera le point de départ temporel de tous les abonnements associés à cette horloge. La date de départ peut être antérieur ou postérieure à la date du jour, selon le scénario que vous souhaitez tester. Cependant, une fois cette date définie, l’horloge ne pourra qu’avancer.
Configurer votre simulation![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Ensuite, configurez le cas de test à simuler. Vous devez d’abord créer un client, puis son abonnement.
Les objets Customer et Subscription sont associés à l’objet Clock que vous avez créé à la première étape. Dans le Dashboard, l’icône indique qu’un objet est associé à une horloge.
Avancer la date et l'heure de la simulation![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Une fois que vous avez créé l’horloge de simulation et configuré votre cas de test, avancez la date et l’heure de l’horloge. La première fois, vous avancerez à partir de la date de départ définie à la création de l’horloge. Vous pourrez ainsi observer le comportement de votre intégration à la fin d’un abonnement, à son renouvellement ou en cas de modification de l’abonnement (par exemple, au passage d’une période d’essai à un abonnement payant).
Vous pouvez uniquement faire avancer l’horloge de deux intervalles à la fois à compter de leur date de départ. La longueur de ces intervalles correspond à la plus petite période d’abonnement de cette horloge, qui est déterminée par son tarif récurrent. Par exemple, si l’horloge est associée à un abonnement mensuel, elle ne pourra être avancée que de deux mois à la fois. Les horloges qui ne sont pas associées à un abonnement ou une fréquence d’abonnement peuvent être avancées de deux ans maximum à partir de leur date de départ.
Surveiller et gérer les modifications![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
À la réussite de la requête à l’API ou de l’opération dans le Dashboard, l’horloge avance à la date et l’heure spécifiées (cette opération prend quelques secondes). Pour savoir si l’état de l’horloge a changé, vous pouvez écouter les notifications d’événements à l’aide de webhooks ou interroger l’horloge. Le Dashboard reflète également les changements survenus. Par exemple, vous pouvez accéder à la page Factures pour vérifier si une facture a été créée ou payée pour cet abonnement.
Si vous utilisez des webhooks, écoutez les notifications d’événements suivantes. Avant de passer au mode production, pensez à vérifier que votre intégration est capable de gérer les notifications d’événements de facturation autres que celles listées ci-dessous.
Événement | Description |
---|---|
test_ | L’horloge a commencé à avancer mais n’a pas atteint la date et l’heure spécifiées. |
test_ | L’horloge a atteint à la date et à l’heure spécifiées. |
Pour interroger l’état de l’horloge, récupérez-le en indiquant l’ID de l’horloge pour examiner son attribut status
.
Modifier la simulation![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Vous pouvez continuer à apporter des changements à votre simulation et à avancer l’horloge pour différentes simulations, par exemple pour :
- Ajout d’un solde client.
- Changer d’abonnement en milieu de cycle.
- Ajout de postes de facture ponctuels.
Après chaque modifications, observez à nouveau les changements survenus. Réitérez l’opération autant de fois que votre cas de test l’exige.
Supprimer l'horloge![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Les horloges de test sont automatiquement supprimées 30 jours après leur création, mais pour un environnement de test moins encombré, vous pouvez les effacer dès que votre test est terminé.
La suppression de l’horloge supprime également les clients qui y sont associés et annule leurs abonnements. Les horloges de simulation sont uniquement disponibles en mode test, vous ne risquez donc pas d’effacer des objets réels lors de la suppression d’une horloge.
Cas d'usage![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Tester les renouvellements d’abonnements![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :
- Créez une horloge de simulation
- Configurez votre simulation
- Avancez la date et l’heure de l’horloge
- Observez et traitez les modifications
- Modifiez la simulation
Ensuite, vous pouvez tester certains renouvellements d’abonnements à l’aide d’horloges de simulation. Imaginons que vous souhaitez tester si un abonnement à 50 USD/mois se renouvelle correctement. Pour simuler cette situation en utilisant des horloges de simulation :
- Créez une nouvelle horloge de simulation et définissez son paramètre
frozen_
sur le 1er janvier.time - Ajoutez un client et associez-y un moyen de paiement :
Quand vous avez ajouté un moyen de paiement à votre client, créez-lui un abonnement de 50 USD/mois. Ce faisant, la facture de 50 USD est payée automatiquement et l’abonnement passe à l’état
active
.Avancez la date au 1er février. Vous devriez constater qu’une facture de 50 USD a été créée. Par défaut, la facture apparaît à l’état
draft
pendant une heure.Avancez l’horloge d’une heure pour vérifier que la facture a bien été finalisée et payée automatiquement.
Tester un changement d’abonnement en cours de cycle avec calcul au prorata![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :
- Créez une horloge de simulation
- Configurez votre simulation
- Avancez la date et l’heure de l’horloge
- Observez et traitez les modifications
- Modifiez la simulation
Ensuite, vous pouvez tester des calculs au prorata pour les clients qui changent d’offre au milieu d’un cycle de facturation. Imaginons que vous avez deux produits : un à 50 USD/mois (‘basic plan‘) et l’autre à 100 USD/mois (‘premium plan‘). Dans ce cas, vous pourriez vouloir tester les calculs au prorata pour un client qui passe de l’offre ‘basic plan‘ à l’offre ‘premium plan‘ en cours de cycle de facturation. Pour simuler cette situation à l’aide d’horloges de simulation :
- Créez une nouvelle horloge de simulation et définissez son paramètre
frozen_
sur le 1er janvier.time - Créez un client et ajoutez son moyen de paiement. Ici, utilisez la carte de test .
- Créez un abonnement à ‘basic plan’ pour 50 USD/mois. Vous pourrez alors observer qu’une facture de 50 USD/mois a été créée, finalisée et payée automatiquement.
- Avancez la date de deux semaines. Ici, nous définirons la date sur le 16 janvier.
- Passez à l’abonnement ‘premium plan’, de 100 USD/mois :
Après le passage à un abonnement supérieur, l’événement webhook customer.subscription.updated est créé.
Les postes de facture en attente sont aussi créés pour les calculs au prorata. Vous remarquerez un prorata négatif de -25 USD correspondant à la période non-consommée du ‘basic plan’, et un prorata positif de 50 USD pour la consommation du ‘premium plan’ correspondant à la moitié du mois restant. À ce stade, aucune facture n’a été générée.
Avancez la date de deux semaines. Dans ce cas, nous réglerons la date au 1er février. Vous remarquerez que l’abonnement a effectué son cycle. Une facture a été générée à l’état
draft
. Elle inclut les postes de facturation en attente, y compris un prorata négatif, un prorata positif et le paiement complet pour le mois de février, qui s’élève à 125 USD. Par défaut, la facture apparaît à l’étatdraft
pendant environ une heure.Avancez l’horloge d’une heure afin de finaliser la facture.
Périodes d’essai![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :
- Créer une horloge de simulation
- Configurer votre simulation
- Avancer la date et l’heure de l’horloge
- Observer et traiter les modifications
- Modifier la simulation
Ensuite, vous pouvez commencer à tester les périodes d’essai avec les horloges de simulation. Imaginons que vous voulez que vos clients testent vos produits gratuitement pendant une période d’essai de sept jours avant de commencer à payer et vous souhaitez collecter les informations de paiement en amont. Suivez les étapes ci-après pour simuler cette situation en utilisant des horloges de simulation :
- Créez une nouvelle horloge de simulation et réglez son
frozen_
sur le 1er janvier.time - Ajoutez un client et spécifiez son moyen de paiement. Dans ce cas, utilisez une carte de test.
- Créez un abonnement et ajoutez une période d’essai gratuit de sept jours :
- Suite à la création d’un abonnement avec une période d’essai gratuit de sept jours, un abonnement est créé dans un état
trialing
. L’essai gratuit donne lieu à la génération d’une facture de 0 $. - Avancez la date au 5 janvier pour recevoir la notification d’événement customer.subscription.trial_will_end. Stripe envoie la notification trois jours avant la fin de la période d’essai. Vous pouvez utiliser cet événement webhook pour informer vos clients que la période d’essai arrive bientôt à son terme.
- Avancez la date au 8 janvier pour vérifier que l’abonnement est désormais à l’état
paid
et qu’une facture de 50 USD a été créée. - Avancez la date d’un cycle (par exemple, au 8 février pour un abonnement mensuel) pour constater le renouvellement.
Limites![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Pour un fonctionnement efficace des horloges de test, Stripe limite la complexité de chaque simulation à :
- Trois clients
- Trois abonnements (qui peuvent être des abonnements planifiés) par client
- Dix devis non associés à des clients
Objets de l’horloge de simulation omis dans la liste de tous les résultats![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Les API de liste de Stripe (telles que Liste de factures) omettent les résultats générés par les horloges de simulation pour toutes les requêtes de liste. Pour voir les résultats générés par les horloges de simulation dans ces cas, vous devez demander des résultats dans un parent spécifique, tel que test_
, customer
ou subscription
.
Par exemple, GET /v1/invoices
ne renverra pas les factures générées par l’horloge de simulation, mais GET {customer_
renverra toutes les factures pour ce client, y compris celles qui sont générées par l’horloge de simulation.
De même, vous pouvez spécifier un identifiant d’horloge de simulation dans cet exemple pour obtenir toutes les factures liées à cette horloge, ou spécifier un identifiant d’abonnement pour obtenir toutes les factures relatives à cet abonnement, y compris les factures générées par l’horloge de simulation.
Mises en garde concernant le traitement des paiements![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
L’avancement de l’horloge de simulation ne prend pas encore en charge la collecte des paiements par prélèvement bancaire (comme les types de moyen de paiement us_
). Stripe encaisse les paiements après avancement de l’horloge de simulation. Pour tester les échecs de paiement :
Sélectionnez le paramètre Annuler l’abonnement après l’échec de toutes les relances de paiement.
Associez un moyen de paiement de type
us_
à un client dont les paiements échouent.bank_ account Créez un abonnement pour le client.
Faites avancer l’horloge de simulation pour collecter le paiement d’un abonnement.
Une fois l’horloge de simulation avancée, l’abonnement est toujours à l’état active
. Cela signifie qu’aucune tentative d’encaissement du paiement n’a été effectuée durant l’avancement de l’horloge de simulation, et que l’abonnement n’est pas passé à l’état canceled
suite au payment_
.
Écoutez l’événement invoice.
pour surveiller l’état de l’abonnement en retard de paiement et le paiement de la facture. L’événement customer.
indique que l’abonnement est à l’état canceled
.