Nutzung für Abrechnungszwecke mit der API aufzeichnen

Sie müssen die Nutzungsdaten in Stripe aufzeichnen, um sicherzustellen, dass Sie Ihren Kundinnen/Kunden für jeden Abrechnungszeitraum korrekte Beträge in Rechnung stellen. Um die Nutzungsdaten aufzuzeichnen, konfigurieren Sie zuerst Ihren Zähler und senden Sie dann Zählerereignisse, die den für den Zähler konfigurierten Ereignisnamen, die Kunden-ID, einen numerischen Wert und einen Zeitstempel (optional) enthalten.

Sie können entscheiden, wie oft Sie die Nutzung bei Stripe aufzeichnen, beispielsweise direkt oder in Batches. Stripe verarbeitet Zählerereignisse asynchron, sodass die Nutzung in Zählerereignis-Zusammenfassungen aggregiert wird und anstehende Rechnungen möglicherweise kürzlich empfangene Zählerereignisse nicht sofort widerspiegeln.

Zählerereignisse erstellen

Erstellen Sie ein Zählerereignis mithilfe der 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}}

Idempotenz

Verwenden Sie Idempotenz-Schlüssel, um zu verhindern, dass die Nutzung aufgrund von Latenz oder anderen Problemen für jedes Ereignis mehrmals gemeldet wird. Jedes Zählerereignis entspricht einer Kennung, die Sie in Ihrer Anfrage angeben können. Wenn Sie keine Angabe machen, erstellen wir diese automatisch.

Ereignis-Zeitstempel

Der Zeitstempel muss innerhalb der letzten 35 Kalendertage und darf nicht mehr als 5 Minuten in der Zukunft liegen. Das 5-Minuten-Fenster berücksichtigt mögliche Uhrenfehler zwischen Ihrem Server und den Systemen von Stripe.

Nutzungswerte

Der numerische Nutzungswert in der Nutzlast akzeptiert nur ganzzahlige Werte. Wenn die gesamte Zyklusnutzung negativ ist, meldet Stripe die Nutzungsmenge des Rechnungspostens als 0.

Ratenbegrenzungen

Der Zählerereignis-Endpoint ermöglicht 1000 Anrufe pro Sekunde im Live-Modus und einen gleichzeitigen Anruf pro Kunde/Kundin und Zähler. Wenn Ihre Dienstleistung dieses Limit überschreiten könnte, können Sie Ihr Produkt in Beträgen „bündeln“. Wenn Sie beispielsweise pro 1000 Anfragen abrechnen, können Sie Ihr Produkt in „pro 1000 Transaktionen“ zusammenfassen und dann alle 1000 Mal 1 Nutzungsdatensatz senden.

Im Sandbox-Modus werden Aufrufe der Endpoints meter event und meter event stream auf das Basislimit angerechnet.

Sie können 429-Statuscodes überwachen und einen Wiederholungsmechanismus mit einem exponentiellen Backoff-Zeitplan implementieren, um das Anfragevolumen zu verwalten.

Aufnahme von hohem Durchsatz mit höheren Ratenbegrenzungen API v2

Mit der API v2 können Sie mithilfe von Zählerereignis-Streams bis zu 10.000 Ereignisse pro Sekunde an Stripe senden. Dies funktioniert nur im Live-Modus.

Dieser Endpoint verwendet statuslose Authentifizierungssitzungen. Erstellen Sie zunächst eine Zählerereignissitzung, um ein Authentifizierungs-Token zu erhalten. Authentifizierungs-Token sind nur 15 Minuten lang gültig. Sie müssen also eine neue Zählerereignissitzung erstellen, wenn Ihr Token abläuft.

Verwenden Sie als Nächstes das zurückgegebene Authentifizierungst-Token, um Ihre Zählerereignisse mit hohem Durchsatz mit dem Zählerereignis-Stream zu erstellen.

Sie können 429-Statuscodes überwachen und einen Wiederholungsmechanismus mit einem exponentiellen Backoff-Zeitplan implementieren, um das Anfragevolumen zu verwalten.

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

Umgang mit Zählerereignisfehlern

Stripe verarbeitet Zählerereignisse asynchron. Wenn wir einen Fehler finden, erstellen wir eines der folgenden Ereignisse:

Beispiel-Nutzlasten

{
  "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": [
        {

Fehlercodes

Der reason.error_types.code stellt die Fehlerkategorisierung bereit, die den Fehler ausgelöst hat. Mögliche Fehlercodes sind:

• 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: (wird nur für den Ereignistyp v1.billing.meter.no_meter_found unterstützt)

Ereignisse überwachen

Sie können Ereignisse überwachen, indem Sie einen Webhook-Endpoint oder eine andere Art von Ereignisziel einrichten.

1. Klicken Sie auf der Registerkarte Webhooks in Workbench auf Neues Ziel erstellen. Alternativ können Sie diese Vorlage verwenden, um ein neues Ziel in Workbench zu konfigurieren, bei dem die beiden Ereignistypen vorausgewählt sind.

2. Klicken Sie auf ** Erweiterte Optionen anzeigen ** und wählen Sie dann den Thin als Nutzlaststil.

3. Wählen Sie v1.billing.meter.error_report_triggered und v1.billing.meter.no_meter_found aus der Ereignisliste.

4. Erstellen Sie einen Handler, um das Ereignis zu verarbeiten.

   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')
   

   Alle 35 Zeilen anzeigen

5. Testen Sie Ihren Handler, indem Sie einen lokalen Listener mit der Stripe CLI konfigurieren, um Ereignisse zum Testen an Ihren lokalen Computer zu senden, bevor Sie den Handler in der Produktionsumgebung bereitstellen. Verwenden Sie das Flag --forward-thin-to, um anzugeben, an welche URL die thin-Ereignisse weitergeleitet werden sollen, und das Flag --thin-events, um anzugeben, welche Thin-Ereignisse weitergeleitet werden sollen. Sie können alle Thin-Ereignisse mit einem Sternchen (*) oder einer Teilmenge von Thin-Ereignissen an Ihre Anwendung weiterleiten.

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

6. Lösen Sie Testereignisse für Ihren Handler aus. Verwenden Sie die Trigger-Funktion, um die folgenden Befehle auszuführen, die die jeweiligen Ereignisse in Ihrem Konto zum Testen simulieren.

   $ 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. Wenn Sie Ereignisse mit einem Webhook-Endpoint verarbeiten, überprüfen Sie die Webhook-Signaturen, um Ihren Endpoint zu sichern und zu überprüfen, ob alle Anforderungen von Stripe stammen.

8. Ungültige Ereignisse zur erneuten Verarbeitung korrigieren und erneut senden.