Partner-API-Integration

Die Partner-API ermoeglicht es externen Systemen, sich mit Levy Fleets zu integrieren und programmatischen Zugriff auf Fahrzeuge, Fahrten, Kunden, Zonen und Preisdaten zu ermoeglichen. Verwenden Sie Webhooks, um Echtzeit-Benachrichtigungen ueber Flottenereignisse zu erhalten.

Ueberblick

Die Partner-API bietet RESTful-Endpunkte zur programmatischen Verwaltung Ihrer Flotte. Alle Anfragen werden mit API-Schluesseln authentifiziert und basierend auf Ihrer Konfiguration ratenbegrenzt.

Hauptfunktionen

• RESTful-API - Standard-HTTP-Methoden und JSON-Antworten
• API-Schluessel-Authentifizierung - Sicherer Zugriff mit begrenzten Berechtigungen
• Ratenbegrenzung - Konfigurierbare Limits pro Minute, Stunde und Tag
• Webhooks - Echtzeit-Ereignisbenachrichtigungen mit Wiederholungslogik
• Anfrageprotokollierung - Vollstaendiger Audit-Trail der API-Nutzung

Basis-URL

https://app.levyelectric.com/api/partner/v1

Erste Schritte

API-Schluessel erstellen

API-Schluessel-Format

API-Schluessel verwenden das Format: lf_pk_<32 zufaellige Zeichen>

Beispiel: lf_pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Nur die ersten 12 Zeichen (Praefix) werden zur Anzeige gespeichert. Der vollstaendige Schluessel wird mit SHA-256 gehasht zur sicheren Speicherung.

Authentifizierung

Anfrage-Header

Alle API-Anfragen muessen den API-Schluessel-Header enthalten:

curl -X GET "https://app.levyelectric.com/api/partner/v1/vehicles" \
  -H "X-Partner-Api-Key: lf_pk_your_api_key_here" \
  -H "Content-Type: application/json"

Optionale Header

Authentifizierungsfehler

Berechtigungen

API-Schluesseln werden spezifische Berechtigungen erteilt, die steuern, welche Vorgaenge sie ausfuehren koennen.

Verfuegbare Berechtigungen

Standardberechtigungen

Neue API-Schluessel erhalten standardmaessig Lesezugriff:

• vehicles:read
• rides:read
• customers:read
• zones:read
• pricing:read

Schluesselumfaenge

Ratenbegrenzung

API-Anfragen sind ratenbegrenzt, um Missbrauch zu verhindern und faire Nutzung zu gewaehrleisten.

Standard-Limits

Antwort-Header

Ratenlimit-Status ist in Antwort-Headern enthalten:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2025-01-15T10:31:00Z

Ratenlimit ueberschritten

Wenn Limits ueberschritten werden, erhalten Sie eine 429-Antwort:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for minute window. Retry after 2025-01-15T10:31:00Z",
    "details": {
      "limit": 60,
      "window": "minute",
      "retry_after": 45
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:15Z"
  }
}

API-Endpunkte

Fahrzeuge

Fahrzeuge auflisten

GET /api/partner/v1/vehicles
GET /api/partner/v1/vehicles?status=available&limit=50

Fahrzeug abrufen

GET /api/partner/v1/vehicles/{id}

Fahrzeugstatus aktualisieren

PATCH /api/partner/v1/vehicles/{id}
{
  "status": "maintenance"
}

Fahrzeuge in der Naehe

GET /api/partner/v1/vehicles/nearby?lat=40.7128&lng=-74.0060&radius=500

Fahrten

Fahrten auflisten

GET /api/partner/v1/rides
GET /api/partner/v1/rides?status=active

Fahrt abrufen

GET /api/partner/v1/rides/{id}

Fahrt starten (erfordert rides:write)

POST /api/partner/v1/rides
{
  "customer_id": "uuid",
  "vehicle_id": "uuid"
}

Fahrt pausieren

POST /api/partner/v1/rides/{id}/pause

Fahrt fortsetzen

POST /api/partner/v1/rides/{id}/resume

Fahrt beenden

POST /api/partner/v1/rides/{id}/end
{
  "end_latitude": 40.7128,
  "end_longitude": -74.0060
}

Kunden

Kunden auflisten

GET /api/partner/v1/customers
GET /api/partner/v1/customers?email=user@example.com

Kunden abrufen

GET /api/partner/v1/customers/{id}

Wallet-Guthaben abrufen

GET /api/partner/v1/customers/{id}/wallet

Wallet gutschreiben (erfordert wallet:write)

POST /api/partner/v1/customers/{id}/wallet
{
  "action": "credit",
  "amount_cents": 1000,
  "description": "Aktionsguthaben"
}

Zonen

Zonen auflisten

GET /api/partner/v1/zones
GET /api/partner/v1/zones?type=parking

Preise

Preise abrufen

GET /api/partner/v1/pricing

Antwortformat

Erfolgsantwort

