TRANSCEND SDK für Python und JavaScript: Maut und Route ins TMS

Die meisten Flotten rechnen Maut noch in Tabellenkalkulationen – ein Vorgang von sechs bis zehn Minuten pro Tour, der bei 2.500 Touren im Jahr über 250 Arbeitsstunden bindet. Ein SDK ersetzt diesen Schritt durch einen Aufruf: Fahrzeugprofil, Start, Ziel und Zeit hinein, Kostensatz je Ladung heraus. Dieser Artikel zeigt die Endpunkte, die Auth-Logik, die Fehlerfälle und den Aufwand für die Anbindung. Alle Angaben beziehen sich auf die TRANSCEND-API 2026.

Was leistet das SDK und was nicht?

Das SDK ist eine dünne, typisierte Hülle um die REST-API. Es übernimmt Authentifizierung, Retries und die Umwandlung der Antworten in native Objekte – in Python als dataclasses, in JavaScript als typisierte Objekte.

• Es rechnet: Maut je Land und Abschnitt, Route samt Fahrzeit, Kraftstoffschätzung, Zeitfensterkonflikte.
• Es dokumentiert: jede Kalkulation ist mit Zeitstempel und Tarifstand versioniert abrufbar.
• Es entscheidet nicht: Routenfreigabe, Fahrerzuordnung und Freigabe von Angeboten bleiben in Ihrem System.
• Es speichert nicht dauerhaft mehr als die Kalkulationshistorie Ihrer Organisation.

Wie authentifiziere ich mich korrekt?

Die API nutzt API-Keys mit Bearer-Authentifizierung, in der Regel ein Key pro Umgebung und pro Integration.

• Zwei Keys parallel: einer für Produktion, einer für die Sandbox. Keys werden nie im Frontend oder im Fahrzeuggerät hinterlegt.
• Scopes: tolls:read, routes:write, vehicles:read, ecmr:write – ein Reporting-Skript braucht kein Schreibrecht auf Dokumente.
• Rotation: empfohlen alle 90 Tage, mit Überlappungsfenster von 14 Tagen für unterbrechungsfreien Wechsel.
• IP-Allowlist: für Server-zu-Server-Integrationen dringend empfohlen; verhindert Missbrauch bei Key-Verlust.
• Ablauf: Keys laufen nicht automatisch ab, werden aber bei Verdacht sofort invalidiert.

Welche Endpunkte brauche ich für eine Tourkalkulation?

Vier Aufrufe genügen für den Standardfall; die übrigen sind Ergänzung.

Die Antwort von tolls/calculate enthält immer eine Aufschlüsselung: Summe in Euro, Anteil je Land, Anteil je Bauwerk, Maut pro Kilometer und das Gültigkeitsdatum des Tarifstands.

Wie sieht der Aufruf in Python aus?

Der Ablauf ist in beiden Sprachen identisch: Client erzeugen, Fahrzeugprofil referenzieren, Kalkulation auslösen, Ergebnis prüfen.

• Client: Transcend(api_key=...) mit optionaler Basis-URL für die Sandbox.
• Fahrzeug: entweder eine gespeicherte Fahrzeug-ID aus vehicles oder ein Inline-Profil mit Achsen, Höhe, Gesamtgewicht und Emissionsklasse.
• Route: Start und Ziel als Koordinaten oder als strukturierte Adresse, optional Zwischenstopps und Ankunftszeit.
• Optionen: include_breakdown für die Länderaufschlüsselung, currency für die Ausgabewährung, valid_at für einen abweichenden Buchungszeitpunkt.
• Ergebnis: total_eur, per_km, breakdown[], tariff_version, warnings[] – Warnungen erscheinen etwa bei fehlendem Mautabschnitt oder unplausibler Achsenzahl.

In der Praxis sind es rund 40 Zeilen Code inklusive Fehlerbehandlung für einen vollständigen Angebots-Endpunkt.

Wie sieht derselbe Aufruf in JavaScript aus?

Für Node.js und TypeScript ist die Struktur identisch, nur asynchron:

