01
Token
POST /auth/token mit den Zugangsdaten des Brokers.
Für Entwickler
Broker-API von NoloForWeb: technische Referenz
Die Broker-API ist die REST-Schnittstelle, über die Broker, Agenturen und Reiseveranstalter Katalog, Verfügbarkeit und Preise eines Vermieters mit NoloForWeb lesen und direkt in dessen Kalender buchen. Der Vermieter schaltet jeden Broker mit eigenen Zugangsdaten und Rechten frei; Testzugänge auf Anfrage.
REST über HTTPS, JSON Idempotente Buchungen HMAC-SHA256-signierte Webhooks
Verbindung
Adresse, Authentifizierung und Limits
| Punkt | Wert |
|---|---|
| Basisadresse | https://brokerapi.rilogi.it/broker/v1 |
| Authentifizierung | Client Credentials über POST /auth/token (HTTP Basic, Formular oder JSON mit client_id brk_… und client_secret). Antwort: opakes access_token, token_type: Bearer, expires_in, scope. |
| Sitzung | 60 Minuten, ohne Refresh: Nach Ablauf wird ein neues Token angefordert. Höchstens 20 aktive Sitzungen je Zugang; POST /auth/revoke beendet die aktuelle. |
| Unternehmen | Ergibt sich nur aus dem Zugang: X-Tenant-*-Header werden ignoriert. |
| Rechte | Nach Bereich (Katalog, Verfügbarkeit, Buchungen, Finanzen, Konto) und Stufe (Lesen, Schreiben, Verwalten), vom Vermieter vergeben; in den Scopes etwa als bookings:write. |
| Sicherheit | Sperre des Zugangs für 15 Minuten nach 5 Fehlversuchen, optionale IP-Freigabeliste, Secret-Rotation mit Übergangsfrist. |
| Limits | 120 Anfragen pro Minute je Broker (vom Vermieter änderbar), 600 je Unternehmen, 10 pro Minute je IP auf /auth/token. Darüber: 429 mit Retry-After. |
| Fehler | JSON {error, message, correlationId}; jede Antwort trägt X-Correlation-Id. Login-Fehler folgen dem OAuth-Format {error, error_description}. |
Endpunkte
Verfügbare Aufrufe
| Methode und Pfad | Recht | Zweck |
|---|---|---|
GET /locations | Katalog, Lesen | Für den Broker freigegebene Stationen, mit Adresse und Flughafen ja/nein |
GET /vehicle-groups | Katalog, Lesen | Fahrzeuggruppen mit bis zu drei Beispielmodellen |
GET /extras?culture= | Katalog, Lesen | Buchbare Extras, in der angefragten Sprache beschrieben |
POST /availability | Verfügbarkeit, Lesen | Angebote zu den Tarifen des Vermieters, mit signiertem offerToken, 15 Minuten gültig |
GET /images/{token} | Signierter Link | Fotos der Modelle aus den Angeboten, mit ETag und einem Tag Cache |
POST /bookings | Buchungen, Schreiben | Bucht aus einem offerToken; Idempotency-Key Pflicht; antwortet 201 mit Location |
GET /bookings/{brokerReference} | Buchungen, Lesen | Liest eine Buchung |
PATCH /bookings/{brokerReference} | Buchungen, Schreiben | Ändert Daten, Extras, Fahrer oder Voucher |
POST /bookings/{brokerReference}/cancel | Buchungen, Verwalten | Storniert mit eventueller Gebühr; wiederholt, liefert es dasselbe Ergebnis |
GET /statements?from=&to= | Finanzen, Lesen | Kontoauszug des Brokers, höchstens ein Jahr pro Abruf |
GET /invoices | Finanzen, Lesen | An den Broker ausgestellte Rechnungen |
Listen sind nicht paginiert. Es gibt keinen Endpunkt, der Buchungen auflistet: Statusänderungen kommen per Webhook.
Idempotenz und Webhooks
Keine Dubletten, jede Änderung signiert
| Punkt | Funktionsweise |
|---|---|
Idempotency-Key | 1 bis 100 ASCII-Zeichen, eindeutig je Broker, 24 Stunden gültig. Gleicher Schlüssel und gleicher Body: Die gespeicherte Antwort kommt mit Idempotent-Replayed: true zurück. Anderer Body: 422 idempotency_key_reuse. Anfrage läuft noch: 409. |
| Ereignisse | booking.modified, booking.cancelled, booking.no_show, rental.closed |
| Umschlag | JSON {eventId, type, occurredAt, source, data}, mit source BACKOFFICE oder BROKER_API; Header X-N4W-Event-Id und X-N4W-Event-Type |
| Signatur | X-N4W-Signature: t=<unix>,v1=<hex>, wobei hex der HMAC-SHA256 mit dem Secret whsec_… über <t>. gefolgt vom rohen UTF-8-Body ist. Wir empfehlen, Zeitstempel älter als 5 Minuten abzulehnen. |
| Zustellung | Nur https-Adressen. Jeder 2xx gilt als empfangen, Timeout 10 Sekunden; bis zu 10 Versuche von 1 Minute bis 24 Stunden, mit derselben eventId (der Zeitstempel der Signatur ist bei jedem Versuch neu). |
Webhook-Adresse und Secret richtet der Vermieter in der Software ein: Es gibt keinen Endpunkt, um sie zu registrieren.
Der Ablauf
Eine Buchung in vier Aufrufen
02
Verfügbarkeit
POST /availability mit Stationen, Daten und Uhrzeiten: Jedes Angebot hat einen Preis und ein offerToken, 15 Minuten gültig.
03
Buchung
POST /bookings mit dem offerToken, den Fahrerdaten und einem Idempotency-Key: Ein erneuter Versuch erzeugt keine Dublette.
04
Aktualisierungen
Änderungen, Stornierungen, Nichterscheinen und Mietabschluss kommen als signierte Webhooks.
Testzugang gewünscht?
Schreiben Sie uns über die Kontaktseite: vollständige Spezifikation und Testzugang auf Anfrage.