{
  "data": {
    "id": "uuid",
    "vehicle_number": "V001",
    "status": "available"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Listenantwort

{
  "data": [
    { "id": "uuid-1", "vehicle_number": "V001" },
    { "id": "uuid-2", "vehicle_number": "V002" }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 125,
    "has_next": true,
    "has_prev": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fehlerantwort

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Vehicle not found",
    "details": {
      "vehicle_id": "uuid"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Webhooks

Webhooks senden Echtzeit-HTTP-POST-Anfragen an Ihren Server, wenn Ereignisse auftreten.

Webhooks einrichten

Webhook-Ereignisse

Webhook-Payload

{
  "event": "ride.ended",
  "event_id": "evt_abc123def456",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "ride_id": "uuid",
    "customer_id": "uuid",
    "customer_number": 12345,
    "vehicle_id": "uuid",
    "vehicle_number": "V001",
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": "2025-01-15T10:30:00Z",
    "duration_minutes": 30,
    "distance_km": 5.2,
    "pricing": {
      "total_cents": 850,
      "unlock_cents": 100,
      "time_cents": 750,
      "distance_cents": 0,
      "discount_cents": 0
    },
    "payment_status": "paid",
    "subaccount_id": "uuid"
  }
}

Webhook-Signatur

Webhooks werden mit HMAC-SHA256 zur Sicherheitsverifizierung signiert.

Signatur-Header:

X-Levy-Signature: t=1705312200,v1=abc123...

Verifizierung (Node.js-Beispiel):

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const parts = signature.split(',')
  const timestamp = parts.find(p => p.startsWith('t=')).substring(2)
  const expectedSig = parts.find(p => p.startsWith('v1=')).substring(3)

  // Pruefen, ob Zeitstempel aktuell ist (innerhalb von 5 Minuten)
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp)
  if (age > 300) return false

  // Signatur berechnen
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`
  const computedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  return computedSig === expectedSig
}

Wiederholungslogik

Fehlgeschlagene Webhook-Zustellungen werden automatisch wiederholt:

Nach 5 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert.

API-Schluessel-Verwaltung

Schluessel neu generieren

Wenn ein Schluessel kompromittiert ist:

1. Gehen Sie zu Einstellungen → Integrationen
2. Finden Sie den API-Schluessel
3. Klicken Sie auf Neu generieren
4. Aktualisieren Sie Ihre Systeme mit dem neuen Schluessel
5. Der alte Schluessel wird sofort ungueltig

Schluessel deaktivieren

Schluessel voruebergehend deaktivieren, ohne ihn zu loeschen:

1. Finden Sie den API-Schluessel
2. Schalten Sie Aktiv auf aus
3. Alle Anfragen mit diesem Schluessel geben 401 zurueck

Nutzung anzeigen

API-Schluessel-Aktivitaet ueberwachen:

• Zuletzt verwendet - Wann der Schluessel zuletzt verwendet wurde
• Anfragen heute - Anzahl der heutigen Anfragen
• Anfragen diese Woche/diesen Monat - Historische Nutzung

Best Practices

Sicherheit

1. Schluessel sicher speichern - Umgebungsvariablen verwenden, nicht im Code
2. HTTPS verwenden - Alle API-Aufrufe muessen HTTPS verwenden
3. Webhooks verifizieren - Webhook-Signaturen immer validieren
4. Schluessel rotieren - Schluessel regelmaessig neu generieren
5. Minimale Berechtigungen - Nur notwendige Berechtigungen erteilen

Leistung

1. Paginierung verwenden - Kleinere Seiten fuer grosse Listen anfordern
2. Antworten cachen - Nur-Lesen-Daten angemessen cachen
3. Ratenlimits behandeln - Exponentielles Backoff implementieren
4. Webhooks verwenden - Webhooks statt Polling bevorzugen

Fehlerbehandlung

1. Antwortcodes pruefen - 4xx- und 5xx-Fehler behandeln
2. Request-IDs verwenden - request_id fuer Debugging protokollieren
3. Transiente Fehler wiederholen - 5xx-Fehler mit Backoff wiederholen
4. Fehler ueberwachen - Bei wiederholten Webhook-Fehlern alarmieren

Fehlerbehebung

Authentifizierungsfehler

Webhook-Probleme

Ratenlimit-Probleme

SDK-Beispiele

Node.js

const axios = require('axios')

const api = axios.create({
  baseURL: 'https://app.levyelectric.com/api/partner/v1',
  headers: {
    'X-Partner-Api-Key': process.env.LEVY_API_KEY,
    'Content-Type': 'application/json'
  }
})

// Verfuegbare Fahrzeuge auflisten
const { data } = await api.get('/vehicles', {
  params: { status: 'available' }
})

console.log(data.data) // Array von Fahrzeugen

Python

import requests
import os

API_KEY = os.environ['LEVY_API_KEY']
BASE_URL = 'https://app.levyelectric.com/api/partner/v1'

headers = {
    'X-Partner-Api-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Ein bestimmtes Fahrzeug abrufen
response = requests.get(
    f'{BASE_URL}/vehicles/uuid-here',
    headers=headers
)

vehicle = response.json()['data']
print(f"Fahrzeug {vehicle['vehicle_number']}: {vehicle['status']}")