B2B Mobility Customer Data Quickstart

Einführung

Die B2B Mobility Customer Data API ist ein RESTful Service, der Ihnen die Abfrage und Verwaltung von Kundenkontodaten, Kartengruppen und zugehörigen Konfigurationen innerhalb der Shell Cards Platform ermöglicht. Diese API bietet flexible Suchfunktionen, unterstützt die Paginierung und ermöglicht den Abruf von Kontoinformationen, Kartenlieferadressen, Preislisten und Kartentypen. Sie unterstützt auch Vorgänge zum Erstellen und Aktualisieren von Kartengruppen sowie zum Verschieben von Karten zwischen Gruppen.

Nutzen	Beschreibung
Umfassende Kontoverwaltung	Zugriff auf detaillierte Kundenkontoinformationen einschließlich Abrechnung, Kartenzusammenfassungen und Status
Kartengruppenoperationen	Erstellen, aktualisieren, und Beenden von Kartengruppen mit flexiblen Kartenbewegungsfunktionen
Zugriff auf Preislisten	Abrufen von nationalen und internationalen Preislisten mit kundenspezifischen Rabatten
Flexible Suche	Abfragen von Daten mit mehreren Suchkriterien und Paginierungsunterstützung

Authentifizierung

Diese API unterstützt sowohl Basic Authentication als auch OAuth 2.0. OAuth 2.0 ist die empfohlene Authentifizierungsmethode für verbesserte Sicherheit.

Migrationshinweis

Die API unterstützt jetzt die OAuth 2.0-Authentifizierung. Wenn Sie derzeit Basic Authentication verwenden, empfehlen wir die Migration zu OAuth 2.0, um die Sicherheit zu erhöhen. Die Basis-URL wurde aktualisiert, und alle Endpunkte sind jetzt unter dem Pfad /v1 versioniert. Detaillierte Hinweise zur Migration finden Sie im OAuth 2.0 Migration Support.

Autorisierungsablauf

1. Anforderung von Client ID und Secret

Kontaktieren Sie das Shell API Team, um Zugang zur OAuth-Authentifizierung zu beantragen. Das Shell-API-Team stellt eine Client-ID und ein Geheimnis zur Verfügung.

2. Anforderung des Bearer-Tokens

Wenn Sie die Anmeldeinformationen erhalten haben, stellen Sie eine Anfrage an die OAuth-Token-Endpunkt der Shell-Authentifizierungs-API mit Ihren Anmeldeinformationen.

Beispielanforderung:

curl --location --request POST 'https://api-test.shell.com/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

Sie erhalten ein Bearer-Token in der Antwort:

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}

Hinweis: Die Ablaufzeit des Bearer-Tokens wird in Sekunden angegeben.

3. Authorisierung von API-Anfragen

Beim Aufruf von Shell-APIs muss Folgendes in den Header der Anfrage aufgenommen werden.

Authorisierung: Bearer access_token

Basis-URLs

Umgebung	URL
Test	https://api-test.shell.com/test
Produktion	https://api.shell.com

Core Integration

1. Get Logged-In User Details

Beschreibung: Dieser Endpunkt ruft die Benutzerdaten des angemeldeten Benutzers ab, einschließlich zugänglicher Zahler, Konten und Rollen. Dieser Vorgang sollte nach erfolgreicher Authentifizierung aufgerufen werden, um die PayerId zu erhalten, die für nachfolgende API-Aufrufe benötigt wird.

Pfad: POST /user-management/v1/loggedinuser

Beispielanfrage

curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filter": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard"
  }
}'

Anfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
RequestId	String	Ja	Pflicht UUID (RFC 4122) zur Nachverfolgung von Anfragen
IncludePayerGroup	boolean	No	Include payer group information when true (default: false)
IncludeEIDDetails	boolean	No	Include Electronic Invoice Data when true (default: false)

Beispielantwortung

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "ERFOLG",
  "Data": [
    {
      "UserName": "John123",
      "DisplayName": "John A.",
      "HasAPIAccess": wahr,
      "Payers": [
        {
          "IsDefault": true,
          "ColcoId": 1,
          "ColcoCode": 86,
          "PayerId": 1234,
          "PayerNumber": "GB000000123",
          "PayerName": "MATTHEW ALGIE & COMPANY LIMITED"
        }
      ]
    }
  ]
}

Antwortfelder

Feld	Typ	Beschreibung
Benutzername	String	Kennung des angemeldeten Benutzers
DisplayName	string	Name des angemeldeten Benutzers
HasAPIAccess	boolean	True wenn Benutzer Zugriff auf die angeforderte API hat
PayerId	integer	Payer Id zur Verwendung in nachfolgenden Anfragen
PayerNumber	string	Payer Number zur Verwendung in nachfolgenden Anfragen

2. Abfrage von Kundenkonten

Beschreibung: Dieser Endpunkt ermöglicht die Abfrage von Kundenkontodetails von der Shell Cards Platform mit flexiblen Suchkriterien und Paginierungsunterstützung. Verwenden Sie die im vorherigen Schritt erhaltene PayerId.

Pfad: POST /customer-management/v1/accounts

Beispielanforderung

curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filter": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "AKTIV",
    "IncludeCardSummary": true
  },
  "Seite": 1,
  "PageSize": 50
}'

Anfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
ColCoCode	integer	Ja	Erfassung Company Code (Shell Code)
PayerNumber	string	Yes	Payer Number des Kunden
Status	string	No	Kontostatusfilter (ACTIVE, GESPERRT, ABGESAGT, usw.)
IncludeCardSummary	boolean	No	Kartenzusammenfassungsdetails einschließen (Standard: true)
Page	integer	No	Seitennummer (Standard: 1)
PageSize	integer	No	Datensätze pro Seite (Standard: 50)

Beispielantwort

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "ERFOLG",
  "Data": [
    {
      "AccountId": 1,
      "AccountNumber": "GB000000124",
      "AccountFullName": "Acme Corporation",
      "Status": "Aktiv",
      "CurrencyCode": "EUR",
      "TotalCards": 1000,
      "TotalActiveCards": 500
    }
  ],
  "Seite": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Antwortfelder

Feld	Typ	Beschreibung
AccountId	integer	Konto Kennung
Kontonummer	String	Kontonummer
KontoVollerName	String	Voller Name des Kontos
Status	string	Aktueller Kontostatus
CurrencyCode	ISO-Währungscode
TotalCards	integer	Gesamtzahl Anzahl der Karten unter dem Konto
TotalActiveCards	ganzzahlig	Anzahl der aktiven Karten

3. Abfrage von Kartengruppen

Beschreibung: Dieser Endpunkt ruft Details zu Kartengruppen von der Shell Cards Platform mit flexiblen Suchkriterien und Paginierung ab. Kartengruppen helfen bei der Organisation von Karten innerhalb eines Kontos.

Pfad: POST /customer-management/v1/cardgroups

Beispielanfrage

curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filter": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE"
  },
  "Seite": 1,
  "PageSize": 50
}'

Anfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
ColCoCode	ganzzahlig	Ja	Sammeln Unternehmenscode
Zahlernummer	string	Ja	Zahlernummer des Kunden
Status	string	Ja	Kartengruppenstatus (AKTIV, TERMINATED, ALL)
Kartengruppenname	string	No	Filter nach Kartengruppenname (mindestens 2 Zeichen)

Beispielantwortung

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "ERFOLG",
  "Data": [
    {
      "CardGroupId": 40000,
      "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
      "Status": "AKTIV",
      "PrintOnCard": wahr,
      "CardTypeId": 1234,
      "TotalCards": 1234,
      "ActiveCards": 999
    }
  ],
  "Seite": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Antwortfelder

Feld	Typ	Beschreibung
CardGroupId	integer	Kartengruppenkennung
CardGroupName	string	Name der Kartengruppe Gruppe
Status	String	Status der Kartengruppe
TotalCards	integer	Gesamtanzahl der Karten in der Gruppe
ActiveCards	integer	Anzahl der aktiven Karten in der Gruppe

4. Kartengruppe erstellen

Beschreibung: Dieser Endpunkt erstellt eine neue Kartengruppe in der Shell Cards Platform und verschiebt optional bis zu 500 Karten in die neu erstellte Gruppe. Anfragen zum Verschieben von Karten werden nach der Validierung in eine Warteschlange gestellt.

Pfad: POST /customer-management/v1/createcardgroup

Beispielanfrage

curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  'ColCoCode': 86,
  "PayerNumber": "GB000000123",
  "AccountNumber": "GB000000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": wahr,
  "Karten": [
    {
      "AccountNumber": "GB99215176",
      "PAN": "7002051006629890645"
    }
  ]
}'

Anforderungsparameter

Parameter	Typ	Erforderlich	Beschreibung
ColCoCode	integer	Ja	Inkassounternehmen Code
Zahlernummer	string	Ja	Zahlernummer des Kunden
Kontonummer	string	Ja	Konto Nummer des Kunden
Kartengruppenname	String	Ja	Name der neuen Kartengruppe (1-40 Zeichen)
DruckaufKarte	boolean	Ja	Ob der Name der Kartengruppe auf die Karten geprägt werden soll
Karten	array	Nein	Liste der zu verschiebenden Karten (max 500)

Beispielantwortung

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "ERFOLG",
  "Data": [
    {
      "MainReference": 1234,
      "NewCardGroupReference": 5672,
      "SuccessfulRequests": [
        {
          "PAN": "7002051123456789145",
          "Referenz": 12345
        }
      ],
      "ErrorCards": []
    }
  ]
}

Antwortfelder

Feld	Typ	Beschreibung
Hauptreferenz	integer	Referenz Nummer zur Nachverfolgung der Gesamtanfrage
NewCardGroupReference	integer	Referenznummer für die Erstellung der Kartengruppe
SuccessfulRequests	array	Liste der erfolgreich in die Warteschlange gestellten Kartenverschiebungsanfragen
ErrorCards	array	Liste der Karten, deren Validierung fehlgeschlagen ist

Fehlerbehandlung

Die API verwendet standardmäßige HTTP-Statuscodes. Im Falle eines Fehlers werden zusätzliche Details im Antwortkörper bereitgestellt.

Fehlercode	Beschreibung	Lösung
E0001	Validierungsfehler	Überprüfen Sie die Anfrageparameter auf fehlende oder ungültige Werte
E0003	Unberechtigt	Überprüfen Sie die Anmeldeinformationen und stellen Sie sicher, dass der Benutzer Zugriff auf die Operation hat
E0005	Ressource nicht gefunden	Überprüfen Sie, ob die angeforderte Ressource existiert und zugänglich ist
9015	Kartengruppenname duplizieren	Verwenden Sie einen eindeutigen Kartengruppennamen für den Kunden