• Client: createClient({ apiKey }) mit optionalem Timeout von 8 Sekunden.
• Aufruf: await client.tolls.calculate({ vehicleId, origin, destination, departAt }).
• Typen: die Antwort ist als TollCalculation typisiert; breakdown ist ein Array mit Land, Abschnitt und Betrag.
• Bündelung: für mehrere Touren client.tolls.calculateMany([...]) mit maximal 50 Kalkulationen pro Anfrage.
• Browser: nicht für Produktions-Keys geeignet – Aufrufe laufen über Ihren Server, nicht aus dem Browser.

Wie gehe ich mit Fehlern, Limits und Doppelbuchungen um?

Das ist der Teil, der über Produktionsreife entscheidet:

• 429 Too Many Requests: Retry-After respektieren, dann exponentiell zurückweichen (1 s, 2 s, 4 s, maximal 30 s).
• 5xx: bis zu drei Wiederholungen mit Idempotency-Key, damit keine doppelte Kalkulation entsteht.
• 4xx: nicht wiederholen; 422 bedeutet meist ein unplausibles Profil, etwa Höhe 0 oder 9 Achsen.
• Timeouts: 8 Sekunden Client-Timeout, danach kontrollierter Abbruch mit Fallback auf den letzten gültigen Tarifstand.
• Wartung: geplante Fenster werden über einen Header angekündigt; das SDK liefert sie im Feld maintenance_window.

Wie teste ich, bevor ich live gehe?

Die Sandbox bildet die Produktionsantworten mit festen Tarifständen nach und liefert deterministische Ergebnisse – ideal für Tests und Abnahmen.

• Eigene Basis-URL und eigene Keys, kein Zugriff auf Echtdaten.
• Feste Fixtures für fünf Referenztouren, damit Regressionstests stabil bleiben.
• 500 Kalkulationen pro Monat kostenlos im Sandbox-Tarif.
• Fehlerinjektion über einen Header, um 429- und 5xx-Pfade zu testen, ohne die API zu belasten.

Was kostet die Anbindung an Zeit und Geld?

Erfahrungswerte für eine Flotte mit 18 Fahrzeugen und einem bestehenden TMS:

Dem stehen bei 2.500 Touren im Jahr rund 250 eingesparte Arbeitsstunden gegenüber, dazu 2 bis 5 % weniger Fehlbuchungen durch manuelle Schätzungen.

FAQ

Brauche ich für Python und JavaScript unterschiedliche Keys? Nein, der Key ist sprachunabhängig. Empfohlen sind getrennte Keys je Umgebung und je Integration, nicht je Sprache.

Wie oft ändern sich die Tarifstände? Die API aktualisiert Tarife in der Regel monatlich, bei Gesetzesänderungen sofort. Jede Antwort nennt den verwendeten Tarifstand mit Datum.

Was passiert, wenn ein Land nicht abgedeckt ist? Die Kalkulation liefert eine Warnung und den Preis für die abgedeckten Abschnitte; sie bricht nicht ab. So bleibt das Angebot kalkulierbar.

Kann ich die Kalkulation in mein eigenes Angebots-PDF übernehmen? Ja, die Aufschlüsselung je Land und Abschnitt ist als strukturierte Liste verfügbar und lässt sich direkt in Vorlagen einsetzen.

Ist die API DSGVO-konform nutzbar? Für die Kalkulation werden keine personenbezogenen Fahrerdaten benötigt – nur Fahrzeugprofil und Route. Fahrerbezug entsteht erst, wenn Sie ihn selbst hinzufügen.

Fazit: Rechnen gehört in die Software, nicht in die Tabelle

Ein SDK lohnt sich nicht, weil es modern ist, sondern weil es den sechsminütigen Rechenschritt pro Tour abschafft und Tarifstände versioniert. Der Aufwand liegt bei drei bis fünf Tagen, der Nutzen bei 250 Stunden im Jahr. Wie die API in einer Demo mit Ihren eigenen Fahrzeugprofilen läuft, zeigt die Live-Demo; die Systematik steht unter So funktioniert es, Tarife inklusive API-Kontingente unter Preise.