Per sviluppatori

Broker API di NoloForWeb: reference tecnica

La Broker API è l'interfaccia REST con cui broker, agenzie e tour operator leggono catalogo, disponibilità e prezzi di un noleggiatore che usa NoloForWeb e prenotano nel suo calendario. Il noleggiatore attiva ogni broker con credenziali e permessi propri; credenziali di prova su richiesta.

Richiedi una demo

REST su HTTPS, JSON Prenotazioni idempotenti Webhook firmati HMAC-SHA256

Connessione

Indirizzo, autenticazione e limiti

Voce	Valore
Indirizzo base	`https://brokerapi.rilogi.it/broker/v1`
Autenticazione	Client credentials su `POST /auth/token` (HTTP Basic, form o JSON con `client_id` `brk_…` e `client_secret`). Risposta: `access_token` opaco, `token_type: Bearer`, `expires_in`, `scope`.
Sessione	60 minuti, senza refresh: alla scadenza si chiede un token nuovo. Al massimo 20 sessioni attive per credenziale; `POST /auth/revoke` chiude quella corrente.
Azienda	Ricavata solo dalla credenziale: le intestazioni `X-Tenant-*` vengono ignorate.
Permessi	Per area (catalogo, disponibilità, prenotazioni, finanza, account) e livello (lettura, scrittura, gestione), assegnati dal noleggiatore; negli scope compaiono come `bookings:write`.
Sicurezza	Blocco della credenziale dopo 5 tentativi falliti per 15 minuti, lista di IP ammessi facoltativa, rotazione del secret con periodo di grazia.
Limiti	120 richieste al minuto per broker (il noleggiatore può cambiarle), 600 per azienda, 10 al minuto per IP su `/auth/token`. Oltre: 429 con `Retry-After`.
Errori	JSON `{error, message, correlationId}`; ogni risposta porta `X-Correlation-Id`. Gli errori di login seguono il formato OAuth `{error, error_description}`.

Endpoint

Le chiamate disponibili

Metodo e percorso	Permesso	A cosa serve
`GET /locations`	Catalogo, lettura	Stazioni abilitate per il broker, con indirizzo e aeroporto sì/no
`GET /vehicle-groups`	Catalogo, lettura	Gruppi di veicoli con fino a tre modelli d'esempio
`GET /extras?culture=`	Catalogo, lettura	Extra prenotabili, con le descrizioni nella lingua chiesta
`POST /availability`	Disponibilità, lettura	Offerte con prezzo dal listino del noleggiatore e `offerToken` firmato valido 15 minuti
`GET /images/{token}`	Link firmato	Foto dei modelli presenti nelle offerte, con `ETag` e cache di un giorno
`POST /bookings`	Prenotazioni, scrittura	Prenota da un `offerToken`; `Idempotency-Key` obbligatoria; risponde 201 con `Location`
`GET /bookings/{brokerReference}`	Prenotazioni, lettura	Legge una prenotazione
`PATCH /bookings/{brokerReference}`	Prenotazioni, scrittura	Cambia date, extra, conducente o voucher
`POST /bookings/{brokerReference}/cancel`	Prenotazioni, gestione	Annulla con l'eventuale penale; ripetuta, dà lo stesso esito
`GET /statements?from=&to=`	Finanza, lettura	Estratto conto del broker, al massimo un anno per volta
`GET /invoices`	Finanza, lettura	Fatture emesse al broker

Gli elenchi non sono paginati. Non esiste un endpoint che elenca le prenotazioni: lo stato arriva con i webhook.

Idempotenza e webhook

Nessun doppione, ogni cambiamento firmato

Voce	Come funziona
`Idempotency-Key`	Da 1 a 100 caratteri ASCII, unica per broker, valida 24 ore. Stessa chiave e stesso corpo: torna la risposta salvata con `Idempotent-Replayed: true`. Corpo diverso: 422 `idempotency_key_reuse`. Richiesta ancora in corso: 409.
Eventi	`booking.modified`, `booking.cancelled`, `booking.no_show`, `rental.closed`
Busta	JSON `{eventId, type, occurredAt, source, data}`, con `source` `BACKOFFICE` o `BROKER_API`; intestazioni `X-N4W-Event-Id` e `X-N4W-Event-Type`
Firma	`X-N4W-Signature: t=<unix>,v1=<hex>`, dove hex è HMAC-SHA256 con il secret `whsec_…` di `<t>.` seguito dal corpo grezzo in UTF-8. Consigliato rifiutare timestamp più vecchi di 5 minuti.
Consegna	Indirizzo solo https. Qualsiasi 2xx vale come ricevuto, timeout 10 secondi; fino a 10 tentativi da 1 minuto a 24 ore, con lo stesso `eventId` (il timestamp della firma è nuovo a ogni tentativo).

L'indirizzo del webhook e il suo secret li configura il noleggiatore nel gestionale: non c'è un endpoint per registrarli.

Il flusso

Una prenotazione in quattro chiamate

Token

POST /auth/token con le credenziali del broker.

Disponibilità

POST /availability con stazioni, date e orari: ogni offerta ha prezzo e offerToken valido 15 minuti.

Prenotazione

POST /bookings con l'offerToken, i dati del conducente e una Idempotency-Key: un ritentativo non crea doppioni.

Aggiornamenti

Modifiche, annullamenti, mancate presentazioni e chiusura del noleggio arrivano come webhook firmati.

Ti servono credenziali di prova?

Scrivici dalla pagina Contatti: specifiche complete e credenziali di prova su richiesta.

Richiedi una demo