Shell B2B Mobility Card Management API – Schnellstartanleitung

API-Version: 3.1.5 | Authentifizierung: OAuth 2.0 | Status: Produktion

Übersicht

Die Shell Card Management API ist eine REST-basierte API, die es Entwicklern ermöglicht, Shell-Tankkarten programmgesteuert zu verwalten. Die API unterstützt die Suche nach Karten, die Bestellung, Statusaktualisierungen, die Kündigung sowie verschiedene andere Vorgänge zur Kartenverwaltung.

Hinweis: Diese Anleitung behandelt ausschließlich OAuth 2.0-authentifizierte Endpunkte (Basispfad: /card-management/v1). Ältere Endpunkte mit Basic-Auth-Authentifizierung (/fleetmanagement/v1/card) sind nicht enthalten, da sie auslaufen.

Wichtigste Funktionen

• Tankkarten nach flexiblen Kriterien suchen und filtern
• Neue Karten bestellen und den Bestellstatus verfolgen
• Karten sperren, entsperren und kündigen
• Lieferadressen für Karten aktualisieren
• Einstellungen zur automatischen Kartenverlängerung verwalten
• Karten zwischen Kartengruppen und Konten verschieben
• PIN-Erinnerungen anfordern

Wichtiger Hinweis – OAuth 2.0

WICHTIG: OAuth 2.0 ist nun die Standard-Authentifizierungsmethode

• Neue Integrationen: Verwenden Sie OAuth 2.0 von Anfang an
• Bestehende Integrationen: Planen Sie Ihre Migration zu OAuth 2.0
• Veraltete Methoden: Basic Auth und API-Schlüssel werden auslaufen

Wenden Sie sich an den Shell-Technischen Support, um Ihre OAuth 2.0-Anmeldedaten (client_id und client_secret) zu erhalten.

Authentifizierung

OAuth 2.0 (Standard-Authentifizierungsmethode)

Die Shell Card Management API verwendet den OAuth 2.0-Client-Credentials-Flow für eine sichere Authentifizierung.

WARNUNG: Alle Kunden sollten die Umstellung auf die OAuth 2.0-Authentifizierung planen. Dies ist die empfohlene und zukunftssichere Authentifizierungsmethode für die Shell Card Management API. Ältere Authentifizierungsmethoden werden schrittweise eingestellt.

OAuth 2.0-Ablauf

Schritt 1: Zugriffstoken abrufen

Fordern Sie ein Zugriffstoken vom OAuth-Token-Endpunkt an:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=Ihre-Client-ID&client_secret=Ihr-Client-Secret

Schritt 2: Verwenden des Zugriffstokens in API-Anfragen

Authorization: Bearer 
Content-Type: application/json

Token-Verwaltung

Bewährte Verfahren für die Token-Verwaltung:

• Zugriffstoken haben eine begrenzte Gültigkeitsdauer (in der Regel 15 Minuten)
• Implementieren Sie Token-Caching, um unnötige Token-Anfragen zu vermeiden
• Aktualisieren Sie Token vor Ablauf, um einen unterbrechungsfreien Dienst zu gewährleisten
• Geben Sie Ihr client_secret niemals weiter und betten Sie es nicht in clientseitigen Code ein

Strategie zur Einführung von OAuth 2.0

Warum auf OAuth 2.0 umsteigen?

Sicherheitsvorteile:

• Authentifizierungsprotokoll nach Industriestandard
• Zeitlich begrenzte Zugriffstoken verringern Sicherheitsrisiken
• Bei jeder Anfrage werden keine Anmeldedaten übertragen
• Bessere Unterstützung für die Token-Rotation und -Sperrung

Betriebliche Vorteile:

• Verbesserte Skalierbarkeit und Leistung
• Bessere Überwachungs- und Audit-Funktionen
• Vereinfachte Verwaltung von Anmeldedaten
• Zukunftssichere Integration

Migrationspfad

Wenn Sie derzeit veraltete Authentifizierungsmethoden verwenden, folgen Sie diesem Migrationspfad:

1. OAuth 2.0-Anmeldedaten anfordern bei technischen Support von Shell
2. Implementieren Sie die OAuth-Token-Verwaltung in Ihrer Anwendung
3. Führen Sie gründliche Tests in der Test-/Sandbox-Umgebung durch
4. Führen Sie während der Umstellung eine parallele Authentifizierung (OAuth + Legacy) während der Umstellung
5. OAuth-Integration überwachen und validieren
6. Nach der Validierung ausschließlich auf OAuth umstellen
7. Legacy-Authentifizierung nach erfolgreicher Migration

aus dem Betrieb nehmen

Die API ist in zwei Umgebungen verfügbar:

Tipp: Testen Sie Ihre Integration immer in der Testumgebung, bevor Sie in die Produktion wechseln.

Schnellstart

1. Beziehen Sie Ihre OAuth-Anmeldedaten

• Kontakt den technischen Support von Shell
• OAuth 2.0-Anmeldedaten anfordern (client_id und client_secret)
• Nutzungsbedingungen Nutzungsbedingungen

2. Zugriffstoken abrufen

Rufen Sie zunächst Ihr OAuth-Zugriffstoken ab:

cURL-Beispiel:

curl -X POST https://api-test.shell.com/test/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=Ihre-Client-ID&client_secret=Ihr-Client-Secret"

Antwort:

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 899
}

3. Führen Sie Ihre erste API-Anfrage durch

Beispiel: Nach aktiven Karten suchen

cURL-Beispiel:

