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:

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..."
}
                        

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
                        

2. Schritt: Weiterleitung des Users zur Anmeldung am Leasing-Portal

login-screen

3. Schritt: Genehmigung der Berechtigungsanfrage durch den User

approval-screen

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..."
}
                

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:
                            {
  "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.
Beispiel:
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
Bestell-/ Vorgangsnummer mit Status Bereit zur Abholung (order_id): 29752814
Abholcode (pickup_code): 6t4573
Bestell-/ Vorgangsnummer mit Status Warten auf Rechnungsdaten (order_id): 95218401

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.
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
}'
                        

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
}'