API pre transakčné údaje z kariet Shell B2B Mobility – Príručka rýchleho spustenia

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

Viac

API transakčných údajov kariet Shell je rozhranie založené na REST, ktoré umožňuje vývojárom programovo získavať a analyzovať transakčné údaje z palivových kariet Shell. API poskytuje prístup k transakciám s cenami, poplatkom, cenám založeným na objeme, pravidlám bonusov, výnimkám a prehľadom o používaní kariet.

Poznámka:Táto príručka sa týka iba koncových bodov overovaných prostredníctvom OAuth 2.0 (základná cesta: /transaction-data/v1). Staršie koncové body s overovaním Basic Auth (/fleetmanagement/v1/transaction) nie sú zahrnuté, pretože sa postupne vyraďujú z prevádzky.

Kľúčové funkcie

Načítanie podrobností o transakciách s cenami vrátane transakcií s elektrickými vozidlami
Prístup k podrobnostiam o transakciách s palivom vrátane predávaných položiek a poplatkov
Získanie súhrnných údajov o transakciách s palivom a transakciách NFR
Vyhľadajte pravidlá cenotvorby na základe objemu a bonusové pravidlá
Načítajte položky poplatkov a súhrnné údaje o poplatkoch
Získajte prístup k výnimkám týkajúcim sa kariet a transakcií
Analýza údajov o používaní kariet a výdavkoch
Podpora dotazov na transakcie s viacerými platiteľmi

Dôležité upozornenie – OAuth 2.0

DÔLEŽITÉ: OAuth 2.0 je teraz štandardnou metódou overovania

Nové integrácie: Používajte OAuth 2.0 hneď od začiatku
Existujúce integrácie: Naplánujte si prechod na OAuth 2.0
Staršie metódy: Základné overovanie (Basic Auth) sa postupne vyraďuje

Kontaktujte technickú podporu Shell, aby ste získali svoje prihlasovacie údaje pre OAuth 2.0 (client_id a client_secret).

Overovanie

OAuth 2.0 (štandardná metóda overovania)

Rozhranie API pre údaje o transakciách kartou Shell používa postup overovania pomocou klientských poverení OAuth 2.0 na zabezpečené overovanie.

VAROVANIE: Všetci zákazníci by mali zvážiť prechod na overovanie pomocou OAuth 2.0. Ide o odporúčanú a perspektívnu metódu overovania pre rozhranie API transakčných údajov kariet Shell. Staršie metódy overovania sa postupne vyraďujú z používania.

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 rozhranie API

Authorization: Bearer 
Content-Type: application/json

Správa tokenov

Osvedčené postupy pri správe tokenov postupy:

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 nezverejňujte svoj client_secret ani ho nevkladajte do kódu na strane klienta

Stratégia zavádzania OAuth 2.0

Prečo prejsť na OAuth 2.0?

Výhody v oblasti bezpečnosti:

Autentifikačný protokol podľa priemyselných štandardov
Časovo obmedzené prístupové tokeny znižujú bezpečnostné riziká
Pri každej požiadavke sa neprenášajú žiadne prihlasovacie údaje
Lepšia podpora rotácie a zrušenia tokenov

Prevádzkové výhody:

Zlepšená škálovateľnosť a výkon
Lepšie možnosti monitorovania a auditu
Zjednodušená správa/li>
Integrovaná ochrana proti budúcimintegrácia

Postup migrácie

Ak v súčasnosti používate staršie metódy overovania, postupujte podľa tohto postupu migrácie:

Požiadajte o prihlasovacie údaje OAuth 2.0 od technickej podpory Shell
Implementujte správu tokenov OAuth vo vašej aplikácii
Dôkladne otestujte v testovacom/Sandbox
Počas prechodu prevádzkujte paralelné overovanie (OAuth + starý systém)
Monitorujte a overte integráciu OAuth
Po overení prejsť výlučne na OAuth
Vyradiť staré overovanie po úspešnej migrácii

Prostredia

API je k dispozícii v dvoch prostrediach:

