Plugin-Fehlerbehebung

Diese Anleitung fuehrt durch die haeufigsten Plugin-Probleme, auf die Betreiber stossen, und wie man sie behebt.

Mein Plugin zeigt Status "Fehlerhaft"

Das bedeutet, dass juengste Webhook-Zustellungen Fehler gemeldet haben. Oeffnen Sie die Installation (Einstellungen -> Plugins -> Zahnradsymbol), um zu sehen, was los ist.

Schritte

Ich erhalte keine Ereignisse

Moegliche Ursachen in der Reihenfolge der Wahrscheinlichkeit:

1. Plugin ist deaktiviert. Pruefen Sie den Status-Indikator. Klicken Sie auf Aktivieren, wenn Deaktiviert angezeigt wird.
2. Plugin abonniert nicht das erwartete Ereignis. Verschiedene Plugins abonnieren verschiedene Ereignisse. Oeffnen Sie die Plugin-Detailseite, um seine webhook_subscriptions-Liste zu sehen.
3. Das Ereignis feuert nicht in Ihrem Subkonto. Testen Sie, indem Sie das Ereignis manuell ausloesen (z. B. eine Testfahrt fuer ein ride.ended-Ereignis beenden).
4. Webhook-Endpunkt ist nicht erreichbar. Gehen Sie zu "Mein Plugin zeigt Status Fehlerhaft" oben.
5. Token wurde widerrufen. Rotieren Sie das Token und stellen Sie das neue dem Anbieter zur Verfuegung.

Ein bestimmtes Ereignis fehlt

Wenn die meisten Ereignisse ankommen, aber eines nicht:

• Pruefen Sie die Ereignis-Taxonomie im Manifest des Plugins. Wenn das Ereignis nicht in webhook_subscriptions ist, hoert das Plugin es nicht ab.
• Einige Ereignisse sind noch nicht in den Levy-Kern eingebunden. Die Ereignisse zone.entered, zone.exited und zone.violation sind definiert, werden aber nicht immer emittiert, abhaengig davon, welche Zonen-Tracking-Module in Ihrem Subkonto aktiviert sind.
• Fuer customer.kyc_completed feuert das Ereignis nur, wenn ein KYC-Plugin installiert ist und aktiv Ergebnisse zurueckschreibt - ohne ein KYC-Plugin wird kein Ereignis emittiert.

Webhook-Signaturpruefung schlaegt fehl (Anbieterseite)

Wenn Sie ein Anbieter sind und Ihr Endpunkt Levys Signaturen ablehnt:

• Pruefen Sie, ob Sie die Signatur im richtigen Format verifizieren: X-Levy-Signature: t=<unix-ts>,v1=<hex-hmac>.
• Die signierte Nutzlast ist ${ts}.${body} - beachten Sie den Punkttrenner und dass body der rohe Anforderungskoerper ist, nicht das geparste JSON.
• Das Signierungsgeheimnis ist das Pro-Install-Geheimnis Ihres Plugins, verfuegbar in Ihrem Anbieter-Dashboard fuer jede Installation.
• Levy lehnt Zeitstempel ab, die aelter als 5 Minuten sind; stellen Sie sicher, dass Ihre Uhr mit NTP synchronisiert ist.

Siehe Plugin einreichen - Webhook-Endpunkt fuer Beispielverifizierungscode.

API-Aufrufe des Plugins geben 401 zurueck

Das Token des Plugins ist ungueltig. Gruende:

• Das Token wurde kuerzlich rotiert und die 24-Stunden-Karenzfrist ist abgelaufen. Senden Sie das neue Token an den Anbieter.
• Die Installation wurde deinstalliert - das Token ist dauerhaft widerrufen.
• Das Token-Format entspricht nicht lvy_plg_<install-prefix>_<random> - der Anbieter verwendet moeglicherweise ein Token von einem anderen Konto.
• Die Subkonto-ID des Plugins entspricht nicht der Subkonto-ID der Ressource - der Anbieter versucht, Daten aus einem Subkonto zu lesen, das ihn nicht installiert hat. Dies ist eine harte Sperre auf der RLS-Ebene, nicht konfigurierbar.

