Quick start

Dieser Leitfaden bringt Sie in etwa 5 Minuten von null zu Ihrer ersten authentifizierten Anfrage: ein Token anfordern, ein echtes GET ausführen, die Antwort lesen, paginieren und Fehler verstehen.

Bevor Sie beginnen

Sie benötigen einen Rently-API-Benutzer (mit Berechtigung zur Nutzung der API) und die URL Ihrer Instanz. Bei Rently lebt jeder Kunde (Mandant) auf seinem eigenen Host, zum Beispiel https://{tenant}.rently.com.ar. Der Host identifiziert den Mandanten, verwenden Sie daher bei jedem Aufruf immer den Host Ihrer Instanz.

In diesem Leitfaden verwenden wir https://{tenant}.rently.com.ar als Beispiel. Ersetzen Sie es durch den Host Ihres Mandanten.

1. Ein Token anfordern

Die API authentifiziert sich mit einem OAuth2-Bearer-Token. Um es zu erhalten, senden Sie ein POST an /auth/token mit Ihren Zugangsdaten über den Grant client_credentials. Ihr API-Benutzer ist die client_id und Ihr Schlüssel ist das 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"

Die Antwort ist ein JSON mit dem Token:

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

Feld	Beschreibung
`access_token`	Das Token, das Sie bei jeder weiteren Anfrage senden.
`token_type`	Immer `bearer`. Legt das Schema des Headers `Authorization` fest.
`expires_in`	Gültigkeit des Tokens in Sekunden (≈ 1 Tag).

Verwenden Sie das Token wieder

Das Token ist etwa einen Tag gültig (expires_in ≈ 86399 Sekunden). Speichern Sie es und verwenden Sie es wieder, anstatt bei jeder Anfrage ein neues anzufordern. Fordern Sie nach Ablauf ein neues an.

Das Token ist an den Mandanten gebunden

Das Token ist nur gegen denselben Host gültig, mit dem Sie es angefordert haben. Verwenden Sie ein Token gegen den Host eines anderen Mandanten, antwortet die API mit 403. Fordern Sie das Token immer gegen denselben Host an, gegen den Sie die Aufrufe machen.

2. Ihre erste authentifizierte Anfrage

Fügen Sie mit dem access_token jedem API-Endpunkt den Header Authorization: Bearer {token} hinzu. Beginnen wir mit einem einfachen GET ohne Parameter: die Filialen Ihrer Instanz mit GET /api/branchoffices auflisten.

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

Antwort (Array von Filialen):

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

Sprache der Antwort

Einige Endpunkte akzeptieren einen Parameter Language, um die Sprache der Texte in der Antwort festzulegen; zum Beispiel unterstützt GET /api/search dies. Der Wert akzeptiert den vollständigen Kulturnamen (es-AR, en-US, pt) oder den zweistelligen ISO-Code (es, en). Lassen Sie ihn weg, wird die Standardsprache Ihrer Instanz verwendet. In der API-Referenz sehen Sie, welche Endpunkte ihn akzeptieren.

Fertig: Das ist Ihr erster authentifizierter Aufruf. Immer wenn Sie ein 200 erhalten, arbeiten Sie bereits gegen die API.

3. Ein GET mit Paginierung

Große Listen werden paginiert geliefert. Sehen wir uns GET /api/bookings/list an, das Buchungen in Blöcken zurückgibt. Es akzeptiert diese Query-Parameter:

Parameter	Default	Beschreibung
`offset`	`0`	Paginierungscursor. Beim ersten Aufruf `0`.
`limit`	`30`	Anzahl der Elemente pro Seite.
`status`	—	Optionaler Filter nach Buchungsstatus.
`sortDirectionAsc`	`true`	Sortierrichtung.

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

Die Antwort verpackt die Ergebnisse in einer paginierten Struktur:

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

Feld	Beschreibung
`Offset` / `Limit`	Der auf diese Seite angewendete Offset und das Limit.
`Total`	Gesamtzahl der verfügbaren Datensätze.
`Results`	Das Array der Elemente dieser Seite (kann `null` sein, wenn keine Ergebnisse vorliegen).
`NextOffset`	Das `offset`, das beim nächsten Aufruf für die folgende Seite zu senden ist.

So iterieren Sie über die Seiten

Um alle Seiten zu durchlaufen, nehmen Sie das NextOffset jeder Antwort und übergeben es als offset in der nächsten. Die Iteration endet, wenn Results weniger Elemente als Limit liefert.

# Nächste Seite: verwenden Sie das NextOffset aus der vorherigen Antwort
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=NEXT_OFFSET&limit=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Fehlerbehandlung

Bei einem Fehler antwortet die API mit einem HTTP-Statuscode und, bei Geschäftsfehlern, einem JSON-Body im Format WebApiErrorResponse:

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

Feld	Beschreibung
`ErrorMessage`	Lesbare Beschreibung des Fehlers.
`ErrorCode`	Numerischer Fehlercode (zum Beispiel `1` = Kunde nicht gefunden, `4` = Preis stimmt nicht überein, `22` = Buchung nicht gefunden). Wird als Ganzzahl serialisiert.
`Id`	Korrelations-GUID. Nützlich, um das Problem dem Support zu melden.

Häufigste Statuscodes:

Status	Bedeutung	Body
`200`	Erfolg.	Ergebnis des Endpunkts.
`400`	Geschäfts- oder Validierungsfehler.	`WebApiErrorResponse` mit `ErrorCode`.
`403`	Nicht authentifiziert oder keine Berechtigung.	—
`404`	Ressource nicht gefunden.	—

Fehlgeschlagene Authentifizierung gibt 403 zurück

Fehlt das Token, ist es abgelaufen oder gehört es nicht zum Mandanten des Hosts, antwortet die API mit 403 (nicht 401). Erhalten Sie ein 403, prüfen Sie, ob der Header Authorization vorhanden ist, das Token nicht abgelaufen ist und Sie den korrekten Host des Mandanten verwenden.

Speichern Sie die Id des Fehlers

Wenn etwas mit einem 400 fehlschlägt, ist das Feld Id im Body die Korrelations-ID. Geben Sie sie beim Eröffnen eines Support-Tickets an: So lässt sich genau nachvollziehen, was auf der Serverseite passiert ist.

Nächste Schritte

Sie haben jetzt das Wesentliche: Token, authentifizierte Anfrage, Paginierung und Fehler. Von hier aus können Sie den Rest der API erkunden:

Suchen Sie Verfügbarkeit und berechnen Sie Preise mit GET /api/search und GET /api/booking/price.
Erstellen Sie eine Buchung mit POST /api/booking/book und erfassen Sie die Zahlung mit POST /api/booking/pay.
Fragen Sie die Stammdatenkataloge ab: GET /api/places, GET /api/categories, GET /api/currencies.

Die vollständigen Details jedes Endpunkts mit seinen Parametern und Schemas finden Sie in der API-Referenz.

1. Ein Token anfordern​

2. Ihre erste authentifizierte Anfrage​

3. Ein GET mit Paginierung​

So iterieren Sie über die Seiten​

4. Fehlerbehandlung​

Nächste Schritte​