Enregistrement de l'usage pour la facturation à l'aide de l'API

Vous devez enregistrer l’utilisation dans Stripe pour vous assurer de facturer à vos clients les montants exacts à chaque période de facturation. Pour enregistrer l’utilisation, commencez par configurer votre dispositif de mesure, puis envoyez les événements de mesure qui incluent le nom de l’événement configuré sur le dispositif, l’ID du client, la valeur numérique et un horodatage (facultatif).

Vous pouvez décider de la fréquence à laquelle vous enregistrez l’usage dans Stripe, par exemple au fur et à mesure ou par lots. Stripe traite les événements de mesure de manière asynchrone. L’usage compilé dans des récapitulatifs d’événements de mesure et sur les factures à venir peut donc ne pas refléter immédiatement les derniers événements de mesure.

Créer des événements de mesure de la consommation

Créez un événement de mesure à l’aide de l’API.

curl https://api.stripe.com/v1/billing/meter_events \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d event_name=alpaca_ai_tokens \
  -d "payload[value]"=25 \
  -d "payload[stripe_customer_id]"={{CUSTOMER_ID}}

Idempotence

Utilisez les clés d’idempotence pour éviter d’envoyer des données d’usage plus d’une fois en cas de latence ou d’autres problèmes. Chaque événement de mesure correspond à un identifiant que vous pouvez préciser dans votre requête (sinon, nous en générons un automatiquement).

Horodatage des événements

Assurez-vous que l’horodatage est compris dans les 35 derniers jours calendaires et qu’il ne se situe pas plus de 5 minutes dans le futur. La fenêtre de 5 minutes sert en cas de décalage entre l’horloge de votre serveur et celle des systèmes de Stripe.

Valeurs d’utilisation

La valeur numérique de l’utilisation dans la charge utile n’accepte que les nombres entiers. Si la consommation globale au cours du cycle est négative, Stripe indique que la quantité d’utilisation du poste de facture est égale à 0.

Limites de débit

L’endpoint d’événement de mesure autorise un maximum de 1 000 appels par seconde en mode production, et un appel simultané par client et par mesure. Si votre service est susceptible de dépasser cette limite, vous pouvez créer des produits groupés en fonction des volumes. Par exemple, si vous facturez par lot de 1 000 requêtes, vous pourriez définir un produit correspondant à 1 000 transactions et envoyer 1 enregistrement d’usage par lot de 1 000.

Dans les environnements de test, les appels à l’endpoint meter event et meter event stream sont pris en compte dans la limite de base.

Vous pouvez surveiller les codes d’état 429 et implémenter un mécanisme de relance avec un délai d’attente qui augmente de manière exponentielle pour gérer le volume de requêtes.

Ingestion à haut débit avec des seuils plus élevés API v2

Avec l’API v2, vous pouvez envoyer jusqu’à 10 000 événements par seconde à Stripe en utilisant les flux d’événements de mesure. Cela fonctionne uniquement en mode production.

Cet endpoint utilise des sessions d’authentification sans état. Tout d’abord, créez une session d’événement de mesure pour recevoir un token d’authentification. Les tokens d’authentification ne sont valables que 15 minutes. Vous devez donc créer une nouvelle session d’événement de mesure à l’expiration de votre token.

Ensuite, utilisez le token d’authentification renvoyé pour créer vos événements de mesure à haut débit avec l’API Meter Event Stream.

Vous pouvez surveiller les codes d’état 429 et implémenter un mécanisme de relance avec un délai d’attente qui augmente de manière exponentielle pour gérer le volume de requêtes.

require 'stripe'
require 'date'

class MeterEventManager
  attr_accessor :api_key
  attr_accessor :meter_event_session

  def initialize(api_key)
    @api_key = api_key
    @meter_event_session = nil

Gérer les erreurs relatives aux événements de mesure de la consommation

Stripe traite les événements de mesure de manière asynchrone. Si nous trouvons une erreur, nous créons l’un des événements suivants :

Exemples de charges utiles

{
  "id": "evt_test_65R2GpwDsnmpzihMjdT16R2GDhI4SQdXJGRbvn7JA8mPEm",
  "object": "v2.core.event",
  "created": "2024-08-28T20:54:12.051Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {

Codes d’erreur

reason.error_types.code : indique la catégorie d’erreur déclenchée. Les codes d’erreur possibles sont les suivants :

• meter_event_customer_not_found
• meter_event_no_customer_defined
• meter_event_dimension_count_too_high
• archived_meter
• timestamp_too_far_in_past
• timestamp_in_future
• meter_event_value_not_found
• meter_event_invalid_value
• no_meter (pris en charge uniquement pour le type d’événement v1.billing.meter.no_meter_found)

Écouter les événements

Vous pouvez écouter des événements en configurant un endpoint de webhook ou un autre type de destination d’événement.

1. Dans l’onglet Webhooks de Workbench, cliquez sur Créer une destination. Vous pouvez également utiliser ce modèle pour configurer une nouvelle destination dans Workbench avec les deux types d’événements présélectionnés.

2. Cliquez sur Afficher les options avancées, puis sélectionnez le style de charge utile Léger.

3. Sélectionnezv1.billing.meter.error_report_triggered et v1.billing.meter.no_meter_found dans la liste des événements.

4. Créez un gestionnaire pour traiter l’événement.

   Python

   import os
   from stripe import StripeClient
   from stripe.events import V1BillingMeterErrorReportTriggeredEvent
   
   from flask import Flask, request, jsonify
   
   app = Flask(__name__)
   api_key = os.environ.get('STRIPE_API_KEY')
   webhook_secret = os.environ.get('WEBHOOK_SECRET')
   

   Afficher les 35 lignes

5. Testez votre gestionnaire en configurant un écouteur local avec la CLI Stripe afin d’envoyer les événements à votre machine locale à des fins de test avant de déployer le gestionnaire en mode production. Utilisez le flag --forward-thin-to afin de spécifier l’URL vers laquelle transférer les événements thin, et le flag --thin-events pour spécifier les événements thin à transférer. Vous pouvez transférer tous les événements thin avec un astérisque (*), ou un sous-ensemble des événements thin vers votre application.

   $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"
   

6. Déclenchez des événements de test dans votre gestionnaire. Utilisez la fonction de déclenchement pour exécuter les commandes suivantes, qui simulent les événements respectifs dans votre compte à des fins de test.

   $ stripe trigger v1.billing.meter.error_report_triggered --api-key <your-secret-key>
   $ stripe trigger v1.billing.meter.no_meter_found --api-key <your-secret-key>
   

7. Si vous traitez des événements avec un endpoint de webhook, vérifiez les signatures de webhook pour sécuriser votre endpoint et vous assurer que toutes les requêtes proviennent de Stripe.

8. Corrigez et renvoyez les événements non valides afin qu’ils soient traités à nouveau.