API-Aufrufe des Plugins geben 403 zurueck

Das Token des Plugins ist gueltig, aber eine erforderliche Berechtigung fehlt. Der Antwortkoerper enthaelt den fehlenden Scope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing permission: read:customers.pii",
    "required_scope": "read:customers.pii"
  }
}

Sie (der Betreiber) koennen einem installierten Plugin keine neuen Berechtigungen erteilen, ohne neu zu installieren. Wenn sich das Manifest eines Anbieters aendert, um eine neue Berechtigung hinzuzufuegen, sehen Sie ein Banner, das Sie auffordert, erneut zuzustimmen.

Abrechnung - Belastung fehlgeschlagen

Wenn eine monatliche oder Nutzungsbelastung fehlschlaegt:

1. Oeffnen Sie Einstellungen -> Abrechnung -> Plugin-Rechnungen, um die fehlgeschlagene Rechnung zu sehen.
2. Pruefen Sie Ihre Zahlungsmethode in Einstellungen -> Abrechnung -> Zahlungsmethoden. Aktualisieren Sie sie, falls abgelaufen.
3. Stripe versucht es automatisch nach seinem Standardplan erneut (4 Versuche ueber ca. 2 Wochen). Das Plugin bleibt waehrend der Wiederholungen aktiv.
4. Wenn alle Wiederholungen fehlschlagen, wird das Plugin deaktiviert (nicht deinstalliert - Ihre Konfiguration bleibt erhalten). Aktualisieren Sie Ihre Zahlungsmethode und reaktivieren Sie.

Abrechnung - bestrittene Belastung

Wenn Sie ueber Ihre Bank ein Chargeback einreichen, bearbeitet Stripe Connect den Streit im Namen von Levy:

1. Levy sammelt Beweise aus dem Audit-Protokoll des Plugins (zugestellte Ereignisse, getaetigte API-Aufrufe).
2. Der Anbieter kann ebenfalls Beweise einreichen.
3. Stripe trifft die endgueltige Entscheidung nach Netzwerkregeln.
4. Wenn der Streit zu Ihren Gunsten aufrechterhalten wird, werden sowohl der Anteil des Anbieters als auch die Plattformgebuehr von Levy zurueckgegeben.

Kontaktieren Sie support@levyelectric.com, wenn Sie Hilfe bei der Vorbereitung von Streitbeweisen benoetigen.

Token geleakt - was nun?

Konfigurationsaenderung wird nicht angewendet

Wenn Sie eine Konfigurationsaenderung speichern, tritt sie bei der naechsten Ereigniszustellung in Kraft - typischerweise innerhalb von Sekunden bis Minuten. Wenn Sie die Aenderung nicht widergespiegelt sehen:

• Pruefen Sie, ob Sie tatsaechlich auf Speichern geklickt haben (das Formular sollte seinen geaenderten Zustand loeschen).
• Bei OAuth-verbundenen Plugins erzwingt das erneute Ausfuehren von OAuth aus dem Konfigurations-Bildschirm einen frischen Token-Austausch.
• Pruefen Sie das Audit-Protokoll - jede configure-Aktion wird mit der neuen Konfiguration protokolliert. Wenn es fehlt, ist die Speicherung nicht durchgegangen.
• Fuer BigQuery / Snowflake werden Zeitplanaenderungen beim naechsten geplanten Lauf angewendet, nicht sofort.

Plugin funktioniert fuer einige Fahrten, aber nicht fuer andere

Plugins sind pro Subkonto skopiert. Wenn Sie mehrere Subkonten haben (z. B. eines pro Stadt), muessen Sie das Plugin separat in jedem installieren. Ein in Subkonto A installiertes Plugin verarbeitet keine Fahrten in Subkonto B.

Was kommt als naechstes

• Plugin konfigurieren - fuer routinemaessige Konfigurationsaenderungen
• Plugin-Abrechnung - abrechnungsspezifische Probleme
• FAQ - haeufige Fragen und schnelle Antworten