01
Token
POST /auth/token con las credenciales del bróker.
Para desarrolladores
Broker API de NoloForWeb: referencia técnica
La Broker API es la interfaz REST con la que brókers, agencias y turoperadores leen el catálogo, la disponibilidad y los precios de una empresa de alquiler que usa NoloForWeb y reservan en su calendario. La empresa activa cada bróker con credenciales y permisos propios; credenciales de prueba bajo petición.
REST sobre HTTPS, JSON Reservas idempotentes Webhooks firmados con HMAC-SHA256
Conexión
Dirección, autenticación y límites
| Concepto | Valor |
|---|---|
| Dirección base | https://brokerapi.rilogi.it/broker/v1 |
| Autenticación | Client credentials en POST /auth/token (HTTP Basic, formulario o JSON con client_id brk_… y client_secret). Respuesta: access_token opaco, token_type: Bearer, expires_in, scope. |
| Sesión | 60 minutos, sin refresh: al caducar se pide un token nuevo. Como máximo 20 sesiones activas por credencial; POST /auth/revoke cierra la actual. |
| Empresa | Se obtiene solo de la credencial: las cabeceras X-Tenant-* se ignoran. |
| Permisos | Por área (catálogo, disponibilidad, reservas, finanzas, cuenta) y nivel (lectura, escritura, gestión), asignados por la empresa de alquiler; en los scopes aparecen como bookings:write. |
| Seguridad | Bloqueo de la credencial durante 15 minutos tras 5 intentos fallidos, lista opcional de IP permitidas, rotación del secret con periodo de gracia. |
| Límites | 120 peticiones por minuto por bróker (la empresa puede cambiarlas), 600 por empresa, 10 por minuto por IP en /auth/token. Por encima: 429 con Retry-After. |
| Errores | JSON {error, message, correlationId}; cada respuesta lleva X-Correlation-Id. Los errores de inicio de sesión siguen el formato OAuth {error, error_description}. |
Endpoints
Las llamadas disponibles
| Método y ruta | Permiso | Para qué sirve |
|---|---|---|
GET /locations | Catálogo, lectura | Oficinas habilitadas para el bróker, con dirección y aeropuerto sí/no |
GET /vehicle-groups | Catálogo, lectura | Grupos de vehículos con hasta tres modelos de ejemplo |
GET /extras?culture= | Catálogo, lectura | Extras reservables, descritos en el idioma pedido |
POST /availability | Disponibilidad, lectura | Ofertas con el precio de las tarifas de la empresa y un offerToken firmado válido 15 minutos |
GET /images/{token} | Enlace firmado | Fotos de los modelos incluidos en las ofertas, con ETag y caché de un día |
POST /bookings | Reservas, escritura | Reserva a partir de un offerToken; Idempotency-Key obligatoria; responde 201 con Location |
GET /bookings/{brokerReference} | Reservas, lectura | Lee una reserva |
PATCH /bookings/{brokerReference} | Reservas, escritura | Cambia fechas, extras, conductor o bono |
POST /bookings/{brokerReference}/cancel | Reservas, gestión | Cancela con la posible penalización; repetida, da el mismo resultado |
GET /statements?from=&to= | Finanzas, lectura | Extracto de cuenta del bróker, como máximo un año por llamada |
GET /invoices | Finanzas, lectura | Facturas emitidas al bróker |
Las listas no están paginadas. No hay un endpoint que liste las reservas: los cambios de estado llegan por webhook.
Idempotencia y webhooks
Sin duplicados, cada cambio firmado
| Concepto | Cómo funciona |
|---|---|
Idempotency-Key | De 1 a 100 caracteres ASCII, única por bróker, válida 24 horas. Misma clave y mismo cuerpo: vuelve la respuesta guardada con Idempotent-Replayed: true. Cuerpo distinto: 422 idempotency_key_reuse. Petición aún en curso: 409. |
| Eventos | booking.modified, booking.cancelled, booking.no_show, rental.closed |
| Sobre | JSON {eventId, type, occurredAt, source, data}, con source BACKOFFICE o BROKER_API; cabeceras X-N4W-Event-Id y X-N4W-Event-Type |
| Firma | X-N4W-Signature: t=<unix>,v1=<hex>, donde hex es el HMAC-SHA256, con el secret whsec_…, de <t>. seguido del cuerpo en bruto en UTF-8. Recomendamos rechazar marcas de tiempo de más de 5 minutos. |
| Entrega | Solo direcciones https. Cualquier 2xx cuenta como recibido, tiempo de espera de 10 segundos; hasta 10 intentos de 1 minuto a 24 horas, con el mismo eventId (la marca de tiempo de la firma cambia en cada intento). |
La dirección del webhook y su secret los configura la empresa de alquiler en el programa: no hay un endpoint para registrarlos.
El flujo
Una reserva en cuatro llamadas
02
Disponibilidad
POST /availability con oficinas, fechas y horas: cada oferta tiene precio y un offerToken válido 15 minutos.
03
Reserva
POST /bookings con el offerToken, los datos del conductor y una Idempotency-Key: un reintento no crea duplicados.
04
Actualizaciones
Cambios, cancelaciones, no presentaciones y cierre del alquiler llegan como webhooks firmados.
¿Necesitas credenciales de prueba?
Escríbenos desde la página de Contacto: especificaciones completas y credenciales de prueba bajo petición.