API za podatke o transakcijah cestnin Shell B2B Mobility – Priročnik za hiter začetek

Različica API-ja: 1.0.0 | Preverjanje pristnosti: OAuth 2.0 | Stanje: Produkcijsko

Pregled

API Shell B2B Mobility za podatke o transakcijah cestnin je API na podlagi REST, ki omogoča celovit dostop do zapisov o transakcijah cestnin in povezanih podatkov za stranke mobilnih storitev Shell. Ta API razvijalcem omogoča programsko pridobivanje, filtriranje in analizirajo podatke o transakcijah cestnin na programski način za usklajevanje računov, preverjanje zaračunavanja, upravljanje stroškov in izpolnjevanje zahtev glede skladnosti.

Ključne značilnosti

Pridobivanje podatkov o transakcijah cestnin po številki računa
Filtriranje transakcij po časovnem obdobju (začetni in končni datum)
Iskanje po statusu računa in VRN (registrska številka vozila)
Napredne možnosti razvrščanja po več poljih
Podpora za stranjenje pri velikih zbirkah podatkov
Prilagodljivo filtriranje po poljih za optimizacijo obsega odgovora
Izčrpni podatki o cestninah, vključno z vstopnimi/izstopnimi točkami
Podpora več cestninskih omrežij in operaterjev

Preverjanje pristnosti

OAuth 2.0 (standardna metoda avtentifikacije)

API za podatke o cestninskih transakcijah Shell uporablja postopek OAuth 2.0 Client Credentials za varno avtentifikacijo.

Postopek OAuth 2.0

Korak 1: Pridobite dostopni žeton

Zahtevajte dostopni žeton pri končni točki za žetone OAuth:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=vaša-identifikacijska-številka-odjemalca&client_secret=vaša-skrivnost-odjemalca

Korak 2: Uporaba dostopnega žetona v zahtevkih API

Authorization: Bearer 
Content-Type: application/json
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

Upravljanje žetonov

Najboljše prakse pri upravljanju žetonov:

Dostopni žetoni imajo omejeno veljavnost (običajno 15 minut)
Uvedite shranjevanje žetonov v predpomnilnik, da se izognete nepotrebnim zahtevkom za žetone
Osvežite žetone pred iztekom veljavnosti, da zagotovite neprekinjeno delovanje storitve
Nikoli ne delite svojega client_secret ali ga vstavljajte v kodo na strani odjemalca

Okolja

API je na voljo v dveh okoljih:

Okolje	Osnovni URL	Namen
Proizvodno	https://api.shell.com/toll-data/v1	Proizvodno okolje v živo
Testno (UAT)	https://api-test.shell.com/toll-data/v1	Testno in razvojno okolje

URL-ji za OAuth-token:

Okolje	URL žetona
Proizvodno	https://api.shell.com/v2/oauth/token
Testno (UAT)	https://api-test.shell.com/v2/oauth/token

Nasvet: Svojo integracijo vedno preizkusite v testnem okolju, preden preidete v produkcijo.

Hiter začetek

1. Pridobite svoje OAuth-pooblastila

Obrnite se na tehnično podporo Shell
Zahtevajte poverilnice OAuth 2.0 (client_id in client_secret)
Preglejte pogoje uporabe

2. Pridobite dostopni žeton

Najprej pridobite svoj OAuth dostopni žeton:

Primer 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=vaša-ID-odjemalca&client_secret=vaša-skrivnost-odjemalca"

Odgovor:

{
  "access_token": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Pošljite svojo prvo zahtevo API

Primer: Iskanje transakcij cestnin

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

Primer odgovora:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "SkupnoŠteviloStrani": 15,
  "VelikostStrani": 10,
  "Podatki": [
    {
 "OpisMreže": "Societa Autostradali",
 "KodaZbiralcaCestnine": "410|610",
      "DelcoCode": "714",
 "DelcoName": "Shell Fleet Solutions Consorzio",
 "NetworkCode": "TLI",
 "Network": "euroShell Consortio",
 "PurchasedInCountry": "Italy",
      "PurchasedInCountryCode": "IT",
 "CardNumber": "707737*******334272",
 "CardId": 123456789,
      "CardGroupName": "Shell Fleet Solutions Consorzio",
 "VehicleRegistration": "KN 00000",
 "CostCenter": "100",
      "Datum vnosa v sistem": "20260123",
 "Čas vnosa v sistem": "13:14:25",
 "Datum transakcije": "20260120",
      "Čas transakcije": "10:30:00",
 "Datum knjiženja": "20260123",
 "Čas knjiženja": "00:00:00",
      "PayerNumber": "NL20016398",
 "AccountNumber": "NL20027701",
 "AccountName": "Ime testnega računa",
 "StartDate": "20260120",
      "StartTime": "06:47:41",
 "EndDate": "20260120",
 "EndTime": "07:30:15",
 "TollGateEntry": "ROMA NORD",
      "Izhod iz cestninske postaje": "BRENNERO",
 "Prevožena razdalja": "71,6",
 "Opis poti": "ROMA NORD – BRENNERO",
 "Vrsta transakcije": "Cestnina",
      "ProductCode": "14",
 "ProductDescription": "Cestnina",
 "TransactionNetAmount": "127,1",
 "TransactionTax": "0,0",
 "TransactionGrossAmount": "127,1",
      "TransactionCurrencyCode": "EUR",
 "TransactionStatus": "Poročanje",
 "InvoiceNumber": "8600397548",
 "InvoiceDate": "20260125",
      "InvoiceStatus": "Izstavljeno",
 "PaymentMethod": "Plačilo po prejemu",
 "OBUSerialNumber": "00049000000836932426",
      "Razred emisij": "Euro 6",
 "ID pogodbe": "fb75eb53-46eb-450b-862e-6045002c3fa8",
 "ID transakcije Shell": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "Upravljavec cestnine": "Toll4Europe",
 "Domena cestnine": "Toll4Europe",
 "TariffRelevantInformation": "Razred vozila: 2, Število osi: 2, Kategorija ceste: Avtocesta",
 "AdditionalTransactionInfo": "Lokacija: 1",
 "TCInvoiceNumber": "12343343",
      "TCInvoiceDate": "20260123"
    }
  ]
}

Referenca končnih točk API-ja

Transakcije cestnin

Končna točka	Metoda	Opis
/toll-data/v1/transactions/search	POST	Pridobivanje podatkov o transakcijah cestnine s prilagodljivim filtriranjem in stranjenjem

Pogosti primeri uporabe:

Pridobivanje transakcij cestnin po časovnem obdobju
Filtriranje po statusu računa (zaračunano, nezaračunano, vse)
Iskanje po registrski številki vozila (VRN)
Filtriraj po skupini kartic
Razvrstite transakcije po več merilih
Izberite določena polja za optimizacijo velikosti odziva

Pogosti primeri uporabe

V tem poglavju so pogosti poslovni scenariji povezani z vzorci uporabe API-ja, da boste lažje ugotovili, kako API uporabiti za svoje specifične potrebe.

Primer uporabe 1: Dnevno usklajevanje transakcij cestnin

Scenarij: Zaradi računovodskih namenov morate dnevno uskladiti vse transakcije cestnin iz vaše flote.