Quick start

Ce guide vous amène de zéro à votre première requête authentifiée en environ 5 minutes : obtenir un token, faire un vrai GET, lire la réponse, paginer et comprendre les erreurs.

Avant de commencer

Vous avez besoin d'un utilisateur d'API Rently (avec les permissions pour utiliser l'API) et de l'URL de votre instance. Chez Rently, chaque client (tenant) vit sur son propre host, par exemple https://votre-entreprise.rently.com.ar. Le host identifie le tenant, donc utilisez toujours le host de votre instance dans chaque appel.

Dans ce guide, nous utilisons https://{tenant}.rently.com.ar comme exemple. Remplacez-le par le host de votre tenant.

1. Obtenir un token

L'API s'authentifie avec un token Bearer OAuth2. Pour l'obtenir, faites un POST sur /auth/token avec vos identifiants en utilisant le grant client_credentials. Votre utilisateur d'API est le client_id et votre clé est le 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=VOTRE_UTILISATEUR" \
  -d "client_secret=VOTRE_CLE"

La réponse est un JSON contenant le token :

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

Champ	Description
`access_token`	Le token que vous envoyez dans chaque requête ultérieure.
`token_type`	Toujours `bearer`. Définit le schéma du header `Authorization`.
`expires_in`	Durée de validité du token en secondes (≈ 1 jour).

Réutilisez le token

Le token est valable environ un jour (expires_in ≈ 86399 secondes). Conservez-le et réutilisez-le au lieu d'en demander un nouveau à chaque requête. Lorsqu'il expire, demandez-en un autre.

Le token est lié au tenant

Le token n'est valable que contre le même host que celui avec lequel vous l'avez demandé. Si vous utilisez un token contre le host d'un autre tenant, l'API répond 403. Demandez toujours le token et faites les appels contre le même host.

2. Votre première requête authentifiée

Avec l'access_token, ajoutez le header Authorization: Bearer {token} à n'importe quel endpoint de l'API. Commençons par un GET simple et sans paramètres : lister les agences de votre instance avec GET /api/branchoffices.

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

Réponse (tableau d'agences) :

[
  {
    "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"
  }
]

Langue de la réponse

Certains endpoints acceptent un paramètre Language pour fixer la langue des textes de la réponse ; par exemple, GET /api/search le supporte. La valeur accepte le nom de culture complet (es-AR, en-US, pt) ou le code ISO à deux lettres (es, en). Si vous l'omettez, la langue par défaut de votre instance est utilisée. Consultez la référence de l'API pour voir quels endpoints l'acceptent.

Voilà : c'est votre premier appel authentifié. Chaque fois que vous recevez un 200, vous opérez bien contre l'API.

3. Un GET avec pagination

Les grandes listes sont paginées. Voyons GET /api/bookings/list, qui renvoie les réservations par blocs. Il accepte ces paramètres de query :

Paramètre	Default	Description
`offset`	`0`	Curseur de pagination. Au premier appel, `0`.
`limit`	`30`	Nombre d'éléments par page.
`status`	—	Filtre optionnel par statut de la réservation.
`sortDirectionAsc`	`true`	Sens de tri.

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

La réponse enveloppe les résultats dans une structure paginée :

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

Champ	Description
`Offset` / `Limit`	L'offset et la limite appliqués à cette page.
`Total`	Nombre total d'enregistrements disponibles.
`Results`	Le tableau d'éléments de cette page (peut être `null` s'il n'y a pas de résultats).
`NextOffset`	L'`offset` à envoyer au prochain appel pour récupérer la page suivante.

Comment itérer sur les pages

Pour parcourir toutes les pages, prenez le NextOffset de chaque réponse et passez-le comme offset à la suivante. L'itération se termine lorsque Results renvoie moins d'éléments que Limit.

# Page suivante : utilisez le NextOffset renvoyé par la réponse précédente
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=NEXT_OFFSET&limit=30" \
  -H "Authorization: Bearer VOTRE_TOKEN"

4. Gestion des erreurs

En cas d'erreur, l'API répond avec un code de statut HTTP et, pour les erreurs métier, un corps JSON au format WebApiErrorResponse :

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

Champ	Description
`ErrorMessage`	Description lisible de l'erreur.
`ErrorCode`	Code numérique de l'erreur (par exemple, `1` = client introuvable, `4` = le prix ne correspond pas, `22` = réservation introuvable). Sérialisé comme un entier.
`Id`	GUID de corrélation. Utile pour signaler le problème au support.

Codes de statut les plus courants :

Statut	Signification	Corps
`200`	Succès.	Résultat de l'endpoint.
`400`	Erreur métier ou de validation.	`WebApiErrorResponse` avec `ErrorCode`.
`403`	Non authentifié ou sans permissions.	—
`404`	Ressource introuvable.	—

L'authentification échouée renvoie 403

Si le token est absent, expiré ou ne correspond pas au tenant du host, l'API répond 403 (et non 401). Si vous recevez un 403, vérifiez que le header Authorization est présent, que le token n'a pas expiré et que vous utilisez le bon host du tenant.

Conservez l'Id de l'erreur

Quand quelque chose échoue avec un 400, le champ Id du corps est l'identifiant de corrélation. Incluez-le lorsque vous ouvrez un ticket de support : il permet de retracer exactement ce qui s'est passé côté serveur.

Prochaines étapes

Vous avez désormais l'essentiel : token, requête authentifiée, pagination et erreurs. À partir d'ici, vous pouvez explorer le reste de l'API :

Recherchez la disponibilité et établissez un devis avec GET /api/search et GET /api/booking/price.
Créez une réservation avec POST /api/booking/book et enregistrez le paiement avec POST /api/booking/pay.
Consultez les catalogues de référence : GET /api/places, GET /api/categories, GET /api/currencies.

Le détail complet de chaque endpoint, avec ses paramètres et ses schémas, se trouve dans la référence de l'API.

1. Obtenir un token​

2. Votre première requête authentifiée​

3. Un GET avec pagination​

Comment itérer sur les pages​

4. Gestion des erreurs​

Prochaines étapes​