Quick start

Questa guida ti porta da zero alla tua prima richiesta autenticata in circa 5 minuti: ottenere un token, fare una GET reale, leggere la risposta, paginare e capire gli errori.

Prima di iniziare

Ti serve un utente API di Rently (con permessi per usare l'API) e l'URL della tua istanza. In Rently ogni cliente (tenant) risiede sul proprio host, per esempio https://tu-empresa.rently.com.ar. L'host identifica il tenant, quindi usa sempre l'host della tua istanza in ogni chiamata.

In questa guida usiamo https://{tenant}.rently.com.ar come esempio. Sostituiscilo con l'host del tuo tenant.

1. Ottenere un token

L'API si autentica con un token Bearer OAuth2. Per ottenerlo, fai una POST a /auth/token con le tue credenziali usando il grant client_credentials. Il tuo utente API è il client_id e la tua chiave è il client_secret.

curl -X POST https://{tenant}.rently.com.ar/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_USERNAME" \
  -d "client_secret=YOUR_PASSWORD"

La risposta è un JSON con il token:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...",
  "token_type": "bearer",
  "expires_in": 86399
}

Campo	Descrizione
`access_token`	Il token che invii in ogni richiesta successiva.
`token_type`	Sempre `bearer`. Definisce lo schema dell'header `Authorization`.
`expires_in`	Validità del token in secondi (≈ 1 giorno).

Riutilizza il token

Il token vale circa un giorno (expires_in ≈ 86399 secondi). Salvalo e riutilizzalo invece di richiederne uno nuovo a ogni richiesta. Quando scade, richiedine un altro.

Il token è legato al tenant

Il token è valido solo contro lo stesso host con cui lo hai richiesto. Se usi un token contro l'host di un altro tenant, l'API risponde 403. Richiedi sempre il token e fai le chiamate contro lo stesso host.

2. La tua prima richiesta autenticata

Con l'access_token, aggiungi l'header Authorization: Bearer {token} a qualsiasi endpoint dell'API. Iniziamo con una GET semplice e senza parametri: elencare le filiali della tua istanza con GET /api/branchoffices.

curl https://{tenant}.rently.com.ar/api/branchoffices \
  -H "Authorization: Bearer YOUR_TOKEN"

Risposta (array di filiali):

[
  {
    "Id": 1,
    "BusinessName": "Rently LAX Airport",
    "Name": "LAX Branch",
    "Street": "123 Airport Road",
    "Number": "Terminal 1",
    "City": "Los Angeles",
    "Country": "United States",
    "PostalCode": "90045",
    "Latitude": 33.9416,
    "Longitude": -118.4085,
    "Telephone": "+1-213-555-0123",
    "Email": "lax@rently.com",
    "IATACode": "LAX",
    "IsFranchise": false,
    "PublicWebSite": "https://rently.com/locations/lax"
  }
]

Lingua della risposta

Alcuni endpoint accettano un parametro Language per fissare la lingua dei testi della risposta; per esempio, GET /api/search lo supporta. Il valore accetta il nome di cultura completo (es-AR, en-US, pt) o il codice ISO di due lettere (es, en). Se lo ometti, si usa la lingua predefinita della tua istanza. Consulta il riferimento dell'API per vedere quali endpoint lo accettano.

Fatto: questa è la tua prima chiamata autenticata. Ogni volta che ricevi un 200, stai già operando contro l'API.

3. Una GET con paginazione

Gli elenchi grandi arrivano paginati. Vediamo GET /api/bookings/list, che restituisce le prenotazioni in blocchi. Accetta questi parametri di query:

Parametro	Default	Descrizione
`offset`	`0`	Cursore di paginazione. Nella prima chiamata, `0`.
`limit`	`30`	Quantità di elementi per pagina.
`status`	—	Filtro opzionale per stato della prenotazione.
`sortDirectionAsc`	`true`	Direzione di ordinamento.

curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=0&limit=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

La risposta racchiude i risultati in una struttura paginata:

{
  "Offset": 0,
  "Limit": 30,
  "Total": 1,
  "Results": [
    {
      "Id": 1,
      "IsQuotation": false,
      "Balance": 0.0,
      "TotalPayed": 0.0
    }
  ],
  "NextOffset": 0
}

Campo	Descrizione
`Offset` / `Limit`	L'offset e il limite applicati a questa pagina.
`Total`	Quantità totale di record disponibili.
`Results`	L'array di elementi di questa pagina (può arrivare `null` se non ci sono risultati).
`NextOffset`	L'`offset` da inviare nella chiamata successiva per ottenere la pagina seguente.

Come iterare le pagine

Per scorrere tutte le pagine, prendi il NextOffset di ogni risposta e passalo come offset nella successiva. L'iterazione termina quando Results contiene meno elementi di Limit.

# Pagina successiva: usa il NextOffset restituito dalla risposta precedente
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=NEXT_OFFSET&limit=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Gestione degli errori

In caso di errore, l'API risponde con un codice di stato HTTP e, negli errori di business, un corpo JSON con il formato WebApiErrorResponse:

{
  "ErrorMessage": "The requested resource was not found",
  "ErrorCode": 1,
  "Id": "0HMV9A1B2C3D4-00000001"
}

Campo	Descrizione
`ErrorMessage`	Descrizione leggibile dell'errore.
`ErrorCode`	Codice numerico dell'errore (per esempio, `1` = cliente non trovato, `4` = il prezzo non coincide, `22` = prenotazione non trovata). Viene serializzato come intero.
`Id`	GUID di correlazione. Utile per segnalare il problema al supporto.

Codici di stato più comuni:

Stato	Significato	Corpo
`200`	Successo.	Risultato dell'endpoint.
`400`	Errore di business o di validazione.	`WebApiErrorResponse` con `ErrorCode`.
`403`	Non autenticato o senza permessi.	—
`404`	Risorsa non trovata.	—

L'autenticazione fallita restituisce 403

Se il token manca, è scaduto, o non corrisponde al tenant dell'host, l'API risponde 403 (non 401). Se ricevi un 403, controlla che l'header Authorization sia presente, che il token non sia scaduto e che tu stia usando l'host corretto del tenant.

Salva l'Id dell'errore

Quando qualcosa fallisce con un 400, il campo Id del corpo è l'identificatore di correlazione. Includilo quando apri un ticket di supporto: permette di tracciare esattamente cosa è successo lato server.

Prossimi passi

Hai già l'essenziale: token, richiesta autenticata, paginazione ed errori. Da qui puoi esplorare il resto dell'API:

Cerca disponibilità e preventiva con GET /api/search e GET /api/booking/price.
Crea una prenotazione con POST /api/booking/book e registra il pagamento con POST /api/booking/pay.
Consulta i cataloghi anagrafici: GET /api/places, GET /api/categories, GET /api/currencies.

Il dettaglio completo di ogni endpoint, con i suoi parametri e schemi, è nel riferimento dell'API.

1. Ottenere un token​

2. La tua prima richiesta autenticata​

3. Una GET con paginazione​

Come iterare le pagine​

4. Gestione degli errori​

Prossimi passi​