curl -X POST https://api-test.shell.com/test/card-management/v1/search \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"Filters": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"]
},
"Page": "1",
"PageSize": "50"
}'

Beispielantwort:

{
"RequestId": "233e4567-e89b-12d3-a456-426614174000",
"Status": "SUCCESS",
"Data": [
{
"CardId": 125,
"PAN": "7002861007636000020",
"MaskedPAN": "7002861**000020",
"DriverName": "ROBERT SMITH",
"VehicleRegistrationNumber": "MV65YLH",
"StatusBeschreibung": "Aktiv",
"Ablaufdatum": "20250531",
"Kartentyp-Code": "7077861",
"Kartentyp-Bezeichnung": "Shell-Karte"
}
],
"Seite": 1,
"Seitengröße": 50,
"Gesamtseiten": 1,
"GesamtanzahlDatensätze": 1
}

API-Endpunkt-Referenz

Kartensuche und -abruf

Häufige Anwendungsfälle:

• Suche nach Kartenstatus (AKTIV, GESPERRT, ABGELAUFEN usw.)
• Nach Fahrernamen oder Kfz-Kennzeichen filtern
• Suche nach PAN (letzte 4 Ziffern)
• Karten finden, die in X Tagen ablaufen

Kartenübersicht

Gibt zurück:

• Gesamtanzahl der Karten nach Status
• Zusammenfassende Statistiken nach Kartentyp
• Aufschlüsselung nach aktiven und inaktiven Karten

Kartenbestellung

Erforderliche Angaben für die Kartenbestellung:

• ColCoCode (Code des Abrechnungsunternehmens)
• Zahlernummer oder Zahler-ID
• Kontonummer
• Kartentyp und -konfiguration
• Angaben zur Lieferadresse

Kartenstatusverwaltung

Statusaktionen:

• SPERREN – Eine Karte vorübergehend sperren
• ENTSPERREN – Eine gesperrte Karte wieder aktivieren
• BESCHÄDIGT – Karte als beschädigt melden und Ersatz beantragen
• TEMP_BLOCK_CUSTOMER - Vom Kunden veranlasste vorübergehende Sperrung
• TEMP_BLOCK_SHELL – Von der Shell initiierte vorübergehende Sperrung

ACHTUNG: Die Kartensperrung ist endgültig und kann nicht rückgängig gemacht werden.

Weitere Endpunkte

Anwendungsbeispiele

Beispiel 1: Suche nach Karten, die bald ablaufen

POST /card-management/v1/search

{
"Filters": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"],
"ExpiringInDays": 30
},
"Page": "1",
"PageSize": "100"
}

Beispiel 2: Eine Karte vorübergehend sperren

POST /card-management/v1/updatestatus

{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"Action": "TEMP_BLOCK_CUSTOMER",
"Reason": "Karte vorübergehend verlegt"
}
]
}

Beispiel 3: Karten stornieren

POST /card-management/v1/cancel

{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"CardExpiryDate": "20231231"
}
],
"ReasonText": "Verloren",
"RequestId": "1"
}

Fehlerbehandlung

Häufige Fehlercodes

Bewährte Verfahren

1. OAuth 2.0-Authentifizierung einführen

WICHTIG: Alle Kunden sollten auf die OAuth 2.0-Authentifizierung umsteigen. Implementieren Sie ein ordnungsgemäßes Token-Management:

• Zugriffstoken zwischenspeichern und bis zum Ablauf wiederverwenden
• Token aktualisieren, bevor sie ablaufen (empfohlen: 60 Sekunden vorher)
• Client-Anmeldedaten sicher speichern (verwenden Sie Umgebungsvariablen oder einen Secrets-Manager)
• Protokollieren oder offenlegen Sie Zugriffstoken niemals im clientseitigen Code

2. Verwenden Sie Request-IDs

Fügen Sie immer eine eindeutige Request-ID (im GUID-Format) ein, um eine lückenlose Rückverfolgbarkeit zu gewährleisten

3. Implementieren Sie Paginierung

Verwenden Sie bei großen Datensätzen Paginierung, um Timeouts zu vermeiden

4. Testen Sie in der Sandbox-Umgebung

Testen Sie die Integration immer in der Test-/Sandbox-Umgebung, bevor Sie in die Produktion wechseln

SDK & Code-Beispiele

Shell stellt offizielle SDKs und umfassende Code-Beispiele bereit, um Ihre Integration mit der Card Management API zu beschleunigen.

Verfügbare SDK-Sprachen

• Python – Voll funktionsfähiges SDK mit OAuth 2.0-Unterstützung
• TypeScript – Typsicheres SDK mit vollständigen Typdefinitionen
• Java – SDK für den Einsatz in Unternehmen
• C#/.NET – Vollständige .NET-Integration
• PHP – Einfach zu verwendende PHP-Bibliothek
• Ruby – Ruby-Gem für nahtlose Integration

Offizielle SDKs und Dokumentation anzeigen

Support und Ressourcen

Technischer Support

• Support: Technischer Support von Shell

Dokumentation

• Nutzungsbedingungen
• API-Referenz

Hilfe erhalten

Wenn Sie den Support kontaktieren, geben Sie bitte Folgendes an:

1. Ihre client_id (geben Sie niemals Ihre client_secret oder Zugriffstoken weiter)
2. RequestId aus der API-Antwort
3. Zeitstempel der Anfrage
4. Umgebung (Produktion/Test)

Letzte Aktualisierung: 15. Juni 2026
Dokumentversion: 1.0
API-Version: 3.1.5