Shell B2B Mobility Card Management API – Przewodnik szybkiego startu

Wersja API: 3.1.5 | Uwierzytelnianie: OAuth 2.0 | Status: Wersja produkcyjna

Przegląd

Interfejs API zarządzania kartami Shell to interfejs oparty na architekturze REST, który umożliwia programistom programowe zarządzanie kartami paliwowymi Shell. API obsługuje wyszukiwanie kart, zamawianie, aktualizację statusu, anulowanie oraz różne inne operacje związane z zarządzaniem kartami.

Uwaga: Niniejszy przewodnik obejmuje wyłącznie punkty końcowe uwierzytelniane za pomocą OAuth 2.0 (ścieżka bazowa: /card-management/v1). Starsze punkty końcowe z uwierzytelnianiem Basic Auth (/fleetmanagement/v1/card) nie zostały uwzględnione, ponieważ są stopniowo wycofywane.

Najważniejsze funkcje

• Wyszukiwanie i filtrowanie kart paliwowych według elastycznych kryteriów
• Zamawianie nowych kart i śledzenie statusu zamówienia
• Blokuj, odblokowuj i anuluj karty
• Zaktualizuj adresy dostawy kart
• Zarządzaj ustawieniami automatycznego odnawiania kart
• Przenoś karty między grupami kart i kontami
• Poproś o przypomnienia o kodzie PIN

Ważna informacja – OAuth 2.0

WAŻNE: OAuth 2.0 jest obecnie standardową metodą uwierzytelniania

• Nowe integracje: Korzystaj z OAuth 2.0 od samego początku
• Istniejące integracje: Zaplanuj migrację do OAuth 2.0
• Metody starszego typu: Uwierzytelnianie podstawowe i klucz API są stopniowo wycofywane

Skontaktuj się z pomocą techniczną Shell, aby uzyskać swoje dane uwierzytelniające OAuth 2.0 (client_id i client_secret).

Uwierzytelnianie

OAuth 2.0 (standardowa metoda uwierzytelniania)

Interfejs API zarządzania kartami Shell wykorzystuje proces uwierzytelniania OAuth 2.0 oparty na poświadczeniach klienta w celu zapewnienia bezpiecznego uwierzytelniania.

OSTRZEŻENIE: Wszyscy klienci powinni zaplanować przejście na uwierzytelnianie OAuth 2.0. Jest to zalecana i przyszłościowa metoda uwierzytelniania dla interfejsu API zarządzania kartami Shell. Starsze metody uwierzytelniania są stopniowo wycofywane.

Przebieg OAuth 2.0

Krok 1: Uzyskanie tokenu dostępu

Poproś o token dostępu z punktu końcowego tokenów OAuth:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=twój-identyfikator-klienta&client_secret=twój-sekret-klienta

Krok 2: Użyj tokenu dostępu w żądaniach API

Authorization: Bearer <token-dostępu>
Content-Type: application/json

Zarządzanie tokenami

Najlepsze praktyki dotyczące zarządzania tokenami:

• Tokeny dostępu mają ograniczony czas ważności (zazwyczaj 15 minut)
• Wprowadź buforowanie tokenów, aby uniknąć niepotrzebnych żądań tokenów
• Odśwież tokeny przed wygaśnięciem, aby zapewnić nieprzerwaną obsługę
• Nigdy nie udostępniaj swojego client_secret ani nie osadzaj go w kodzie po stronie klienta

Strategia wdrażania OAuth 2.0

Dlaczego warto przejść na OAuth 2.0?

Korzyści w zakresie bezpieczeństwa:

• Standardowy w branży protokół uwierzytelniania
• Tokeny dostępu ograniczone czasowo zmniejszają ryzyko związane z bezpieczeństwem
• Brak przesyłania danych uwierzytelniających przy każdym żądaniu
• Lepsza obsługa rotacji i unieważniania tokenów

Korzyści operacyjne:

• Zwiększona skalowalność i wydajność
• Lepsze możliwości monitorowania i audytu
• Uproszczone zarządzanie danymi uwierzytelniającymi
• Integracja z myślą o przyszłości

Ścieżka migracji

Jeśli obecnie korzystasz ze starszych metod uwierzytelniania, postępuj zgodnie z poniższą ścieżką migracji:

1. Poproś o poświadczenia OAuth 2.0 na stronie pomocy technicznej Shell
2. Zaimplementuj zarządzanie tokenami OAuth w swojej aplikacji
3. Przeprowadź dokładne testy w środowisku testowym/Sandbox
4. Stosuj równoległe uwierzytelnianie (OAuth + dotychczasowe) w trakcie przejścia
5. Monitoruj i weryfikuj integracji OAuth
6. Przejście na wyłączną obsługę OAuth po zweryfikowaniu
7. Wycofaj dotychczasowy system uwierzytelniania po pomyślnej migracji

Środowiska

API jest dostępne w dwóch środowiskach:

Wskazówka: Zawsze testuj integrację w środowisku testowym przed przejściem do środowiska produkcyjnego.

Szybki start

1. Uzyskaj swoje dane uwierzytelniające OAuth

• Skontaktuj się z pomoc techniczną Shell
• Poproś o dane uwierzytelniające OAuth 2.0 (client_id i client_secret)
• Zapoznaj się z warunki korzystania z usługi

2. Uzyskaj token dostępu

Najpierw uzyskaj swój token dostępu OAuth:

Przykład cURL:

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=twój-identyfikator-klienta&client_secret=twój-sekret-klienta"