Prostredie	Základná URL	Účel
Produkčné	https://api.shell.com	Živé produkčné prostredie
Testovacie (Sandbox)	https://api-test.shell.com/test	Testovacie a vývojové prostredie

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

Rýchly štart

1. Získajte svoje OAuth poverenia

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

2. Získajte prístupový token

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"

Odpoveď:

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

3. Vytvorte svoju prvú požiadavku na API

Príklad: Získanie transakcií s cenami

Príklad cURL:

curl -X POST https://api-test.shell.com/test/transaction-data/v1/priced \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "ColCoCode": "5",
 "PayerNumber": "DE26667080",
 "InvoiceStatus": "A",
 "IncludeFees": true,
 "FromDate": "2024-12-01 00:00:00",
 "ToDate": "2025-01-20 00:00:00"
    },
    "Page": 1,
    "PageSize": 1
}'

Príklad odpovede:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountName": "Blue Colour Ltd",
 "AccountId": 29484,
 "AccountNumber": "DE26667080",
 "AccountShortName": "Mathew",
 "Additional1": "GBALLEGO0002452",
 "Additional2": "GBALLEGO0002452",
 "Additional3": "GBALLEGO0002452",
      "Additional4": "GBALLEGO0002452",
 "AllowClearing": "Null",
 "AuthorisationCode": 300796,
 "TransactionStatus": "Y",
      "DriverName": "SATTY BHAMRA",
 "CardExpiryPeriod": 2204,
 "CardExpiry": "20220101",
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "IssuerCode": 7002,
      "PAN karty": "7002053465789891000",
 "Kód uvoľnenia": 9,
 "Poradové číslo karty": 617,
      "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0,0051,
 „ColCoExchangeRate“: 0,851858,
 „Symbol meny faktúry": "GBP",
 "Označenie opravy": true,
 "Číslo CRM": 10,
 "Krajina zákazníka": "Spojené kráľovstvo",
 "Kód meny zákazníka": "GBP",
 "Symbol meny zákazníka": "£",
 "Zľava z čistej sumy v mene zákazníka": 0,
 "Efektívna zľava v mene zákazníka": -0,22,
 „Efektívna jednotková zľava v mene zákazníka“: -0,0051,
 „Jednotková cena v mene faktúry“: 1,1024,
      "Daň na faktúre": 0,
 "Hrubá suma faktúry": 57,25,
 "Čistá suma faktúry": 47,71,
      "DPH z čistej sumy v mene zákazníka": 9,54,
 "Hrubá maloobchodná cena za jednotku pre zákazníka": 0,
 "Celková hrubá maloobchodná hodnota pre zákazníka": 57,52,
 "Celková maloobchodná hodnota v mene zákazníka (netto)": 47,93,
 "Popis typu transakcie": 9,59,
 "Zľava z čistej sumy v mene transakcie": -0,22,
      „Efektívna zľava v mene transakcie“: -0,22,
 „Výmenný kurz medzi krajinou dodávateľa a krajinou odberateľa“: 0,
 „Karty“: [
        275549
 ],
 "Jednotková zľava v mene transakcie": -0,005,
      "TransactionGrossAmount": 57,25,
 "TransactionNetAmount": 47,71,
 "TransactionTax": 9,54,
 "VATonNetAmount": 9,54,
 „DelcoListPriceUnitNet“: 0,
 „DelcoRetailPriceUnitGross“: 1,32888,
 „UnitPriceInTransactionCurrency“: 1,1074,
 „DelcoRetailPriceUnitNet“: 1,1074,
 „DelcoRetailValueTotalGross“: 57,52,
 „DelcoRetailValueTotalNet“: 47,93,
 „TransactionCurrencySymbol“: "$",
 "DiscountType": 1,
 "DisputeStatus": false,
 "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
      "IncomingProductCode": 23,
 "PostingDate": "20210802",
 "PostingTime": "14:15:22",
 "ProductCode": 30,
 "ProductName": "Bezolovnatý – stredný oktanový počet",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
      "Location": "Shell Broadway Ring",
 "SiteName": "Shell Broadway Ring",
 "SiteCode": 32,
 "IncomingSiteNumber": 15,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceDate": "20210802“,
 „Číslo faktúry“: 3201016193,
 „Palivový produkt“: true,
 „Platí DPH“: „Y“,
      "PayerName": "Colours Services Ltd",
 "PayerNumber": "GB12121212",
 "ParentCustomerNumber": "GB12121212",
 "Skupina platiteľa": "H312066",
 "Názov skupiny platiteľa": "12162566 – SLUŽBA PALIVOVÝCH KARIET",
 "Kontrolná číslica": 6,
      "Indikátor čistej faktúry": "Y",
 "Kód Delco": 5,
 "Kód siete": 3,
      "Krajina nákupu": "Spojené kráľovstvo",
 "Krajina prevádzky": "Spojené kráľovstvo",
 "Krajina DPH": "Spojené kráľovstvo",
 "Názov dodávateľa": "Shell U.K. Oil Products Limited",
 "Sieť": "Shell",
      "Zadaná hodnota tachometra": 0,
 "Pôvodné ID predajnej položky": "Null",
 "Popis ID vozového parku": "YG67OUM",
 „ParentCustomerId“: 6494,
 „PINIndicator“: „Y, N“,
 „ProductGroupName“: „Poplatky“,
 „PurchasedInCountryCode“: „GB",
 "Quantity": 43,28,
 "RebateRate": 0,0022,
 "ReceiptNumber": 6803,
 "RefundFlag": "Y",
 "SiteGroupId": 202,
      "Názov skupiny prevádzok": "CZ 9100 ECONOMY NETWORK",
 "Zemepisná šírka": 53,83606,
      "Longitude": -1,61854,
 "DelCoExchangeRate": 0,851858,
 "EuroRebateAmount": -0,258259,
 "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
      „IsInvoiced“: false,
 „TransactionCurrencyCode“: „GBP“,
 „CreditDebitCode“: „D alebo C“,
 „TransactionDate“: „20210801“,
 „TransactionTime“: „12:16:58“,
      "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
 "VATCategory": "Štandardná sadzba DPH Spojeného kráľovstva",
      "VATRate": 0,2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
 "ColCoGrossAmount": 57,25,
      "Čistá suma ColCo": 47,71,
 "Suma DPH ColCo": 9,54,
 "Symbol pôvodnej meny": "$",
 "Kód pôvodnej meny": "$",
 "Pôvodná suma DPH": 0,
      "Text na reliéfe": "PARKLANE PROPERTIES LTD",
 "Pôvodný výmenný kurz": 0,
 "Dátum faktúry pôvodnej transakčnej položky": „20220202“,
 „FeeTypeId“: 1,
 „LineItemDescription“: true,
      "Popis pravidla poplatku": "Jednoduchý poplatok",
 "Frekvencia": 1,
 "ID pravidla poplatku": 1,
 "Dátum zadania do systému": "20210828",
 "Čas zadania do systému": "20:21:08",
 "IsManual": "Y",
 "OriginalTransactionItemId": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
 "OriginalTransactionItemInvoiceId": 234,
      "PayerShortName": "FUEL CARD SERVICES LTD",
      "ReverseCharge": "Y",
 "OriginalGrossAmount": 57,25,
 "OriginalNetAmount": 57,25,
 "UnitOfMeasure": "L",
 "RoadType": "Národná cesta",
      "Kód krajiny zákazníka podľa ISO": "DE",
 "Prevádzkovateľ EV": "Shell Recharge",
 "Sériové číslo EV": "GBALLEGO0002452",
 "Sériové číslo nabíjacej stanice EV": "GBALLEGO0002452",
 "Typ konektora nabíjacej stanice elektromobilu": 5,
 "Popis typu konektora nabíjacej stanice elektromobilu": "DC 50 kW",
      "EVChargeDuration": "PT3205S",
 "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
 "EVChargeEndDate": "2022-08-01",
 "EVChargeEndTime": "20:08:01",
 "HostingCollectingCompanyNumber": 0,
 "TransactionId": 0,
 "FuelOnly": true,
 "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 5
}

