# Nutzung für Abrechnungszwecke mit der API aufzeichnen Erfahren Sie, wie Sie mit der Stripe API die Nutzung 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](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure.md) 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](https://docs.stripe.com/api/billing/meter-event/create.md) mithilfe der 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}}" ``` ### Idempotenz Verwenden Sie [Idempotenz-Schlüssel](https://docs.stripe.com/api/idempotent_requests.md), 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](https://docs.stripe.com/api/billing/meter-event/create.md#create_billing_meter_event-identifier), 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 Endpoint [Zähler-Ereignis](https://docs.stripe.com/api/billing/meter-event/create.md) erlaubt im Live-Modus 1.000 Aufrufe pro Sekunde. Wenn Sie erwarten, dass Sie diese Grenze überschreiten, haben Sie zwei Möglichkeiten: - Aggregieren Sie Ihre Nutzungsdaten, bevor Sie sie an Stripe senden. Anstatt beispielsweise für jede/n einzelne/n Nutzer/in ein Ereignis zu senden, könnten Sie die Nutzung über mehrere Aktionen hinweg akkumulieren und in regelmäßigen Abständen ein einziges aggregiertes Ereignis senden. Dadurch wird die Anzahl der API-Aufrufe reduziert, während die Gesamtnutzung weiterhin genau gemeldet wird. - Verwenden Sie die Hochdurchsatz-Ingestion-Methode mit Zähler-Ereignisströmen, um deutlich höhere Volumen zu bewältigen. Im Sandbox-Modus werden Aufrufe der Endpoints `meter event` und `meter event stream` auf das [Basislimit](https://docs.stripe.com/rate-limits.md#rate-limiter) angerechnet. > Wenn Sie eine Connect-Plattform sind, die mithilfe des `Stripe-Account`-Headers Anfragen im Namen eines verbundenen Kontos stellt, unterliegen Sie den [regulären Ratenbegrenzungen von Stripe](https://docs.stripe.com/rate-limits.md), also 100 Vorgängen pro Sekunde. 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](https://docs.stripe.com/api-v2-overview.md) können Sie mithilfe von Zählerereignis-Streams bis zu 10.000 Ereignisse pro Sekunde an Stripe senden. Dies funktioniert nur im Live-Modus. [Kontaktieren Sie das Sales-Team](https://stripe.com/contact/sales), wenn Sie bis zu 200.000 Ereignisse pro Sekunde senden müssen. Dieser Endpoint verwendet zustandslose Sessions zur Authentifizierung. Erstellen Sie zunächst eine [Zählerereignissitzung](https://docs.stripe.com/api/v2/billing/meter-event-sessions/create.md), um ein Token zur Authentifizierung zu erhalten. Authentifizierungs-Tokens sind nur 15 Minuten lang gültig. Sie müssen also eine neue Zählerereignis-Sitzung 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](https://docs.stripe.com/api/v2/billing/meter-event-stream/create.md) zu erstellen. > Aufgrund der großen Anzahl von API-Anfragen nehmen wir keine Zählerereignisstream-Anfragen in die Registerkarte [Workbench-Logs](https://docs.stripe.com/workbench/overview.md#request-logs) auf. Sie können `429`-Statuscodes überwachen und einen Wiederholungsmechanismus mit einem exponentiellen Backoff-Zeitplan implementieren, um das Anfragevolumen zu verwalten. #### 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' } } ) ``` ## Umgang mit Zählerereignisfehlern Stripe verarbeitet Zählerereignisse asynchron. Wenn wir einen Fehler finden, erstellen wir eines der folgenden [Ereignisse](https://docs.stripe.com/api/events.md): | Ereignis | Beschreibung | Nutzlasttyp | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | | `v1.billing.meter.error_report_triggered` | Dieses Ereignis tritt auf, wenn ein Zähler ungültige Nutzungsereignisse aufweist. | `thin` | | `v1.billing.meter.no_meter_found` | Dieses Ereignis tritt auf, wenn Nutzungsereignisse fehlende oder ungültige Zähler-IDs aufweisen. | `thin` | > Um ein Ereignisziel zu erstellen, das Thin-Ereignisse abonniert, aktivieren Sie Workbench in Ihren [Entwicklereinstellungen](https://dashboard.stripe.com/settings/developers). ### Beispiel-Nutzlasten #### Beispiel für ein Fehlerberichtsereignis Nachfolgend finden Sie ein Beispiel einer Nutzlast für ein Ereignis des Typs `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" } ``` #### Beispiel-Fehlerereignis für einen falschen Zähler Nachfolgend finden Sie ein Beispiel einer Nutzlast für ein `v1.billing.meter.no_meter_found`-Ereignis. ```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": {} } ``` ### 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](https://docs.stripe.com/event-destinations.md) einrichten. 1. Klicken Sie auf der Registerkarte [Webhooks](https://dashboard.stripe.com/webhooks) in Workbench auf **Neues Ziel erstellen**. Alternativ können Sie diese [Vorlage](https://dashboard.stripe.com/webhooks/create?payload_style=thin&events=v1.billing.meter.error_report_triggered%2Cv1.billing.meter.no_meter_found) verwenden, um ein neues Ziel in Workbench zu konfigurieren, bei dem die beiden Ereignistypen vorausgewählt sind. 1. Klicken Sie auf ** Erweiterte Optionen anzeigen ** und wählen Sie dann den **Thin** als Nutzlaststil. 1. Wählen Sie `v1.billing.meter.error_report_triggered` und `v1.billing.meter.no_meter_found` aus der Ereignisliste. 1. Erstellen Sie einen Handler, um das Ereignis zu verarbeiten. #### 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. Testen Sie Ihren Handler, indem Sie einen [lokalen Listener](https://docs.stripe.com/cli/listen) mit der [Stripe CLI](https://docs.stripe.com/stripe-cli.md) 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. ```sh $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*" ``` 1. Lösen Sie Testereignisse für Ihren Handler aus. Verwenden Sie die [Trigger-Funktion](https://docs.stripe.com/cli/trigger), um die folgenden Befehle auszuführen, die die jeweiligen Ereignisse in Ihrem Konto zum Testen simulieren. ```sh $ stripe trigger v1.billing.meter.error_report_triggered --api-key $ stripe trigger v1.billing.meter.no_meter_found --api-key ``` 1. Wenn Sie Ereignisse mit einem Webhook-Endpoint verarbeiten, [überprüfen Sie die Webhook-Signaturen](https://docs.stripe.com/webhooks.md#verify-official-libraries), um Ihren Endpoint zu sichern und zu überprüfen, ob alle Anforderungen von Stripe stammen. 1. Ungültige Ereignisse zur erneuten Verarbeitung korrigieren und erneut senden.