Pour développeurs

Broker API de NoloForWeb : référence technique

La Broker API est l'interface REST par laquelle brokers, agences et tour-opérateurs lisent le catalogue, les disponibilités et les prix d'un loueur qui utilise NoloForWeb et réservent dans son calendrier. Le loueur active chaque broker avec ses propres identifiants et droits ; identifiants de test sur demande.

Demander une démo

REST sur HTTPS, JSON Réservations idempotentes Webhooks signés HMAC-SHA256

Connexion

Adresse, authentification et limites

Élément	Valeur
Adresse de base	`https://brokerapi.rilogi.it/broker/v1`
Authentification	Client credentials sur `POST /auth/token` (HTTP Basic, formulaire ou JSON avec `client_id` `brk_…` et `client_secret`). Réponse : `access_token` opaque, `token_type: Bearer`, `expires_in`, `scope`.
Session	60 minutes, sans rafraîchissement : à l'échéance, on demande un nouveau jeton. Au maximum 20 sessions actives par identifiant ; `POST /auth/revoke` ferme la session courante.
Entreprise	Déduite uniquement de l'identifiant : les en-têtes `X-Tenant-*` sont ignorés.
Droits	Par domaine (catalogue, disponibilités, réservations, finance, compte) et niveau (lecture, écriture, gestion), attribués par le loueur ; dans les scopes ils apparaissent comme `bookings:write`.
Sécurité	Identifiant bloqué 15 minutes après 5 échecs, liste d'IP autorisées facultative, rotation du secret avec période de grâce.
Limites	120 requêtes par minute par broker (modifiables par le loueur), 600 par entreprise, 10 par minute et par IP sur `/auth/token`. Au-delà : 429 avec `Retry-After`.
Erreurs	JSON `{error, message, correlationId}` ; chaque réponse porte `X-Correlation-Id`. Les erreurs de connexion suivent le format OAuth `{error, error_description}`.

Endpoints

Les appels disponibles

Méthode et chemin	Droit	À quoi il sert
`GET /locations`	Catalogue, lecture	Agences ouvertes au broker, avec adresse et aéroport oui/non
`GET /vehicle-groups`	Catalogue, lecture	Groupes de véhicules avec jusqu'à trois modèles d'exemple
`GET /extras?culture=`	Catalogue, lecture	Options réservables, décrites dans la langue demandée
`POST /availability`	Disponibilités, lecture	Offres au prix de la grille du loueur, avec un `offerToken` signé valable 15 minutes
`GET /images/{token}`	Lien signé	Photos des modèles présents dans les offres, avec `ETag` et cache d'un jour
`POST /bookings`	Réservations, écriture	Réserve à partir d'un `offerToken` ; `Idempotency-Key` obligatoire ; répond 201 avec `Location`
`GET /bookings/{brokerReference}`	Réservations, lecture	Lit une réservation
`PATCH /bookings/{brokerReference}`	Réservations, écriture	Modifie dates, options, conducteur ou voucher
`POST /bookings/{brokerReference}/cancel`	Réservations, gestion	Annule avec l'éventuelle pénalité ; répétée, donne le même résultat
`GET /statements?from=&to=`	Finance, lecture	Relevé de compte du broker, un an au maximum par appel
`GET /invoices`	Finance, lecture	Factures émises au broker

Les listes ne sont pas paginées. Aucun endpoint ne liste les réservations : les changements d'état arrivent par webhook.

Idempotence et webhooks

Pas de doublons, chaque changement signé

Élément	Fonctionnement
`Idempotency-Key`	De 1 à 100 caractères ASCII, unique par broker, valable 24 heures. Même clé et même corps : la réponse enregistrée revient avec `Idempotent-Replayed: true`. Corps différent : 422 `idempotency_key_reuse`. Requête encore en cours : 409.
Événements	`booking.modified`, `booking.cancelled`, `booking.no_show`, `rental.closed`
Enveloppe	JSON `{eventId, type, occurredAt, source, data}`, avec `source` `BACKOFFICE` ou `BROKER_API` ; en-têtes `X-N4W-Event-Id` et `X-N4W-Event-Type`
Signature	`X-N4W-Signature: t=<unix>,v1=<hex>`, où hex est le HMAC-SHA256, avec le secret `whsec_…`, de `<t>.` suivi du corps brut en UTF-8. Nous conseillons de refuser les horodatages de plus de 5 minutes.
Livraison	Adresse https uniquement. Tout 2xx vaut réception, délai de 10 secondes ; jusqu'à 10 tentatives de 1 minute à 24 heures, avec le même `eventId` (l'horodatage de la signature change à chaque tentative).

L'adresse du webhook et son secret sont configurés par le loueur dans le logiciel : aucun endpoint ne permet de les enregistrer.

Le parcours

Une réservation en quatre appels

Jeton

POST /auth/token avec les identifiants du broker.

Disponibilités

POST /availability avec agences, dates et horaires : chaque offre a un prix et un offerToken valable 15 minutes.

Réservation

POST /bookings avec l'offerToken, les données du conducteur et une Idempotency-Key : une nouvelle tentative ne crée pas de doublon.

Mises à jour

Modifications, annulations, non-présentations et clôture de la location arrivent en webhooks signés.

Besoin d'identifiants de test ?

Écrivez-nous depuis la page Contact : spécifications complètes et identifiants de test sur demande.

Demander une démo