Odpowiedź:

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

3. Wyślij swoje pierwsze żądanie API

Przykład: Wyszukaj aktywne karty

Przykład z użyciem cURL:

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

Przykładowa odpowiedź:

{
"RequestId": "233e4567-e89b-12d3-a456-426614174000",
"Status": "SUCCESS",
"Data": [
{
"CardId": 125,
"PAN": "7002861007636000020",
"MaskedPAN": "7002861**000020",
"DriverName": "ROBERT SMITH",
"VehicleRegistrationNumber": "MV65YLH",
"StatusDescription": "Active",
"ExpiryDate": "20250531",
"CardTypeCode": "7077861",
"Nazwa_typu_karty": "Karta Shell"
}
],
"Strona": 1,
"Rozmiar_strony": 50,
"Łączna_liczba_stron": 1,
"TotalRecords": 1
}

Opis punktów końcowych API

Wyszukiwanie i pobieranie kart

Typowe przypadki użycia:

• Wyszukiwanie według statusu karty (AKTYWNA, ZABLOKOWANA, WYGASŁA itp.)
• Filtruj według nazwiska kierowcy lub numeru rejestracyjnego pojazdu
• Wyszukiwanie według numeru PAN (ostatnie 4 cyfry)
• Znajdź karty, których ważność wygasa za X dni

Podsumowanie karty

Zwraca:

• Łączna liczba kart według statusu
• Podsumowanie statystyk według typu karty
• Podział na aktywne i nieaktywne

Zamawianie kart

Wymagane informacje do zamówienia karty:

• ColCoCode (kod firmy pobierającej opłatę)
• PayerNumber lub PayerId
• Numer konta
• Typ karty i konfiguracja
• Szczegóły adresu dostawy

Zarządzanie statusem karty

Działania związane ze statusem:

• BLOKUJ – Tymczasowe zablokowanie karty
• ODBLOKUJ – Ponownie aktywuj zablokowaną kartę
• USZKODZONA – Zgłoś kartę jako uszkodzoną i poproś o wymianę
• TEMP_BLOCK_CUSTOMER - Tymczasowa blokada zainicjowana przez klienta
• TEMP_BLOCK_SHELL - Tymczasowa blokada zainicjowana przez system operacyjny

UWAGA: Anulowanie karty jest nieodwracalne i nie można go cofnąć.

Dodatkowe punkty końcowe

Przykłady użycia

Przykład 1: Wyszukiwanie kart, których ważność wkrótce wygaśnie

POST /card-management/v1/search

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

Przykład 2: Tymczasowe zablokowanie karty

POST /card-management/v1/updatestatus

{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"Action": "TEMP_BLOCK_CUSTOMER",
"Reason": "Karta chwilowo zagubiona"
}
]
}

Przykład 3: Anulowanie kart

POST /card-management/v1/cancel

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

Obsługa błędów

Typowe kody błędów

Najlepsze praktyki

1. Wprowadź uwierzytelnianie OAuth 2.0

WAŻNE:Wszyscy klienci powinni przejść na uwierzytelnianie OAuth 2.0. Należy wdrożyć odpowiednie zarządzanie tokenami:

• Buforuj tokeny dostępu i wykorzystuj je ponownie do momentu wygaśnięcia
• Odświeżaj tokeny przed ich wygaśnięciem (zalecane 60 sekund przed)
• Bezpieczne przechowywanie poświadczeń klienta (używaj zmiennych środowiskowych lub menedżera sekretów)
• Nigdy nie rejestruj ani nie ujawniaj tokenów dostępu w kodzie po stronie klienta

2. Używaj identyfikatorów żądań

Zawsze dołączaj unikalny identyfikator żądania (RequestId w formacie GUID), aby zapewnić śledzenie od początku do końca

3. Wprowadź paginację

W przypadku dużych zbiorów danych stosuj paginację, aby uniknąć przekroczenia limitu czasu

4. Testuj w środowisku testowym (Sandbox)

Zawsze testuj integrację w środowisku testowym (Test/Sandbox) przed przejściem do środowiska produkcyjnego

Przykłady SDK i kodu

Shell udostępnia oficjalne zestawy SDK oraz obszerne przykłady kodu, które przyspieszą integrację z interfejsem API zarządzania kartami.

Dostępne języki SDK

• Python – w pełni funkcjonalny zestaw SDK z obsługą OAuth 2.0
• TypeScript - Bezpieczny pod względem typów zestaw SDK z pełnymi definicjami typów
• Java - SDK klasy korporacyjnej
• C#/.NET - Pełna integracja z platformą .NET
• PHP - Łatwa w użyciu biblioteka PHP
• Ruby - Pakiet Ruby gem zapewniający płynną integrację

Zobacz oficjalne zestawy SDK i dokumentację

Wsparcie i zasoby

Wsparcie techniczne

• Wsparcie: Pomoc techniczna dotycząca powłoki

Dokumentacja

• Warunki korzystania z usługi
• Dokumentacja API

Pomoc

Kontaktując się z działem pomocy technicznej, podaj:

1. swój identyfikator client_id (nigdy nie udostępniaj swojego client_secret ani tokenów dostępu)
2. Identyfikator żądania (RequestId) z odpowiedzi API
3. Sygnatura czasowa żądania
4. Środowisko (produkcyjne/testowe)

Ostatnia aktualizacja: 15 czerwca 2026 r.
Wersja dokumentu: 1.0
Wersja API: 3.1.5