Shell B2B Mobility – API pre údaje o mýtnych transakciách – Príručka rýchleho spustenia

Verzia API: 1.0.0 | Overovanie: OAuth 2.0 | Stav: Produkčné

Prehľad

API Shell B2B Mobility pre údaje o mýtnych transakciách je API založené na REST, ktoré poskytuje komplexný prístup k záznamom o mýtnych transakciách a súvisiacim údajom pre zákazníkov mobility spoločnosti Shell. Toto API umožňuje vývojárom programovo získavať, filtrovať a analyzovať údaje o mýtnych transakciách na účely zosúlaďovania účtov, overenie fakturácie, správu výdavkov a splnenie požiadaviek na súlad s predpismi.

Kľúčové funkcie

Načítanie údajov o transakciách mýta podľa čísla účtu
Filtrovanie transakcií podľa časového rozsahu (od a do)
Vyhľadávanie podľa stavu faktúry a VRN (registračného čísla vozidla)
Pokročilé možnosti triedenia podľa viacerých polí
Podpora stránkovania pre veľké súbory údajov
Flexibilné filtrovanie podľa polí na optimalizáciu veľkosti odpovede
Komplexné údaje o mýte vrátane vstupných a výstupných bodov
Podpora viacerých mýtnych sietí a prevádzkovateľov

Overovanie

OAuth 2.0 (štandardná metóda overovania)

Rozhranie API Shell Toll Transaction Data používa postup overovania pomocou klientskych poverení OAuth 2.0 na zabezpečené overovanie.

Postup OAuth 2.0

Krok 1: Získanie prístupového tokenu

Požiadajte o prístupový token z koncového bodu OAuth token:

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

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Krok 2: Použitie prístupového tokenu v požiadavkách na API

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

Správa tokenov

Osvedčené postupy pri správe tokenov:

Prístupové tokeny majú obmedzenú platnosť (zvyčajne 15 minút)
Implementujte ukladanie tokenov do vyrovnávacej pamäte, aby ste sa vyhli zbytočným požiadavkám na tokeny
Obnovte tokeny pred uplynutím ich platnosti, aby ste zaistili neprerušovanú prevádzku
Nikdy nezdieľajte svoj client_secret ani ho nevkladajte do kódu na strane klienta

Prostredia

API je k dispozícii v dvoch prostrediach:

Prostredie	Základná URL	Účel
Produkčné	https://api.shell.com/toll-data/v1	Produkčné prostredie
Testovanie (UAT)	https://api-test.shell.com/toll-data/v1	Testovacie a vývojové prostredie

URL adresy tokenov OAuth:

Prostredie	URL tokenu
Produkčné	https://api.shell.com/v2/oauth/token
Test (UAT)	https://api-test.shell.com/v2/oauth/token

Tip: Vždy otestujte svoju integráciu v testovacom prostredí pred prechodom do produkčného prostredia.

Rýchly štart

1. Získajte svoje OAuth poverenia

Kontaktujte technickú podporu spoločnosti Shell
Požiadajte o prihlasovacie údaje OAuth 2.0 (client_id a client_secret)
Prečítajte si podmienky používania

2. Získanie prístupového tokenu

Najskôr si získajte svoj prístupový token OAuth:

Príklad s 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še-id-klienta&client_secret=vaše-tajné-kľúče-klienta"

Odpoveď:

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

3. Vytvorte svoju prvú požiadavku na API

Príklad: Vyhľadávanie mýtnych transakcií

Príklad s 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
}'

Príklad odpovede:

{
  "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": "Italy",
      "PurchasedInCountryCode": "IT",
 "CardNumber": "707737*******334272",
 "CardId": 123456789,
      "Názov skupiny kariet": "Shell Fleet Solutions Consorzio",
 "Registračné číslo vozidla": "KN 00000",
 "Nákladové stredisko": "100",
 "Dátum zadania do systému": "20260123",
      "Čas zadania do systému": "13:14:25",
 "Dátum transakcie": "20260120",
 "Čas transakcie": „10:30:00“,
 „Dátum zaúčtovania“: „20260123“,
 „Čas zaúčtovania“: „00:00:00“,
 „Číslo platiteľa“: „NL20016398“,
 „Číslo účtu“: "NL20027701",
 "Názov účtu": "Názov testovacieho účtu",
 "Dátum začiatku": "20260120",
 "Čas začiatku": "06:47:41",
      "EndDate": "20260120",
 "EndTime": "07:30:15",
 "TollGateEntry": "ROMA NORD",
 "TollGateExit": "BRENNERO",
      "Prejdená vzdialenosť": "71,6",
 "Popis trasy": "ROMA NORD – BRENNERO",
 "Typ transakcie": "Cestná daň",
 "Kód produktu": "14",
 "Popis produktu": "Cestná daň",
      "Čistá suma transakcie": "127,1",
 "Daň z transakcie": "0,0",
 "Hrubá suma transakcie": "127,1",
      "TransactionCurrencyCode": "EUR",
 "TransactionStatus": "Reporting",
 "InvoiceNumber": "8600397548",
 "InvoiceDate": "20260125",
      "InvoiceStatus": "Vyfakturované",
 "PaymentMethod": "Platba po dodaní",
 "OBUSerialNumber": "00049000000836932426",
      "EmissionClass": "Euro 6",
 "ContractID": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "TollOperator": "Toll4Europe",
      "TollDomain": "Toll4Europe",
 "TariffRelevantInformation": "Trieda vozidla: 2, Počet náprav: 2, Kategória cesty: Diaľnica",
      "AdditionalTransactionInfo": "Poloha: 1",
 "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

Referenčné koncové body API

Mýto transakcie

Koncový bod	Metóda	Popis
/toll-data/v1/transactions/search	POST	Načítanie údajov o mýtnych transakciách s flexibilným filtrovaním a stránkovaním

Bežné prípady použitia:

Načítanie transakcií mýta podľa časového rozsahu
Filtrovanie podľa stavu faktúry (Fakturované, Nefakturované, Všetko)
Vyhľadávanie podľa evidenčného čísla vozidla (VRN)
Filtrovať podľa skupiny kariet
Zoradiť transakcie podľa viacerých kritérií
Vyberte konkrétne polia na optimalizáciu veľkosti odpovede

Bežné prípady použitia

Táto časť priraďuje bežné obchodné scenáre k vzorom použitia API , aby ste mohli rýchlo zistiť, ako využiť API pre svoje konkrétne potreby.

Prípad použitia 1: Denné zosúlaďovanie mýtnych transakcií

Scenár: Z účtovných dôvodov potrebujete denne zosúlaďovať všetky mýtne transakcie vašej flotily.