Authentifizierung
Für die Nutzung der linexo REST API ist eine initiale Registrierung erforderlich.
Bei Interesse schreiben Sie uns gerne eine Nachricht an leasing-development@linexo.com
Die Autorisierung erfolgt nach dem OAuth 2.0 Protokoll. Bei jeder Anfrage muss ein sogenannter
Access-Token im HTTP
Authorization
Header mitgesendet werden. Die API unterstützt
zwei OAuth 2.0 Genehmigungsprozesse (Grant-Types) um einen Access-Token zu erhalten:
Client Grant und Authorization Code Grant mit PKCE.
Grundsätzlich erhält jeder Konsument der API Zugangsdaten für beide Genehmigungsprozesse.
OAuth Scopes
Der zu verwendende Genehmigungsprozess hängt vom Endpunkt ab, der genutzt werden soll. Die
folgende Tabelle zeigt eine Übersicht welcher Genehmigungsprozess je Endpunkt zur Verfügung
steht und welcher OAuth Scope (Berechtigung) benötigt wird:
Scope | Beschreibung | Grant-Type | Endpunkt |
---|---|---|---|
employee.read |
Lesender zugriff auf Mitarbeiter-Informationen | authorizationCode clientCredentials |
GET /employee/{id} GET /employee/{id}/policy |
order.read |
Lesender Zugriff auf Leasing-Angebote und Status-Informationen | authorizationCode clientCredentials |
GET /order/{id} GET /order/{id}/history |
order.create |
Erstellt ein Leasing-Angebot | authorizationCode |
POST /order/{id} |
order.pickup |
Übergabe des Leasing-Bikes | authorizationCode clientCredentials |
POST /order/{id}/pickup |
order.invoice |
Rechnungserstellung für ein Leasing-Bike | authorizationCode |
GET /order/{id}/invoice POST /order/{id}/invoice |
Grant-Type: Client Grant
Der Client Grant eignet sich für die Kommunikation von Maschine-zu-Maschine. Er kann für
API-Endpunkte verwendet werden, die keinen User-Kontext benötigen. So lassen sich beispielsweise
Status-Informationen als Hintergrundprozess kontinuierlich abrufen.
Der Erhalt eines OAuth 2 Access-Tokens erfolgt über den API-Endpunkt
POST /oauth/token
.
Als Grant-Typ muss client_credentials
verwendet werden. Die eindeutige Kennung
(client_id
) und das dazugehörige Geheimnis (secret
) werden bei der
Registrierung mitgeteilt. Im Erfolgsfall wird ein Access-Token (access_token
)
zurückgeliefert. Dieser hat standardmäßig eine Lebensdauer von 14 Tagen.
Access-Token-Anfrage
POST /oauth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "9beaee6d-9145-49a6-abb2-6dc9a6980e57",
"client_secret": "top-secret",
"scope": "employee.read order.read"
}
Antwort
200 OK
{
"token_type": "Bearer",
"expires_in": 1209600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YzNhY2Y3MS0xNTdhLTRjNDEtYTMxOC0yZTczMDY1..."
}
Hinweis
Alle Details zum API-Endpunkt
Alle Details zum API-Endpunkt
POST /oauth/token
finden Sie in unserer Schnittstellenbeschreibung.
Grant-Type: Authorization Code Grant mit PKCE
Die meisten Endpunkte müssen im Kontext eines Nutzers (z.B. als Mitarbeiter eines Fachhändlers)
aufgerufen werden. Die Autorisierung erfolgt in mehreren Schritten:
1. Schritt: Initialisierung einer Anfrage zur Autorisierung
Die Initialisierung einer Anfrage zur Autorisierung erfolgt über den API-Endpunkt
GET /oauth/authorize
.
Die Kennung (client_id
) erhalten Sie bei der Registrierung mitgeteilt.
GET /oauth/authorize \
?client_id=9bebe9fe-2120-4857-a9b9-ab09efcb754d \
&redirect_uri=https%3A%2F%2Fmein-beispiel-bike-shop.de%2Flinexo%2Fauth%2Fcallback \
&response_type=code \
&scope=employee.read+order.read+order.create+order.pickup+order.invoice \
&state=DxU1oaQ2vymSxim2a7aIq1UCKFEgtHOeXjaNEcgr \
&code_challenge=hWCT9JET_aByVObuu3R4YwpUuiq0hw6OgIDQ_N_DyQI \
&code_challenge_method=S256
Wichtig
Die
Die
redirect_uri
muss identisch zu der bei der Registrierung angegebenen URI sein.
Wichtig
Der
Der
state
Parameter ist ein CSRF-Token. Dieser ist optional, wird aber zur Erhöhung der
Sicherheit empfohlen mitzusenden. Der Client muss dafür den Wert des CSRF-Tokens in der Session des Users
speichern, um diesen später überprüfen zu können.
Hinweis
Alle Details zum API-Endpunkt
Alle Details zum API-Endpunkt
GET /oauth/authorize
finden Sie in unserer Schnittstellenbeschreibung.
2. Schritt: Weiterleitung des Users zur Anmeldung am Leasing-Portal

