Shell B2B Mobility – API danych transakcji opłat drogowych – Przewodnik szybkiego startu

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

Przegląd

Interfejs API danych transakcji opłat drogowych Shell B2B Mobility to interfejs oparty na architekturze REST, który zapewnia kompleksowy dostęp do rejestrów transakcji opłat drogowych i powiązanych danych dla klientów usług mobilnościowych Shell. Interfejs ten umożliwia programistom programowe pobieranie, filtrowanie i analizowanie danych dotyczących transakcji opłat drogowych za pomocą kodu w celu uzgodnienia stanu konta, weryfikacji rozliczeń, zarządzania wydatkami oraz spełnienia wymogów zgodności.

Najważniejsze funkcje

Pobieranie danych dotyczących transakcji opłat drogowych według numeru konta
Filtrowanie transakcji według przedziału dat (data początkowa i końcowa)
Wyszukiwanie według statusu faktury i numeru rejestracyjnego pojazdu (VRN)
Zaawansowane opcje sortowania według wielu pól
Obsługa paginacji dla dużych zbiorów danych
Elastyczne filtrowanie pól w celu optymalizacji zawartości odpowiedzi
Kompleksowe szczegóły opłat drogowych, w tym punkty wjazdu/wyjazdu
Obsługa wielu sieci opłat drogowych i operatorów

Uwierzytelnianie

OAuth 2.0 (standardowa metoda uwierzytelniania)

Interfejs API danych transakcji opłat drogowych Shell wykorzystuje przepływ poświadczeń klienta OAuth 2.0 do bezpiecznego uwierzytelniania.

OAuth 2.0

Krok 1: Uzyskaj token 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 
Content-Type: application/json
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

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 upływem terminu ważności, aby zapewnić nieprzerwaną obsługę
Nigdy nie udostępniaj swojego client_secret ani nie osadzaj go w kodzie po stronie klienta

Środowiska

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

Środowisko	Podstawowy adres URL	Cel
Produkcyjne	https://api.shell.com/toll-data/v1	Aktywne środowisko produkcyjne
Testowe (UAT)	https://api-test.shell.com/toll-data/v1	Środowisko testowe i programistyczne

Adresy URL tokenów OAuth:

Środowisko	Adres URL tokenu
Produkcyjne	https://api.shell.com/v2/oauth/token
Testowe (UAT)	https://api-test.shell.com/v2/oauth/token

Wskazówka: Zawsze testuj integrację w środowisku testowym, zanim przejdziesz do środowiska produkcyjnego.

Szybki start

1. Uzyskaj swoje poświadczenia OAuth

Skontaktuj się z z działem pomocy technicznej 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/v2/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": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Wykonaj swoje pierwsze żądanie API

Przykład: Wyszukiwanie transakcji opłat drogowych

Przykład użycia cURL:

curl -X POST https://api-test.shell.com/toll-data/v1/transactions/search \
  -H "Authorization: Bearer eyJhbGci******NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "RequestId: eb621f45-a543-4d9a-a934-2f223b263c42" \
  -d '{
    "Filters": {
 "ColCoCode": 86,
 "PayerNumber": "NL20016398",
        "AccountNumber": "NL20027701",
 "Filter": "All",
 "FromDate": "2026-01-01",
 "ToDate": "2026-01-31"
    },
    "Page": 1,
    "PageSize": 10
}'

Przykładowa odpowiedź:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "TotalPages": 15,
  "PageSize": 10,
  "Data": [
    {
      "NetworkDescription": "Societa Autostradali",
 "TollChargerCode": "410|610",
 "DelcoCode": "714",
 "DelcoName": "Shell Fleet Solutions Consorzio",
      "NetworkCode": "TLI",
 "Network": "euroShell Consortio",
 "PurchasedInCountry": "Włochy",
 "PurchasedInCountryCode": "IT",
      "CardNumber": "707737*******334272",
      "Identyfikator karty": 123456789,
 "Nazwa grupy kart": "Shell Fleet Solutions Consorzio",
 "Numer rejestracyjny pojazdu": "KN 00000",
      „CostCenter”: „100”,
 „SystemEntryDate”: „20260123”,
 „SystemEntryTime”: „13:14:25”,
      "TransactionDate": "20260120",
 "TransactionTime": "10:30:00",
 "PostingDate": "20260123",
      "Czas zaksięgowania": "00:00:00",
 "Numer płatnika": "NL20016398",
 "Numer konta": "NL20027701",
 "Nazwa konta": "Nazwa konta testowego",
      "StartDate": "20260120",
 "StartTime": "06:47:41",
      "EndDate": "20260120",
 "EndTime": "07:30:15",
 "TollGateEntry": "ROMA NORD",
 "TollGateExit": "BRENNERO",
      "DistanceDriven": "71,6",
 "RouteDescription": "ROMA NORD – BRENNERO",
 "TransactionType": "Opłata drogowa",
 "ProductCode": "14",
 "ProductDescription": "Opłata drogowa",
      "Kwota netto transakcji": "127,1",
 "Podatek od transakcji": "0,0",
 "Kwota brutto transakcji": "127,1",
      "TransactionCurrencyCode": "EUR",
 "TransactionStatus": "Raportowanie",
 "InvoiceNumber": "8600397548",
 "InvoiceDate": "20260125",
      "Status faktury": "Zafakturowano",
 "Metoda płatności": "Płatność z dołu",
 "Numer seryjny pojazdu": "00049000000836932426",
 „EmissionClass”: „Euro 6”,
 „ContractID”: „fb75eb53-46eb-450b-862e-6045002c3fa8”,
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "TollOperator": "Toll4Europe",
      "TollDomain": "Toll4Europe",
 "TariffRelevantInformation": "Klasa pojazdu: 2, Liczba osi: 2, Kategoria drogi: Autostrada",
 "AdditionalTransactionInfo": "Lokalizacja: 1",
 "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

Przewodnik po punktach końcowych API

Transakcje opłat drogowych

Punkt końcowy	Metoda	Opis
/toll-data/v1/transactions/search	POST	Pobieranie danych transakcji opłat drogowych z elastycznym filtrowaniem i paginacją

Typowe przypadki użycia:

Pobieranie transakcji opłat drogowych według przedziału czasowego
Filtrowanie według statusu faktury (Zafakturowane, Niefakturowane, Wszystkie)
Wyszukiwanie według numeru rejestracyjnego pojazdu (VRN)
Filtruj według grupy kart
Sortuj transakcje według wielu kryteriów
Wybierz konkretne pola, aby zoptymalizować rozmiar odpowiedzi

Typowe przypadki użycia

W tej sekcji przedstawiono powiązania między typowymi scenariuszami biznesowymi a wzorcami korzystania z API, co pomoże szybko określić, jak wykorzystać API do konkretnych potrzeb.

Przypadek użycia 1: Codzienne uzgadnianie transakcji opłat drogowych

Scenariusz: Musisz codziennie uzgadniać wszystkie transakcje opłat drogowych swojej floty dla celów księgowych.