Referenčné koncové body API

Transakcie s cenou

Koncový bod	Metóda	Popis
/transaction-data/v1/priced	POST	Získanie podrobností o transakciách s cenou vrátane transakcií s elektrickými vozidlami (OAuth 2.0)
/transaction-data/v1/pricedtransaction	POST	Získanie podrobností o transakciách za palivo vrátane predávaných položiek a poplatkov (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions	POST	Získanie podrobností o transakciách s cenou pre viacerých platiteľov (OAuth 2.0)

Bežné prípady použitia:

Načítanie transakcií podľa časového rozsahu
Filtrovanie podľa stavu faktúry (fakturované, nefakturované atď.)
Vyhľadávanie podľa čísla karty (PAN) alebo evidenčného čísla vozidla
Získať transakcie za nabíjanie elektromobilov
Vyhľadávanie transakcií viacerých platiteľov

Prehľady transakcií

Koncový bod	Metóda	Popis
/transaction-data/v1/pricedtransactionssummary	POST	Získať súhrnné údaje o transakciách s cenami pre palivo a NFR vrátane predávaných položiek a poplatkov (OAuth 2.0)
/transaction-data/v1/cardusagesummary	POST	Získanie analýzy výdavkov a súhrnu využitia karty (OAuth 2.0)

Vrátené údaje:

Agregované údaje o transakciách podľa obdobia
Celkové objemy a sumy
Rozpis podľa typu a kategórie produktu
Analýza výdavkov na úrovni karty

Správa poplatkov

Koncový bod	Metóda	Popis
/transaction-data/v1/feessummary	POST	Získanie súhrnných údajov o položkách poplatkov pre daného platiteľa (OAuth 2.0)

Informácie o poplatkoch:

Načítanie položiek poplatkov uplatnených na transakcie
Prehľad všetkých poplatkov podľa obdobia
Rozpis poplatkov podľa typu a kategórie
Analýza poplatkov na úrovni platiteľa

Pravidlá založené na objeme

Koncový bod	Metóda	Popis
/transaction-data/v1/volumebasedpricing	POST	Získanie nastavenia pravidiel poplatkov za omeškanie pre daného platiteľa (OAuth 2.0)
/transaction-data/v1/volumebasedbonus	POST	Získanie nastavenia pravidiel bonusov a pridružených bonusov pre daného plátcu (OAuth 2.0)

Funkcie založené na objeme:

Prístup k pravidlám cenotvorby na základe objemu
Načítanie pravidiel výpočtu bonusov
Získanie konfigurácií bonusov za pridruženie

Výnimky

Koncový bod	Metóda	Popis
/transaction-data/v1/exceptions	POST	Načítanie výnimiek súvisiacich s kartou alebo transakciou (OAuth 2.0)

Typy výnimiek:

Chyby pri overovaní transakcií
Anomálie pri používaní karty
Výnimky pri autorizácii

Bežné prípady použitia

Táto časť priraďuje bežné obchodné scenáre k príslušným koncovým bodom API, aby vám pomohla rýchlo zistiť, ktoré API použiť pre vaše konkrétne potreby.

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

Scenár: Z účtovných dôvodov potrebujete denne zosúlaďovať všetky transakcie z vašich firemných kariet.

Odporúčané rozhranie API: /transaction-data/v1/priced

Prečo práve toto API: Tento koncový bod poskytuje komplexné podrobnosti o transakciách vrátane transakcií za nabíjanie elektrických vozidiel, podporuje flexibilné filtrovanie podľa dátumu a zahŕňa fakturované aj nefakturované transakcie. Je ideálny na denné zosúlaďovanie a podporuje stránkovanie pri práci s veľkými dátovými súbormi.

Kľúčové parametre:

PostingDateFrom a PostingDateTo – Nastavte na včerajší dátum
InvoiceStatus – Pre všetky transakcie použite „A“
PageSize – Nastavte na 100 pre efektívne načítanie údajov