3. Schritt: Genehmigung der Berechtigungsanfrage durch den User

4. Schritt: Das Leasing-Portal leitet zur redirect_uri
zurück
Der Client überprüft die zurückgelieferten Informationen und sendet eine weitere Anfrage zum
Erhalt von Access- und Refresh-Token.
302 Redirect
https://mein-beispiel-bike-shop.de/linexo/auth/callback \
?code=def50200065462814d8ec3141ca119263fa1ac0093eeaa307469c69eaf11881e93c594f1fdd25fd6a51e22f462... \
&state=eW2sbrpuJtwvdGXdbpieFFHZtLz3TV5D8zvrztNo
5. Schritt: Access-Token-Anfrage
POST /oauth/token
Content-Type: application/json
{
"grant_type": "authorization_code",
"client_id": "9bebe9fe-2120-4857-a9b9-aa09efcb754d",
"redirect_uri": "https://mein-beispiel-bike-shop.de/linexo/auth/callback",
"code_verifier": "ZNro09Muoh6GwtIxKCHFUEMWKtOC9ekuetOsEztgMszq4e2DvkQJZFBNZ5krDeyuctSpU8VO0dsJ...",
"code": "def50200e835ec465842e8b9dbbbd763ef41c7a32113efbf4b6a3bd63cfe2a265b559379b2b041d59b2eb..."
}
Antwort
200 OK
{
"token_type": "Bearer",
"expires_in": 1209600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YmViZTlmZS0yMTIwLTQ4NTctYTliOS...",
"refresh_token": "def502002d31f5677609a18602665df1021cefc0c04e24e84ba9af64da9acf0540c8cf20a40dc8..."
}
Hinweis
Der Access-Token hat eine Lebensdauer von 14 Tagen und kann nach Ablauf der Gültigkeit über den Refresh-Token erneuert werden. Der Refresh-Token ist 28 Tage gültig.
Der Access-Token hat eine Lebensdauer von 14 Tagen und kann nach Ablauf der Gültigkeit über den Refresh-Token erneuert werden. Der Refresh-Token ist 28 Tage gültig.
OAuth Access-Token
Alle Access-Token werden als JSON Web Token (JWT) ausgegeben. JWT's sind in RFC 7519 spezifiziert. Sie bestehen aus
Header, Payload und Signatur, die Base64-kodiert übertragen werden und durch Punkte getrennt sind.
Der Payload ist wie folgt aufgebaut:
Beispiel JWT Payload:
Eigenschaft | Datentyp | Beschreibung |
---|---|---|
aud |
string (UUID) |
Audience - gibt an für wen der Token bestimmt ist. Der Wert entspricht der client_id . |
jti |
string |
JWT ID - ist eine eindeutige ID des JWT (JSON Web Token). Jeder Token erhält eine neue ID. |
iat |
string (UNIX Timestamp) |
Issued at - ist der Zeitpunkt, zu dem der JWT ausgestellt wurde. Mit dieser Angabe kann das Alter des JWT bestimmt werden. |
nbf |
string (UNIX Timestamp) |
Not Before - ist der Zeitpunkt, ab dem der JWT gültig ist. |
exp |
string (UNIX Timestamp) |
Expiration Time - ist der Zeitpunkt, zu dem der JWT seine Gültigkeit verliert. |
sub |
string (UUID) |
Subject - gibt an für welchen User der Token ausgestellt ist. Das Feld besitzt nur beim Grant-Type authorization_code einen Wert. Der Wert entspricht der ID des Users. |
retailer_id |
string |
Retailer - gibt an zu welchem Fachhändler der User gehört. Das Feld besitzt nur beim Grant-Type authorization_code einen Wert. Der Wert entspricht der ID des Fachhändlers. |
scopes |
array |
Scopes - Liste von OAuth Scopes auf die mit dem Token zugegriffen werden kann. |
{
"aud": "9c3ad109-d0c7-40c6-9405-087b5f17fc2f",
"jti": "6b5e8fc02ad8ddd6913169aa1e9952ed1d400ef59ba9c9de06e8736b53739b4b32b00f61fbdac006",
"iat": 1718032938.550092,
"nbf": 1718032938.550094,
"exp": 1719242538.537486,
"sub": "9c3abf5a-f654-4b75-ae36-fbe0b2704e3e",
"retailer_id": "123456",
"scopes": [
"order.create",
"order.read",
"order.pickup",
"order.invoice"
]
}
Access-Token vom Typ Authorization Code Grant mit PKCE enthalten im Payload des
JWT Informationen über den User für den der Token ausgestellt wurde. Es gibt zwei relevante Eigenschaften:
Das Feld sub
(subject) ist eine technische UUID und identifiziert den User eindeutig.
Das Feld retailer_id
ist die ID des Fachhändlers, so dass der User einem Fachhändler
zugeordnet werden kann. Beide ID's sind konstant und ändern sich nicht.
Wichtig
Speichern Sie Access- und Refresh-Token entsprechend ihrer Lebensdauer, so dass die Token zu einem späteren Zeitpunkt erneut verwendet werden können. Speichern Sie Token vom Typ Authorization Code Grant mit PKCE so, dass ein Bezug zum User und Fachhändler hergestellt werden kann.
Speichern Sie Access- und Refresh-Token entsprechend ihrer Lebensdauer, so dass die Token zu einem späteren Zeitpunkt erneut verwendet werden können. Speichern Sie Token vom Typ Authorization Code Grant mit PKCE so, dass ein Bezug zum User und Fachhändler hergestellt werden kann.
Beispiel:
Es wird ein Access-Token für einen Mitarbeiter eines Fachhändlers ausgestellt, so dass in seinem Namen ein Leasing-Angebot (
Es wird ein Access-Token für einen Mitarbeiter eines Fachhändlers ausgestellt, so dass in seinem Namen ein Leasing-Angebot (
POST /order
) erstellt werden kann. Access- und Refresh-Token
werden vom Client gespeichert, so dass sie zu einem späteren Zeitpunkt erneut verwendet werden können.
Der Client verhindert damit, dass der Mitarbeiter sich zu einem späteren Zeitpunkt erneut am
Leasing-Portal anmelden muss. Es ist zusätzlich möglich den Token für Hintergrundprozesse zu nutzen
um beispielsweise den Schritt der Rechnungserstellung (POST /order/{id}/invoice
) zu
automatisieren.
Testdaten
Die meisten API-Endpunkte müssen im Kontext von einem Arbeitnehmer und/oder einer Bestellung (Leasing-Angebot) aufgerufen werden.
Hier finden Sie passende Testdaten.
Umgebung:
api.stage.leasingportal.linexo.com
Arbeitnehmer-ID (
employee_id
): 6157w9
Bestell-/ Vorgangsnummer mit Status Angebot versendet (
order_id
): 31381176
Hinweis: Dieser Status ist gut geeignet zum Testen der Bestelldetails und des Bestellstatus - siehe Schritt 3.
Bestell-/ Vorgangsnummer mit Status Bereit zur Abholung (
order_id
): 29752814
Abholcode (
pickup_code
): 6t4573
Hinweis: Dieser Status ist gut geeignet um eine Abholung eines Leasing-Bikes zu testen.
Bestell-/ Vorgangsnummer mit Status Warten auf Rechnungsdaten (
order_id
): 95218401
Hinweis: Dieser Status ist gut geeignet um eine Erstellung einer Rechnung zu testen.
Beratungs- und Verkaufsgespräch
Es ist empfehlenswert den Kunden direkt zu Beginn eines Beratungs- und Verkaufsgespräches nach seiner Arbeitnehmer-ID
zu fragen. So kann geprüft werden ob die Arbeitnehmer-ID korrekt ist, der Mitarbeiter den Registrierungs- und
Verifizierungsprozess erfolgreich abgeschlossen hat und ob er bereits andere aktive Leasing-Bikes besitzt. Neben
den Kundendaten können über die Arbeitnehmer-ID auch die aktuellen Unternehmensrichtlinien geladen werden, so dass
der Fachhändler herausfinden kann welche Fahrradtypen erlaubt sind und ob Einschränkungen bzgl. der Bike-Auswahl
bestehen, so dass dem Kunden direkt ein passendes Angebot unterbreitet werden kann.
Abfrage der Details zu einem Mitarbeiter
curl --location --request GET 'https://api.stage.leasingportal.linexo.com/employee/6157w9' \
--header 'Authorization: Bearer <access-token>'
$client = new Client();
$headers = [
'Authorization' => 'Bearer <access-token>'
];
$request = new Request('GET', 'https://api.stage.leasingportal.linexo.com/employee/6157w9', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.stage.leasingportal.linexo.com/employee/6157w9");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <access-token>");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Abfrage der Unternehmensrichtlinien
curl --location --request GET 'https://api.stage.leasingportal.linexo.com/employee/6157w9/policy' \
--header 'Authorization: Bearer <access-token>'
Leasing-Angebot
Hat sich der Kunde für ein Bike und passendes Zubehör entschieden kann der Fachhändler direkt über
sein Warenwirtschaftssystem die Daten aufnehmen und ein Leasing-Angebot erstellen. Im Erfolgsfall erhält
der Fachhändler eine eindeutige Bestell- und Vorgangsnummer zurück. Das Warenwirtschaftssystem muss diese
Nummer speichern, so dass später auf die Bestellung zugegriffen werden kann. Fachhändler und Arbeitnehmer
erhalten vom Leasing-Portal E-Mails zur weiteren Vorgehensweise.
Leasing-Angebot erstellen
curl --location --request POST 'https://api.stage.leasingportal.linexo.com/order' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"employee_id": "6157w9",
"articles": [
{
"group_name": "EBIKE_CITY",
"manufacturer_name": "VENICE",
"external_number": "S06A90F3P2",
"model_name": "Elektro-Citybike VICTORIA LADY 28 Zoll",
"build_year": 2024,
"color": "beige",
"material": "ALUMINIUM",
"shape": "MEN",
"size": 46,
"unit": "CM",
"engine_manufacturer": "Etrotek",
"battery_capacity": "252",
"purchase_net_price": 117563,
"purchase_gross_price": 139900,
"retail_price": 159900
},
{
"group_id": 301550,
"group_name": "Kettenschlösser",
"manufacturer_name": "KOHLBURG",
"model_name": "KOHLBURG Sicherheits-Fahrradschloss 120 cm lang",
"external_number": "S0O690ECP2",
"purchase_net_price": 5029,
"purchase_gross_price": 5985,
"retail_price": 6999
}
],
"delivery_week": 31,
"given_information_accurate_and_complete": true,
"bike_complies_with_employer_policy": true
}'
Warten auf Freigaben
Nach der Angebotserstellung müssen Arbeitnehmer und Arbeitgeber dem Leasing-Angebot zustimmen. Der aktuelle Bestellstatus
kann vom Warenwirtschaftssystem im Hintergrund kontinuierlich abgefragt werden. Dabei wird eine Liste von Statuseinträgen
abgerufen. Bei einer Änderung z.B. der Annahme des Angebotes durch den Arbeitnehmer wird am Anfang der Liste ein weiterer
Status-Eintrag hinzugefügt.
Status | Folge-Status | Finaler Status |
---|---|---|
SENT |
EMPLOYEE_ACCEPTED EMPLOYEE_DECLINED |
|
EMPLOYEE_ACCEPTED |
EMPLOYER_ACCEPTED EMPLOYER_DECLINED |
|
EMPLOYER_ACCEPTED |
READY_FOR_DELIVERY |
|
READY_FOR_DELIVERY |
DELIVERED |
|
DELIVERED |
WAITING_FOR_INVOICE |
|
WAITING_FOR_INVOICE |
WAITING_FOR_PAYMENT |
|
WAITING_FOR_PAYMENT |
ACTIVE PAYMENT_REJECTED |
|
PAYMENT_REJECTED |
ACTIVE |
DECLINED |
ACTIVE |
- | UNCOMPLETED_CASE_INSURANCE UNCOMPLETED_CASE_TRANSFER COMPLETED |
Bestelldetails abfragen
curl --location --request GET 'https://api.stage.leasingportal.linexo.com/order/31381176' \
--header 'Authorization: Bearer <access-token>'
Bestellstatus abfragen
curl --location --request GET 'https://api.stage.leasingportal.linexo.com/order/31381176/history' \
--header 'Authorization: Bearer <access-token>'
Übergabe des Leasing-Bikes
Haben Arbeitnehmer und Arbeitgeber dem Leasing-Angebot zugestimmt und ist das Bike beim Fachhändler
eingetroffen kann die Übergabe stattfinden. Der Arbeitnehmer hat vorab einen Abholcode erhalten,
der für die Übernahme des Leasing-Bikes erforderlich ist. Der Fachhändler muss zusätzlich die
Identität des Arbeitnehmers anhand seines Personalausweises prüfen und dem Arbeitnehmer eine
Einweisung in das Leasing-Bike geben. Im Erfolgsfall wird der Bestellstatus auf
WAITING_FOR_INVOICE
gesetzt.
Übernahme durchführen
curl --location --request POST 'https://api.stage.leasingportal.linexo.com/order/29752814/pickup' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"pickup_code": "6t4573",
"serial": "B0783KMCW2763",
"battery_serial": "E1786-12873-8197",
"id_card_verification": true,
"bike_instruction": true
}'
Hinweis
Als Übernahmedatum gilt der Zeitstempel des API-Aufrufs.
Als Übernahmedatum gilt der Zeitstempel des API-Aufrufs.
Rechnungserstellung
Wurde das Bike erfolgreich an den Arbeitnehmer übergeben muss der Fachhändler eine Rechnung für
das Leasing-Bike erstellen. Rechnungssteller ist der Fachhändler. Es werden seine zum Zeitpunkt
des API-Aufrufs im Leasing-Portal hinterlegten Daten wie Anschrift, Bankverbindung und Steuernummer
für die Rechnung verwendet. Rechnungsempfänger ist der Leasinggeber. Um eine Rechnung erstellen
zu können, muss sich die Bestellung im Status
WAITING_FOR_INVOICE
befinden. Im Erfolgsfall
wird der Bestellstatus auf WAITING_FOR_PAYMENT
gesetzt.
Rechnung erstellen
curl --location --request POST 'https://api.stage.leasingportal.linexo.com/order/29752814/invoice' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"invoice_number": "R2405-72135",
"invoice_date": "2024-05-23",
"net_total": 273109,
"gross_total": 325000
}'