Erste Schritte

Die öffentliche API unterstützt derzeit Rental. Ihr System kann Fahrzeuge und Mietvorgänge synchronisieren, Inspektionen vorbereiten und validierte Ergebnisse abrufen. Die API-Referenz ist der verbindliche Vertrag für jede Anfrage und Antwort.

1. Schlüssel erstellen

Ein Administrator der Organisation öffnet in der TrakarIA-Anwendung API & Integrationen und erstellt einen API-Schlüssel. Der API-Zugang hängt vom Rental-Tarif der Organisation ab. Verwenden Sie für jede Integration einen eigenen Schlüssel; das vollständige Geheimnis wird nur einmal angezeigt. Weitere Informationen: Authentifizierung.

Die Basis-URL lautet https://api.trakaria.com. Anfragen mit Ihrem Schlüssel wirken sich auf die echten Daten Ihres Kontos aus.

2. Zugriff und wirksame Limits prüfen

Legen Sie den Schlüssel in Ihrem Terminal fest, ohne ihn in die Versionsverwaltung zu übernehmen, und senden Sie zunächst eine schreibgeschützte Anfrage:

export TRAKARIA_API_KEY='your-api-key'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  https://api.trakaria.com/v1/capabilities

Die Antwort enthält die aktuell verfügbaren Rental-Funktionen und Limits Ihrer Organisation. 401 bedeutet, dass der Schlüssel ungültig oder abgelaufen ist. 403 kann bedeuten, dass der Vorgang oder Tarif nicht verfügbar ist. Siehe Fehler und Zuverlässigkeit.

3. Fahrzeug und Mietvorgang synchronisieren

Verwenden Sie für einen Test eindeutige externe Kennungen, die Sie später wiederfinden, und vermeiden Sie echte Kundendaten. Die folgenden Aufrufe erzeugen Datensätze in Ihrem Konto. Ersetzen Sie die Beispielwerte. Wenn Sie dieselbe externe Kennung wiederverwenden, aktualisieren Sie dieselbe Ressource. Speichern Sie die zurückgegebenen öffentlichen id-Werte für spätere Aufrufe.

curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/vehicles/by-external/demo-vehicle-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"plate":"AA-123-AA","name":"Airport car","photo_url":"https://cdn.example.com/fleet/demo-vehicle-001.jpg","make":"Example","model":"Car","trim":"Business","year":2025,"registration_date":"2025-03-20","vehicle_type":"hatchback","energy":"petrol","gearbox":"automatic","transmission":"fwd","color":"Blue","mileage":12000,"source_revision":1}'

curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/rentals/by-external/demo-reservation-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"vehicle_external_id":"demo-vehicle-001","source_revision":1}'

Die zweite Anfrage erzeugt sofort einen sichtbaren Planungseintrag. Die Antwort enthält sowohl die Rental-id als auch planning.entry_id. Im Anfragetext ist nur vehicle_external_id erforderlich. Geplante Zeiten, Referenzen, Standorte, Kontakt und Fahrer sind optional und können im Voraus, bei der tatsächlichen Fahrzeugübergabe oder später übermittelt werden. Fehlt die Abfahrtszeit, verwendet TrakarIA den Erstellungszeitpunkt; ohne Rückgabezeit bleibt der Planungseintrag offen.

Verwenden Sie bei späteren inhaltlichen Änderungen eine streng steigende source_revision. Nicht übermittelte Felder behalten ihren aktuellen Wert. Derselbe Planungseintrag wird aktualisiert und nicht dupliziert. Siehe Synchronisierungsregeln.

Ein erfolgreiches Fahrzeug-Upsert weist das Fahrzeug außerdem der Organisation des API-Schlüssels zu. Berechtigte Benutzer dieser Gruppe können es danach in TrakarIA sehen. Ein unverändertes Upsert kann sicher wiederholt werden und stellt die Zuordnung wieder her, falls sie fehlte.

Prüfen Sie nach einem Test die Datensätze in TrakarIA und bereinigen Sie sie mit den Aktionen, die Ihrer Gruppe zur Verfügung stehen. Die öffentliche API kann einen Mietvorgang vor der Abfahrt mit POST /v1/rentals/{rental_id}/cancel stornieren; dadurch wird auch sein Planungseintrag storniert. Es gibt keine allgemeine DELETE-Route für Fahrzeuge oder Mietvorgänge. Eine Stornierung löscht den Verlauf nicht.

4. Inspektionsablauf fortsetzen

Verwenden Sie die von der zweiten Anfrage zurückgegebene öffentliche Rental-id — nicht die externe Kennung oder die Planungskennung — um die Abfahrtsinspektion vorzubereiten. Die geplante Abfahrt darf in der Zukunft liegen.

export RENTAL_ID='rental_...'
export DEPARTURE_IDEMPOTENCY_KEY="departure-${RENTAL_ID}"

curl --fail-with-body --silent --show-error \
  -X POST "https://api.trakaria.com/v1/rentals/${RENTAL_ID}/inspections" \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${DEPARTURE_IDEMPOTENCY_KEY}" \
  -d '{"type":"departure"}'

Dieser Aufruf bereitet dieselbe Inspektion vor oder setzt sie fort: 201 bedeutet, dass sie erstellt wurde; 200 bedeutet, dass sie bereits bestand. Wiederholen Sie nach Timeout, Verbindungsabbruch, 503 oder REQUEST_ALREADY_PROCESSING dieselbe Methode, denselben Pfad und denselben Inhalt mit demselben Idempotency-Key. Erstellen Sie keinen weiteren Mietvorgang und keine andere externe Kennung. Senden Sie niemals Kernel-Zykluskennungen, Revisionen, ETag, If-Match oder expectedRevision; TrakarIA verwaltet diese privaten Parallelitätsdetails.

Ein TrakarIA-Benutzer muss sich anmelden, um die zurückgegebene launch_url zu öffnen und den Fahrzeugzustand zu validieren. Der API-Aufruf führt diese menschliche Validierung nicht durch. Rufen Sie nach der Validierung den Abfahrtsbericht ab; bereiten Sie nach der Rückgabe eine Inspektion vom Typ return vor und laden Sie den Vergleichsbericht. Folgen Sie dem vollständigen Rental-Ablauf und der genauen API-Referenz. Sie können außerdem signierte Webhooks empfangen und verpasste Ereignisse über GET /v1/events nachholen.