# Enregistrement de l'usage pour la facturation à l'aide de l'API Découvrez comment enregistrer l'usage à l'aide de l'API Stripe. 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](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure.md), 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](https://docs.stripe.com/api/billing/meter-event/create.md) à l’aide de l’API. ```curl curl https://api.stripe.com/v1/billing/meter_events \ -u "<>:" \ -d event_name=hypernian_tokens \ -d "payload[value]=25" \ -d "payload[stripe_customer_id]={{CUSTOMER_ID}}" ``` ### Idempotence Utilisez les [clés d’idempotence](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/billing/meter-event/create.md#create_billing_meter_event-identifier) 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 [Événement de mesure](https://docs.stripe.com/api/billing/meter-event/create.md) autorise 1 000 appels par seconde en mode production. Si vous prévoyez de dépasser cette limite, vous avez deux options : - Précompilez vos données d’utilisation avant de les envoyer à Stripe. Par exemple, au lieu d’envoyer un événement pour chaque action individuelle de l’utilisateur, vous pouvez accumuler l’utilisation sur plusieurs actions et envoyer un seul événement agrégé périodiquement. Cela permet de réduire le nombre d’appels à l’API tout en signalant avec précision l’utilisation totale. - Utilisez la méthode d’ingestion à haut débit avec des flux d’événements de mesure pour des volumes nettement plus élevés. Dans les environnements de test, les appels à l’endpoint `meter event` et `meter event stream` sont pris en compte dans la [limite de base](https://docs.stripe.com/rate-limits.md#rate-limiter). > Si vous êtes une plateforme Connect qui fait des demandes au nom d’un compte connecté en utilisant l’en-tête `Stripe-Account`, vous êtes soumis à la [limite de débit normale de Stripe](https://docs.stripe.com/rate-limits.md), qui est de 100 opérations par seconde. 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](https://docs.stripe.com/api-v2-overview.md), 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. [Contactez notre équipe](https://stripe.com/contact/sales) si vous avez besoin d’envoyer jusqu’à 200 000 événements par seconde. Cet endpoint utilise des sessions d’identification sans état. Tout d’abord, créez une [session d’événement facturé à l’usage](https://docs.stripe.com/api/v2/billing/meter-event-sessions/create.md) pour recevoir un token d’authentification. Les tokens d’authentification ne sont valables que pour 15 minutes, vous devez donc créer une nouvelle session d’événement facturé à l’usage lorsque votre token expire. Ensuite, utilisez le token d’authentification renvoyé pour créer vos événements de mesure à haut débit avec l’[API Meter Event Stream](https://docs.stripe.com/api/v2/billing/meter-event-stream/create.md). > En raison du volume important de requêtes API, nous n’incluons pas les requêtes de flux d’événements de compteur dans l’[onglet Logs de Workbench](https://docs.stripe.com/workbench/overview.md#request-logs). 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. #### Ruby ```ruby 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 end def refresh_meter_event_session if @meter_event_session.nil? || DateTime.parse(@meter_event_session.expires_at) <= DateTime.now # Create a new meter event session in case the existing session expired client = Stripe::StripeClient.new(api_key) @meter_event_session = client.v2.billing.meter_event_session.create end end def send_meter_event(meter_event) # Refresh the meter event session if necessary refresh_meter_event_session # Create a meter event with the current session's authentication token client = Stripe::StripeClient.new(meter_event_session.authentication_token) client.v2.billing.meter_event_stream.create( events: [meter_event] ) end end # Send meter events api_key = "{{API_KEY}}" customer_id = "{{CUSTOMER_ID}}" manager = MeterEventManager.new(api_key) manager.send_meter_event( { event_name: 'hypernian_tokens', payload: { "stripe_customer_id" => customer_id, "value" => '25' } } ) ``` ## 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](https://docs.stripe.com/api/events.md) suivants : | Événement | Description | Type de charge utile | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------- | | `v1.billing.meter.error_report_triggered` | Cet événement se produit quand une mesure compte des événements d’usage non valide. | `thin` | | `v1.billing.meter.no_meter_found` | Cet événement se produit quand des événements d’usage comptent des ID de mesure manquants ou non valide. | `thin` | > Pour créer une destination d’événement abonnée aux événements légers, activez Workbench dans vos [paramètres de développement](https://dashboard.stripe.com/settings/developers). ### Exemples de charges utiles #### Exemple d'événement de rapport d'erreur Voici un exemple de charge utile pour un événement `v1.billing.meter.error_report_triggered`. ```json { "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": [ { "code": "meter_event_no_customer_defined", "error_count": 1, "sample_errors": [ { "error_message": "Customer mapping key stripe_customer_id not found in payload.", "request": { "id": "", "idempotency_key": "37c741d8-1f7e-4adc-af16-afdca1d73b37" } } ] } ] }, "validation_end": "2024-08-28T20:54:10.000Z", "validation_start": "2024-08-28T20:54:00.000Z" }, "reason": null, "related_object": { "id": "mtr_test_61R2GlpFXJ4R3L5DN41Fb82guyGVEUmO", "type": "billing.meter", "url": "/v1/billing/meters/mtr_test_61R2GlpFXJ4R3L5DN41Fb82guyGVEUmO" }, "type": "v1.billing.meter.error_report_triggered" } ``` #### Exemple d'événement d'erreur pour dispositif de mesure erroné Voici un exemple de charge utile pour un événement `v1.billing.meter.no_meter_found`. ```json { "created": "2024-10-01T20:42:52.203Z", "id": "evt_test_61REarcdWIsXleUiz16REahOMTSQbAhSD0fdnF9JAUdk", "object": "v2.core.event", "context": null, "type": "v1.billing.meter.no_meter_found", "data": { "developer_message_summary": "There is 1 invalid event", "reason": { "error_count": 1, "error_types": [ { "code": "no_meter", "error_count": 1, "sample_errors": [ { "error_message": "No meter was found matching event_name d2aa8cb3-3f00-44a4-b98f-3fbd1d0e93b1.", "request": { "identifier": "df5d4002-515b-4090-8fe2-a1b1f6f5b945" } } ] } ] }, "validation_end": "2024-10-01T20:42:50.000Z", "validation_start": "2024-10-01T20:42:40.000Z" }, "livemode": false, "reason": null, "related_object": {} } ``` ### 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](https://docs.stripe.com/event-destinations.md). 1. Dans l’onglet [Webhooks](https://dashboard.stripe.com/webhooks) de Workbench, cliquez sur **Créer une destination**. Vous pouvez également utiliser ce [modèle](https://dashboard.stripe.com/webhooks/create?payload_style=thin&events=v1.billing.meter.error_report_triggered%2Cv1.billing.meter.no_meter_found) pour configurer une nouvelle destination dans Workbench avec les deux types d’événements présélectionnés. 1. Cliquez sur **Afficher les options avancées**, puis sélectionnez le style de charge utile **Léger**. 1. Sélectionnez`v1.billing.meter.error_report_triggered` et `v1.billing.meter.no_meter_found` dans la liste des événements. 1. Créez un gestionnaire pour traiter l’événement. #### Python ```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') client = StripeClient(api_key) @app.route('/webhook', methods=['POST']) def webhook(): webhook_body = request.data sig_header = request.headers.get('Stripe-Signature') try: thin_event = client.parse_thin_event(webhook_body, sig_header, webhook_secret) # Fetch the event data to understand the failure event = client.v2.core.events.retrieve(thin_event.id) if isinstance(event, V1BillingMeterErrorReportTriggeredEvent): meter = event.fetch_related_object() meter_id = meter.id # Record the failures and alert your team # Add your logic here return jsonify(success=True), 200 except Exception as e: return jsonify(error=str(e)), 400 if __name__ == '__main__': app.run(port=4242) ``` 1. Testez votre gestionnaire en configurant un [écouteur local](https://docs.stripe.com/cli/listen) avec la [CLI Stripe](https://docs.stripe.com/stripe-cli.md) 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. ```sh $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*" ``` 1. Déclenchez des événements de test dans votre gestionnaire. Utilisez la [fonction de déclenchement](https://docs.stripe.com/cli/trigger) pour exécuter les commandes suivantes, qui simulent les événements respectifs dans votre compte à des fins de test. ```sh $ stripe trigger v1.billing.meter.error_report_triggered --api-key $ stripe trigger v1.billing.meter.no_meter_found --api-key ``` 1. Si vous traitez des événements avec un endpoint de webhook, [vérifiez les signatures de webhook](https://docs.stripe.com/webhooks.md#verify-official-libraries) pour sécuriser votre endpoint et vous assurer que toutes les requêtes proviennent de Stripe. 1. Corrigez et renvoyez les événements non valides afin qu’ils soient traités à nouveau.