Mises à jour de l'API Invoices
Dans les précédentes versions de l’API Stripe, les factures n’avaient pas d’état, mais une série de valeurs booléennes, telles que closed
, paid
et forgiven
.
Afin de mieux aligner les factures Stripe sur les flux financiers, nous avons ajouté des états aux factures. Tous les objets Invoice portent désormais la propriété status
. Le champ status
peut avoir les valeurs draft
, open
, paid
, void
et uncollectible
.
- L’état
draft
indique qu’une facture est modifiable. - L’état
open
indique que la facture a été finalisée. Par conséquent, elle n’est plus modifiable. - L’état
paid
indique que le montant de la facture a été intégralement réglé. - L’état
void
indique que la facture n’est plus valide. - L’état
uncollectible
indique que la facture sera probablement impayée et qu’elle peut être considérée comme une créance irrécouvrable.
Pour en savoir plus sur les différents états et le passage d’un état à un autre, consultez le guide de la facturation.
Exemples de chronologies de facturation
Cette section présente des exemples de chronologies pour les factures ponctuelles et les factures d’abonnement et détaille les différents états propres à chaque type de facture.
Exemple de facture ponctuelle
Voici un exemple de chronologie pour une facture ponctuelle. Cette séquence d’événements est identique à l’ancienne chronologie de facturation, à ceci près que Stripe affiche désormais un champ status
permettant d’identifier plus facilement l’état de la facture.
- 16 nov. : via l’API, vous créez une facture correspondant à l’expédition de 12 widgets à un client. Stripe envoie un webhook
invoice.created
pour vous informer de la création de la nouvelle facture. Dans l’API, vous pouvez constater que la facture porte l’état suivant :status='draft'
. - 26 nov. : après vérification, un comptable finalise la facture via le Dashboard Stripe. Au cours de la finalisation, l’état est mis à jour sur
status='open'
et le champfinalized_at
est défini. Stripe envoie un webhookinvoice.finalized
pour vous informer que la facture a été finalisée. - 26 nov. : quelques instants plus tard, Stripe envoie la facture par e-mail et commence les relances. Pour aider le système CRM à garder une trace de l’envoi des factures, Stripe joint un webhook
invoice.sent
à chaque envoi. - 1er déc. : votre client clique sur le lien de l’e-mail et tente de régler la facture depuis une page de paiement de facture hébergée, mais la carte qu’il utilise est expirée. Le paiement échoue et Stripe envoie le webhook
invoice.payment_failed
pour vous en avertir. - 3 déc. : le client renouvelle sa tentative avec une carte valide et le paiement aboutit. Stripe envoie le webhook
invoice.paid
pour vous informer du succès de l’opération, enregistre la carte et définit la facture surstatus='paid'
. Si l’adresse e-mail du client est renseignée, Stripe lui envoie également un reçu pour attester du règlement de la facture.
Exemple de facture d’abonnement
Voici un exemple de chronologie pour une facture générée par un abonnement.
- 13 nov. : via le Dashboard, vous créez un abonnement récurrent pour un client, avec l’option de paiement automatique. Le client bénéficiant d’une période d’essai de 20 jours, la première facture sera générée une fois ce délai écoulé (le 3 décembre). Stripe envoie un webhook
customer.subscription.created
.
- 30 nov. : trois jours avant la fin de la période d’essai, Stripe envoie un webhook
customer.subscription.trial_will_end
. Profitez de ces trois jours précédant la facturation pour envoyer un e-mail de rappel concernant la fin de la période d’essai.
- 3 déc. : à la fin de la période d’essai, une facture
status='draft'
est générée. Stripe envoie un webhookinvoice.created
pour vous informer de la création de la nouvelle facture. - 3 déc. : après environ une heure, la facture est automatiquement finalisée. Cela déclenche la mise à jour du
status
sur'open'
, la définition definalized_at
et l’envoi du webhookinvoice.finalized
. - 3 déc. : peu après, Stripe tente de débiter la carte enregistrée du client et le paiement aboutit. Stripe envoie le webhook
invoice.paid
pour vous informer du succès de l’opération et définit la facture surstatus='paid'
.
Nouvelles méthodes d’API
Stripe a lancé une suite de nouvelles API pour la gestion de l’état d’une facture. Les nouvelles options, détaillées dans la liste des mises à niveau ci-après, sont les suivantes :
- Envoyer une facture : Stripe envoie et renvoie automatiquement les factures par e-mail. Cet endpoint, disponible via l’API Stripe, vous permet d’envoyer la facture à votre client au moment de votre choix.
- Finaliser une facture : dans l’exemple ci-dessus, le comptable a finalisé la facture depuis le Dashboard Stripe. Cette fonctionnalité est également disponible via l’API Stripe.
- Annuler une facture : lorsqu’une facture a été finalisée, elle ne peut plus être annulée. L’annulation est utilisée pour indiquer que la facture a été émise par erreur. Vous pouvez par exemple annuler une facture sur laquelle le nom de votre entreprise a été écorché, puis en créer une nouvelle pour la remplacer.
- Supprimer un brouillon de facture : cette action concerne uniquement les brouillons de facture. Les brouillons supprimés ne sont pas visibles depuis votre Dashboard ou l’API et la suppression est irréversible.
- Marquer une facture comme non recouvrable : le service comptable de votre entreprise tient peut-être un registre des « créances douteuses », c’est-à-dire une liste des factures jugées irrécouvrables. Vous pouvez utiliser cette API pour marquer les factures concernées.
Liste des mises à niveau
Les sections suivantes répertorient les modifications fonctionnelles de l’objet Invoice
et des webhooks de facturation.
Objet Invoice
Stripe a ajouté plusieurs champs à l’objet Invoice
afin d’aider les utilisateurs à mieux comprendre son état et son fonctionnement.
finalized_at
Le nouveau champ finalized_at
précise l’heure à laquelle la facture a été finalisée. Il est disponible pour les demandes faites sur toutes les versions de l’API.
status
Le nouveau champ status
est disponible pour les demandes faites sur toutes les versions de l’API. Il remplace de nombreuses valeurs booléennes sur la facture, par exemple :
- Pour les demandes faites avec la version 2018-11-08 ou ultérieure, la valeur booléenne
paid=true
est remplacée parstatus='paid'
. - Pour les demandes faites avec la version 2018-11-08 ou ultérieure, la valeur booléenne
forgiven=true
est remplacée parstatus='uncollectible'
.
auto_advance
Le nouveau champ auto_advance
indique si l’encaissement automatique est activé. Pour les états 'draft'
et 'open'
, le champ auto_advance
peut être mis à jour. Sinon, auto_advance
sera toujours défini sur false
.
Si auto_advance=false
, Stripe s’abstient:
- D’émettre automatiquement des brouillons de facture
- D’envoyer automatiquement les premiers e-mails (ou les rappels) pour les factures
collection_method='send_invoice'
- De tenter automatiquement d’effectuer les premiers paiements (ou les relances) pour les factures
collection_method='charge_automatically'
Même si auto_advance=false
, Stripe rapproche automatiquement les virements entrants. Si un virement référence à une facture, il est rapproché de ladite facture. Dans le cas contraire, Stripe recherche les factures impayées et tente de les régler.
Pour les factures portant l’état 'uncollectible'
, 'void'
et 'paid'
, le champ auto_advance
est toujours défini sur false
.
Sur les versions antérieures à 2018-11-08, le champ closed
est toujours présent et correspond à l’inverse de la valeur du champ auto_advance
. Par exemple, auto_advance=true
équivaut à closed=false
, et inversement. closed=false
reste la valeur par défaut pour les factures créées à l’aide de versions antérieures de l’API.
Webhooks
Dans le cadre de cette mise à jour, nous avons ajouté trois nouveaux webhooks :
invoice.finalized
: webhook envoyé lorsqu’une facture est finalisée.invoice.voided
: webhook envoyé lorsqu’une facture est annulée.invoice.marked_uncollectible
: webhook envoyé lorsqu’une facture est marquée comme irrécouvrable.
Le webhook existant invoice.created
est envoyé lors de la création d’une facture. Si vous voulez que votre gestionnaire de webhooks différencie les factures ponctuelles des factures générées par un abonnement, vérifiez la présence de la propriété invoice.subscription
dans le corps du webhook.
Les webhooks suivants restent inchangés :
invoice.sent
: webhook envoyé lorsqu’une facture est communiquée par e-mail à un utilisateur, soit automatiquement via l’API, soit depuis le Dashboard.invoice.deleted
: webhook envoyé lorsqu’une facture portant l’étatdraft
est supprimée via l’API ou depuis le Dashboard.invoice.paid
ouinvoice.payment_failed
: webhook envoyé lorsqu’une tentative de paiement aboutit ou échoue, respectivement.