API pro transakční údaje o mýtném Shell B2B Mobility – Průvodce rychlým startem

Verze API: 1.0.0 | Ověřování: OAuth 2.0 | Stav: Produkční

Přehled

API Shell B2B Mobility pro data o mýtných transakcích je API založené na REST, které poskytuje komplexní přístup k záznamům o mýtných transakcích a souvisejícím datům pro zákazníky mobility společnosti Shell. Toto API umožňuje vývojářům programově načítat, filtrovat a analyzovat data o mýtných transakcích pro účely odsouhlasení účtů, ověření fakturace, správy výdajů a splnění požadavků na dodržování předpisů.

Klíčové funkce

Načtení údajů o transakcích mýtného podle čísla účtu
Filtrování transakcí podle časového rozsahu (datum od a do)
Vyhledávání podle stavu faktury a VRN (registračního čísla vozidla)
Pokročilé možnosti třídění podle více polí
Podpora stránkování u rozsáhlých datových sad
Flexibilní filtrování podle polí pro optimalizaci objemu dat v odpovědi
Komplexní údaje o mýtném včetně vstupních a výstupních bodů
Podpora více mýtných sítí a provozovatelů

Ověřování

OAuth 2.0 (standardní metoda ověřování)

Rozhraní Shell Toll Transaction Data API využívá tokový proces OAuth 2.0 Client Credentials pro bezpečné ověření.

Proces OAuth 2.0

Krok 1: Získání přístupového tokenu

Požádejte o přístupový token z koncového bodu OAuth token:

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

grant_type=client_credentials&client_id=vaše-id-klienta&client_secret=vaše-tajemství-klienta

Krok 2: Použití přístupového tokenu v požadavcích na API

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

Správa tokenů

Osvědčené postupy pro správu tokenů:

Přístupové tokeny mají omezenou dobu platnosti (obvykle 15 minut)
Implementujte ukládání tokenů do mezipaměti, abyste se vyhnuli zbytečným žádostem o tokeny
Obnovte tokeny před vypršením platnosti, abyste zajistili nepřerušenou službu
Nikdy nesdílejte svůj client_secret ani jej nevkládat do kódu na straně klienta

Prostředí

API je k dispozici ve dvou prostředích:

Prostředí	Základní URL	Účel
Produkční	https://api.shell.com/toll-data/v1	Provozní prostředí
Testování (UAT)	https://api-test.shell.com/toll-data/v1	Testovací a vývojové prostředí

URL tokenů OAuth:

Prostředí	URL tokenu
Produkční	https://api.shell.com/v2/oauth/token
Testovací (UAT)	https://api-test.shell.com/v2/oauth/token

Tip: Před přechodem do produkčního prostředí vždy otestujte svou integraci v testovacím prostředí.

Rychlý start

1. Získejte své přihlašovací údaje OAuth

Kontaktujte technickou podporu Shell
Vyžádejte si přihlašovací údaje OAuth 2.0 (client_id a client_secret)
Prostudujte si podmínky služby

2. Získejte přístupový token

Nejprve si získejte svůj přístupový token OAuth:

Příklad příkazu 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-tajemství-klienta"

Odpověď:

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

3. Proveďte svůj první požadavek na API

Příklad: Vyhledání mýtných transakcí

Pří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
}'

Příklad odpovědi:

{
  "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,
 "CardGroupName": "Shell Fleet Solutions Consorzio",
 "VehicleRegistration": "KN 00000",
      „CostCenter“: „100“,
 „SystemEntryDate“: „20260123“,
 „SystemEntryTime“: „13:14:25“,
 „TransactionDate“: „20260120“,
      "TransactionTime": "10:30:00",
 "PostingDate": "20260123",
      "Čas zaúčtování": "00:00:00",
 "Číslo plátce": "NL20016398",
 "Číslo účtu": "NL20027701",
 "Název účtu": "Název testovacího účtu",
      "StartDate": "20260120",
 "StartTime": "06:47:41",
 "EndDate": "20260120",
 "EndTime": "07:30:15",
      "Vjezd na mýtnou bránu": "ROMA NORD",
 "Výjezd z mýtné brány": "BRENNERO",
 "Ujetá vzdálenost": "71,6",
 "Popis trasy": "ROMA NORD – BRENNERO",
      "TransactionType": "Silniční poplatek",
 "ProductCode": "14",
 "ProductDescription": "Silniční poplatek",
 "TransactionNetAmount": "127,1",
 "TransactionTax": "0,0",
 "TransactionGrossAmount": "127,1",
 "TransactionCurrencyCode": "EUR",
 "TransactionStatus": "Reporting",
 "InvoiceNumber": "8600397548",
      "Datum faktury": "20260125",
 "Stav faktury": "Vyfakturováno",
 "Způsob platby": "Platba po dodání",
 "Sériové číslo OBU": "00049000000836932426",
      "EmissionClass": "Euro 6",
 "ContractID": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "TollOperator": "Toll4Europe",
      "TollDomain": "Toll4Europe",
 "TariffRelevantInformation": "Třída vozidla: 2, Počet náprav: 2, Kategorie silnice: Dálnice",
 "AdditionalTransactionInfo": "Umístění: 1",
      "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

Přehled koncových bodů API

Mýtné transakce

Koncový bod	Metoda	Popis
/toll-data/v1/transactions/search	POST	Načtení údajů o mýtných transakcích s flexibilním filtrováním a stránkováním

Běžné případy použití:

Načtení transakcí mýtného podle časového rozsahu
Filtrování podle stavu faktury (fakturováno, nefakturováno, vše)
Vyhledávání podle registračního čísla vozidla (VRN)
Filtrovat podle skupiny karet
Seřadit transakce podle více kritérií
Vyberte konkrétní pole pro optimalizaci velikosti odpovědi

Běžné případy použití

Tato část přiřazuje běžné obchodní scénáře k vzorcům využití API, aby vám pomohla rychle zjistit, jak API využít pro vaše konkrétní potřeby.

Případ použití 1: Denní odsouhlasení transakcí mýtného

Scénář: Z účetních důvodů potřebujete denně odsouhlasit všechny transakce mýtného z vaší flotily.