API pro transakční data karet Shell B2B Mobility – Průvodce rychlým startem

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

Přehled

API transakčních údajů karet Shell je API založené na REST , které vývojářům umožňuje programově načítat a analyzovat transakční data z palivových karet Shell. API poskytuje přístup k transakcím s cenami, poplatkům, cenám založeným na objemu, pravidlům pro bonusy, výjimkám a souhrnům o používání karet.

Poznámka: Tato příručka se zabývá pouze koncovými body ověřovanými pomocí OAuth 2.0 (základní cesta: /transaction-data/v1). Starší koncové body s ověřováním Basic Auth (/fleetmanagement/v1/transaction) nejsou zahrnuty, protože jsou postupně vyřazovány z provozu.

Klíčové funkce

Načtení podrobností o transakcích s cenou, včetně transakcí s elektromobily
Přístup k podrobnostem o transakcích s palivem včetně prodejních položek a poplatků
Získejte souhrnné údaje o transakcích týkajících se paliva a NFR
Vyhledejte pravidla pro cenotvorbu na základě objemu a bonusová pravidla
Načíst položky poplatků a souhrnné údaje o poplatcích
Zobrazení výjimek u karet a transakcí
Analýza údajů o používání karet a výdajích
Podpora dotazů na transakce s více plátci

Důležité upozornění - OAuth 2.0

DŮLEŽITÉ: OAuth 2.0 je nyní standardní metodou ověřování

Nové integrace: Používejte OAuth 2.0 od samého začátku
Stávající integrace: Naplánujte si přechod na OAuth 2.0
Starší metody: Základní ověřování (Basic Auth) se postupně vyřazuje

Kontaktujte technickou podporu společnosti Shell a vyžádejte si své přihlašovací údaje pro OAuth 2.0 (client_id a client_secret).

Ověřování

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

Rozhraní API pro transakční data karet Shell využívá OAuth 2.0 Client Credentials pro bezpečné ověřování.

UPOZORNĚNÍ: Všichni zákazníci by měli plánovat přechod na ověřování pomocí OAuth 2.0. Jedná se o doporučenou a do budoucna perspektivní metodu ověřování pro rozhraní API transakčních dat karet Shell. Starší metody ověřování jsou postupně vyřazovány z provozu.

Průběh 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=your-client-id&client_secret=your-client-secret

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

Authorization: Bearer 
Content-Type: application/json

Správa tokenů

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

Přístupové tokeny mají omezenou platnost (obvykle 15 minut)
Zaveďte 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řetržitý provoz služby
Nikdy nesdílejte svůj client_secret ani jej nevkládat do kódu na straně klienta

Strategie zavádění OAuth 2.0

Proč přejít na OAuth 2.0?

Výhody z hlediska bezpečnosti:

Autentizační protokol odpovídající průmyslovému standardu
Časově omezené přístupové tokeny snižují bezpečnostní rizika
Při každém požadavku se nepřenášejí žádné přihlašovací údaje
Lepší podpora rotace a zrušení tokenů

Provozní výhody:

Vylepšená škálovatelnost a výkon
Lepší možnosti monitorování a auditu
Zjednodušená správa přihlašovacích údajů
Integrace připravená na budoucnost

Cesta migrace

Pokud v současné době používáte starší metody ověřování, postupujte podle tohoto migračního plánu:

Požádejte o přihlašovací údaje OAuth 2.0 od technické podpory Shell
Zaveďte správu tokenů OAuth ve vaší aplikaci
Důkladně otestujte v testovacím/sandboxovém prostředí
Během přechodu provozujte paralelní ověřování (OAuth + starší způsob)
Sledujte a ověřte integraci OAuth
Po ověření přejít výhradně na OAuth
Po úspěšné migraci vyřaďte staré ověřování

Prostředí

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

Prostředí	Základní URL	Účel
Produkční	https://api.shell.com	Živé produkční prostředí
Test (Sandbox)	https://api-test.shell.com/test	Testovací a vývojové prostředí

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

Rychlý start

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

Kontakt technickou podporu Shell
Požádejte o přihlašovací údaje OAuth 2.0 (client_id a client_secret)
Projděte 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": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

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

Příklad: Načtení transakcí s cenami

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

Příklad odpovědi:

{
  "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 uvolnění": 9,
      "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0,0051,
 "ColCoExchangeRate": 0,851858,
 "InvoiceCurrencySymbol": "GBP",
 "CorrectionFlag": true,
 "CRMNumber": 10,
 "CustomerCountry": "Spojené království",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
      "Sleva z čisté částky v měně zákazníka": 0,
 "Efektivní sleva v měně zákazníka": -0,22,
 "Efektivní jednotková sleva v měně zákazníka": -0,0051,
 „UnitPriceInInvoiceCurrency“: 1,1024,
 „Daň na faktuře“: 0,
 „Hrubá částka na faktuře“: 57,25,
 „Čistá částka na faktuře“: 47,71,
 „DPH z čisté částky v měně zákazníka“: 9,54,
 „Hrubá maloobchodní cena za jednotku v měně zákazníka“: 0,
      "Celková maloobchodní hodnota v měně zákazníka (brutto)": 57,52,
 "Celková maloobchodní hodnota v měně zákazníka (netto)": 47,93,
 "Popis typu transakce": 9,59,
 "Sleva z čisté částky v měně transakce": -0,22,
      "Skutečná sleva v měně transakce": -0,22,
 "Směnný kurz země odesílatele k zemi příjemce": 0,
 "Karty": [
 275549
 ],
 "Jednotková sleva v měně transakce": -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ý – střední oktanové číslo",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSitePopis": "Shell Broadway Ring",
 "Umístění": "Shell Broadway Ring",
 "Název provozovny": "Shell Broadway Ring",
 "Kód provozovny": 32,
 "Číslo přijímající provozovny": 15,
 "Kód měny faktury": "GBP",
 "Datum faktury": "20210802",
 "Číslo faktury": 3201016193,
 "Palivový produkt": true,
 "Platí DPH": "Y",
 "PayerName": "Colours Services Ltd",
 "PayerNumber": "GB12121212",
 "ParentCustomerNumber": "GB12121212",
 "Skupina plátce": "H312066",
 "Název skupiny plátce": "12162566 – SLUŽBA PALIVOVÝCH KARET",
 "Kontrolní číslice": 6,
 "NetInvoiceIndicator": "Y",
 "DelcoCode": 5,
 "NetworkCode": 3,
 "PurchasedInCountry": "Spojené království",
 "SiteCountry": "Spojené království",
 "VATCountry": "Spojené království",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
      "Popis ID vozového parku": "YG67OUM",
 "ID nadřazeného zákazníka": 6494,
 "Indikátor PIN": "Y, N",
 "ProductGroupName": "Poplatky",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
 "RebateRate": 0,0022,
 „ReceiptNumber“: 6803,
 „RefundFlag“: „Y“,
 „SiteGroupId“: 202,
 „SiteGroupName“: „CZ 9100 ECONOMY NETWORK“,
      "Latitude": 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 nebo C",
 "TransactionDate": "20210801",
      "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
      "UTCOffset": "Europe/London",
 "VATCategory": "Standardní sazba DPH ve Spojeném království",
 "VATRate": 0,2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
      "ColCoGrossAmount": 57,25,
 "ColCoNetAmount": 47,71,
      "ColCoVATAmount": 9,54,
 "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
 "OriginalVATAmount": 0,
 "EmbossText": "PARKLANE PROPERTIES LTD",
 "OriginalExchangeRate": 0,
 "OriginalTransactionItemInvoiceDate": "20220202",
 "FeeTypeId": 1,
      "Popis položky": true,
 "Popis pravidla poplatku": "Jednoduchý poplatek",
 "Frekvence": 1,
 "ID pravidla poplatku": 1,
 "Datum zadání do systému": "20210828",
      "SystemEntryTime": "20:21:08",
 "IsManual": "Y",
 "ID původní transakční položky": "Y",
 "Číslo faktury původní transakční položky": 6750802,
 "ID faktury původní transakční položky": 234,
      "Zkrácený název plátce": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "Původní hrubá částka": 57,25,
      "Původní čistá částka": 57,25,
 "Měrná jednotka": "L",
 "Typ silnice": "Státní silnice",
 "ISO kód země zákazníka": "DE",
 "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
 „EVChargePointConnectorType“: 5,
 „EVChargePointConnectorTypeDescription“: „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í příručka koncových bodů API

Transakce s cenou

Koncový bod	Metoda	Popis
/transaction-data/v1/priced	POST	Získat podrobnosti o transakcích s cenou včetně transakcí s elektromobily (OAuth 2.0)
/transaction-data/v1/pricedtransaction	POST	Získání podrobností o transakcích za palivo včetně prodejních položek a poplatků (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions	POST	Získat podrobnosti o transakcích s cenou pro více plátců (OAuth 2.0)

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

Načtení transakcí podle časového rozsahu
Filtrování podle stavu faktury (fakturováno, nefakturováno atd.)
Vyhledat podle čísla karty (PAN) nebo registračního čísla vozidla
Zobrazit transakce za nabíjení elektromobilů
Dotaz na transakce napříč více plátci

Souhrny transakcí

Koncový bod	Metoda	Popis
/transaction-data/v1/pricedtransactionssummary	POST	Načíst souhrnné údaje o transakcích s cenami pro palivo a NFR včetně prodejních položek a poplatků (OAuth 2.0)
/transaction-data/v1/cardusagesummary	POST	Načíst analýzu výdajů a souhrn využití karty (OAuth 2.0)

Vrací:

Souhrnná data o transakcích podle období
Celkové objemy a částky
Rozpis podle typu produktu a kategorie
Analýza výdajů na úrovni karet

Správa poplatků

Koncový bod	Metoda	Popis
/transaction-data/v1/feessummary	POST	Získání souhrnných údajů o položkách poplatků pro daného plátce (OAuth 2.0)

Informace o poplatcích:

Načtení položek poplatků uplatněných na transakce
Souhrn všech poplatků podle období
Rozpis poplatků podle typu a kategorie
Analýza poplatků na úrovni plátce

Pravidla založená na objemu

Koncový bod	Metoda	Popis
/transaction-data/v1/volumebasedpricing	POST	Načíst nastavení pravidel pro poplatky za prodlení u daného plátce (OAuth 2.0)
/transaction-data/v1/volumebasedbonus	POST	Načíst nastavení pravidel pro bonusy a asociované bonusy u daného plátce (OAuth 2.0)

Funkce založené na objemu:

Přístup pravidla cenového modelování na základě objemu
Načíst pravidla pro výpočet bonusů
Načíst konfigurace bonusů za přidružení

Výjimky

Koncový bod	Metoda	Popis
/transaction-data/v1/exceptions	POST	Načíst výjimky související s kartou nebo transakcí (OAuth 2.0)

Typ výjimky:

Selhání ověření transakce
Anomálie při používání karty
Výjimky při autorizaci

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

Tato část přiřazuje běžné obchodní scénáře k příslušným koncovým bodům API, aby vám pomohla rychle určit, která API použít pro vaše konkrétní potřeby.

Případ použití 1: Denní odsouhlasení transakcí

Scénář: Z účetních důvodů potřebujete denně provádět odsouhlasení všech transakcí z karet vaší vozového parku.

Doporučené API: /transaction-data/v1/priced

Proč toto API: Tento koncový bod poskytuje komplexní podrobnosti o transakcích, včetně transakcí za nabíjení elektromobilů, podporuje flexibilní filtrování podle data a zahrnuje jak fakturované, tak nefakturované transakce. Je ideální pro denní odsouhlasení a díky podpoře stránkování je vhodný i pro velké datové sady.

Klíčové parametry:

PostingDateFrom a PostingDateTo – Nastavte na včerejší datum
InvoiceStatus – Použijte „A“ pro všechny transakce
PageSize – Nastavte na 100 pro efektivní načítání dat

Případ použití 2: Ověření a kontrola faktury

Scénář: Obdrželi jste fakturu a potřebujete ověřit všechny podrobnosti transakce, včetně poplatků a příplatků.

Doporučené API: /transaction-data/v1/pricedtransaction

Proč toto API: Je speciálně navrženo k poskytování podrobných informací o transakcích s palivem, včetně prodejních položek a všech souvisejících poplatků. Je ideální pro ověření faktury, protože odpovídá struktuře faktury.

Klíčové parametry:

Číslo faktury - Konkrétní faktura k ověření
Datum faktury - Datum faktury z vašeho vyúčtování
IncludeFees – Nastavte na hodnotu „true“, chcete-li zobrazit všechny položky poplatků

Případ použití 3: Analýza spotřeby paliva a vytváření reportů

Scénář: Potřebujete analyzovat vzorce spotřeby paliva ve vašem vozovém parku za uplynulý měsíc, abyste mohli optimalizovat trasy a snížit náklady.

Doporučené API:

/transaction-data/v1/pricedtransactionssummary – Pro agregovaná data

Proč právě tato API: Souhrnné koncové body poskytují agregovaná data podle produktu, skupiny lokalit a časového období, což je ideální pro analýzu trendů bez nutnosti zpracovávat velké objemy transakcí.

Klíčové parametry:

PostingDateFrom a PostingDateTo – Nastaveno na posledních 30 dní
ProductCode – Filtrování podle konkrétních druhů paliv
ProductGroupName - Seskupit podle kategorií paliv

Případ použití 4: Správa více vozových parků

Scénář: Spravujete více podúčtů nebo plátců a potřebujete načíst údaje o transakcích ze všech z nich pro konsolidované reportování.

Doporučené API: /transaction-data/v1/multipayerspricedtransactions

Proč toto API: Je speciálně navrženo pro dotazování na transakce napříč více plátci v rámci jediného volání API, což výrazně snižuje počet požadavků a zlepšuje výkon v scénářích s víceflotilových scénářů.

Klíčové parametry:

Účty – Pole ID a čísel plátců (max. 10 plátců)
InvoiceStatus – „A“ pro všechny transakce
PostingDateFrom a PostingDateTo – vykazované období

Použití Případ 5: Sledování výjimek a detekce podvodů

Scénář: Chcete identifikovat neobvyklé vzorce transakcí, jako jsou transakce s vysokou hodnotou, nadměrné objemy paliva, nebo karty s neobvyklým používáním, abyste předešli podvodům či zneužití.

Doporučené API: /transaction-data/v1/exceptions

Proč právě toto API: Je speciálně navrženo pro identifikaci transakcí, které překračují definované prahové hodnoty, což je činí ideálním nástrojem pro monitorování výjimek a potenciálních podvodů.

Klíčové parametry:

Podmínka – Nastavení typu prahové hodnoty (ValueGreaterThan, VolumeGreaterThan atd.)
Hodnota – Definujte prahovou hodnotu
OutputType – „Transaction“ pro výjimky v transakcích
TransactionsFromDate a TransactionsToDate – Sledované období

Případ použití 6: Analýza poplatků a nákladů

Scénář: Potřebujete získat přehled o všech poplatcích a poplatků účtovaných na váš účet, abyste mohli identifikovat možnosti úspor nebo ověřit správnost vyúčtování.

Doporučené API: /transaction-data/v1/feessummary

Proč toto API: Poskytuje souhrnné informace o poplatcích podle typu poplatku, skupiny produktů a skupinu poplatků, což usnadňuje analýzu struktury poplatků a identifikaci oblastí s vysokými náklady.

Klíčové parametry:

InvoiceStatus – „I“ pouze pro fakturované poplatky
FeeTypeGroup – Filtrování podle „Poplatky za kartu“, „Poplatky z účtu“ atd.
PostingDateFrom a PostingDateTo – Období analýzy

Případ použití 7: Sledování výdajů jednotlivých karet

Scénář: Řidič si vyžádá historii transakcí za posledních 6 měsíců, nebo potřebujete analyzovat vzorce výdajů u konkrétní karty.

Doporučené API: /transaction-data/v1/cardusagesummary

Proč toto API: Poskytuje podrobnou analýzu výdajů za jednotlivé karty za posledních 7 měsíců, seskupenou podle místa a produktu, což je ideální pro reportování na úrovni karet.

Klíčové parametry:

CardId nebo PAN - Konkrétní karta k analýze
CardExpiry – Pro dodatečné ověření
AccountId – Volitelný filtr účtu

Případ použití 8: Kontrola způsobilosti pro cenové úrovně založené na objemu

Scénář: Chcete ověřit, zda váš účet splňuje podmínky pro cenové úrovně založené na objemu, a zjistit, jak se vaše aktuální spotřeba srovnává s definovanými prahovými hodnotami.

Doporučené API: /transaction-data/v1/volumebasedpricing

Proč toto API: Zobrazuje pravidla pro poplatky za prodlení, konfigurace cenových úrovní a aktuální objem spotřeby, což vám pomůže porozumět cenovým strukturám a naplánovat si dosažení lepších cenových úrovní.

Klíčové parametry:

PayerNumber – Váš účet plátce
IncludeHistory – Nastavte na „true“, chcete-li zobrazit historické výpočty
IncludeCurrentPeriodVolume – Nastavte na hodnotu „true“, chcete-li zobrazit

Případ použití 9: Sledování bonusů a slev

Scénář: Máte dohody o bonusech založených na objemu a chcete sledovat svůj pokrok směrem k prahovým hodnotám pro bonusy a zobrazit dříve získané bonusy.

Doporučené API: /transaction-data/v1/volumebasedbonus

Proč toto API: Poskytuje kompletní podrobnosti o pravidlech bonusů, spotřebě v aktuálním období a historických výpočtech bonusů, což vám umožňuje optimalizovat nákupy s cílem maximalizovat bonusy.

Klíčové parametry:

PayerNumber – Váš účet plátce
IncludeHistory – Nastavte na hodnotu „true“, chcete-li zobrazit minulé bonusové platby
IncludeCurrentPeriodVolume – Nastavte na hodnotu „true“, chcete-li sledovat průběh aktuálního období

Příklady použití

Příklad 1: Získání oceněných transakcí (včetně EV)

Žádost:

POST /transaction-data/v1/priced

{
  "PageSize": 1,
  "Page": 1,
  "Filters": {
    "ColCoCode": "5",
    "ColCoId": 5,
    "InvoiceStatus": "A",
    "PayerNumber": "DE26685263",
    "AccountId": 29484,
    "AccountNumber": "DE26667080",
    "CardPAN": "7002051006629890645",
    "FromDate": "2022-01-01 00:00:00",
    "ToDate": "2022-01-31 00:00:00",
    "IncludeFees": true
  }
}

Odpověď:

{
  "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,
 "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
 "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
      "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0,0051,
 "ColCoExchangeRate": 0,851858,
      "Symbol měny faktury": "GBP",
 "Příznak opravy": true,
 "Číslo CRM": 10,
 "Země zákazníka": "Spojené království",
 "Kód měny zákazníka": "GBP",
 "Symbol měny zákazníka": "£",
 "Sleva z čisté částky v měně zákazníka": 0,
 "Efektivní sleva v měně zákazníka": -0,22,
      "Efektivní jednotková sleva v měně zákazníka": -0,0051,
 "Jednotková cena v měně faktury": 1,1024,
      "Daň na faktuře": 0,
 "Hrubá částka na faktuře": 57,25,
 "Čistá částka na faktuře": 47,71,
 "DPH z čisté částky v měně zákazníka": 9,54,
      "Hrubá jednotková maloobchodní cena pro zákazníka": 0,
 "Celková hrubá maloobchodní hodnota pro zákazníka": 57,52,
 "Celková čistá maloobchodní hodnota pro zákazníka": 47,93,
 "Popis typu transakce": 9,59,
 "SlevaateonNetAmountInTransactionCurrency": -0,22,
 "EffectiveDiscountInTrxCurrency": -0,22,
      "Směnný kurz z národní měny do kolumbijské měny": 0,
 "Karty": [
 275549
 ],
 „Jednotková sleva v měně transakce“: -0,005,
 „Hrubá částka transakce“: 57,25,
 „Čistá částka transakce“: 47,71,
 „Daň z transakce“: 9,54,
 „VATonNetAmount": 9,54,
 "DelcoListPriceUnitNet": 0,
 "DelcoRetailPriceUnitGross": 1,32888,
 "UnitPriceInTransactionCurrency": 1,1074,
      "DelcoRetailPriceUnitNet": 1,1074,
 "DelcoRetailValueTotalGross": 57,52,
      "Celková maloobchodní hodnota Delco (netto)": 47,93,
 "Symbol měny transakce": "$",
 "Typ slevy": 1,
 „Stav sporu“: false,
 „Je to čerpací stanice Shell“: false,
 „ID vozového parku (vstup)“: „YG67OUM“,
 „Kód příchozího produktu“: 23,
 „Datum zaúčtování“: „20210802“,
      „PostingTime“: „14:15:22“,
 „ProductCode“: 30,
 „ProductName“: „Bezolovnatý – střední oktanové číslo“,
 „ProductGroupId“: 22,
 „IncomingCurrencyCode“: "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
 "SiteName": "Shell Broadway Ring",
 "SiteCode": 32,
 "IncomingSiteNumber": 15,
      "Kód měny faktury": "GBP",
 "Datum faktury": "20210802",
 "Číslo faktury": 3201016193,
 „Palivový produkt“: true,
 „Platí DPH“: „Y“,
 „Jméno plátce“: „Colours Services Ltd",
 "Číslo plátce": "GB12121212",
 "Číslo nadřazeného zákazníka": "GB12121212",
 "Skupina plátce": "H312066",
 "Název skupiny plátce": „12162566 – FUEL CARD SERVICE“,
 „Kontrolní číslice“: 6,
 „Indikátor čisté faktury“: „Y“,
 „Kód Delco“: 5,
 „Kód sítě“: 3,
      "PurchasedInCountry": "Spojené království",
 "SiteCountry": "Spojené království",
 "VATCountry": „Spojené království“,
 „DelcoName“: „Shell U.K. Oil Products Limited“,
 „Network“: „Shell“,
 „OdometerInput“: 0,
 „OriginalSalesItemId“: "Null",
 "Popis ID vozového parku": "YG67OUM",
 "ID nadřazeného zákazníka": 6494,
 "Indikátor PIN": „Y, N“,
 „ProductGroupName“: „Poplatky“,
 „PurchasedInCountryCode“: „GB“,
 „Quantity“: 43,28,
 „RebateRate“: 0,0022,
      "ReceiptNumber": 6803,
 "RefundFlag": "Y",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 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 nebo C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
      "TrnIdentifier": "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
 "VATCategory": "Standardní sazba DPH ve Spojeném království",
 "VATRate": 0,2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
 "ColCoGrossAmount": 57,25,
 "ColCoNetAmount": 47,71,
 „ColCoVATAmount“: 9,54,
 „OriginalCurrencySymbol“: „$“,
 „OriginalCurrencyCode“: „$“,
 „OriginalVATAmount“: 0,
      "EmbossText": "PARKLANE PROPERTIES LTD",
 "OriginalExchangeRate": 0,
 "OriginalTransactionItemInvoiceDate": "20220202",
      "FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "Simple Fee",
 "Frequency": 1,
 "FeeRuleId": 1,
      "SystemEntryDate": "20210828",
      "SystemEntryTime": "20:21:08",
 "IsManual": "Y",
 "OriginalTransactionItemId": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
      "ID faktury původní transakční položky": 234,
 "Zkrácený název plátce": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "Původní hrubá částka": 57,25,
      "OriginalNetAmount": 57,25,
 "UnitOfMeasure": "L",
 "RoadType": "Státní silnice",
 "CustomerCountryIsoCode": "DE",
 "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
 "EVChargePointConnectorType": 5,
 "EVChargePointConnectorTypeDescription": "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": 3,
  "PageSize": 30,
  "TotalPages": 5
}

Příklad 2: Získání podrobností o transakci s palivem

Žádost:

POST /transaction-data/v1/pricedtransaction

{
  "Filters": {
    "ColCoCode": 14,
    "InvoiceStatus": "A",
    "PayerId": 12345,
    "PayerNumber": "NL10042616"
  },
  "Page": 1,
  "PageSize": 50
}

Odpověď:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
 "Type": "SalesItem /FeeItem",
 "CardId": 0,
 "CardPAN": "7002051006629891000",
          "CardExpiry": "2026-06-16",
 "TransactionDate": "2026-06-16",
          "TransactionTime": "string",
 "UTCOffset": "string",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
          "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "$",
 "TransactionNetAmount": 0,
          "TransactionTax": 0,
 "TransactionGrossAmount": 0,
 "InvoiceNetAmount": 0,
 "InvoiceTax": 0,
 "InvoiceGrossAmount": 0,
          "PurchasedInCountry": "Germany",
 "AccountId": 29484,
 "AccountNumber": "GB99215176",
 „AccountName“: „MATTHEW ALGIE & COMPANY LIMITED“,
 „AccountShortName“: „string“,
 „Quantity“: 0,
 „FuelProduct“: true,
 „UnitPriceInTransactionCurrency“: 0,
          "Jednotková cena v měně faktury": 0,
          "UnitDiscountTransactionCurrency": 0,
 "UnitDiscountInvoiceCurrency": 0,
 "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "Datum faktury": "string",
 "Kód lokality": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Název lokality": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Země lokality": "Německo",
          "Location": {
 "Latitude": "37.4224764",
 "Longitude": "122.0842499"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
          "ReceiptNumber": "1234",
 "ProductCode": "10 - TMF poplatky",
 "ProductName": "Bezolovnatý – vysokooktanový",
 "ProductGroupId": 1,
          "ProductGroupName": "Nadřazená skupina produktů",
 "DelCoExchangeRate": 0,
 "ColCoExchangeRate": 0,
 "IsShellSite": true,
 "Network": "100013\tSTEINDORFER",
          "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "string",
 "IssuerCode": "7002",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Nizozemsko",
 "ReleaseCode": "8",
 "CardGroupId": "string",
          "CardSequenceNumber": "2",
 "CheckDigit": "string",
 "FleetIDDescription": "string",
 "VATRate": "0,20 pro 20 %",
 "VATCategory": "1 – s nulovou sazbou",
          "VATonNetAmount": 0,
 "VATCountry": "Nizozemsko",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Nákup s fyzickou kartou, jinak prázdné",
 "PINIndicator": "„PIN použit“",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "CustomerCurrencyCode": "GBP",
 "Symbol měny zákazníka": "£",
 "Skutečná jednotková sleva v měně zákazníka": 0,
 "Skutečná sleva v měně zákazníka": 0,
 "DPH z čisté částky v měně zákazníka": 0,
 "Typ slevy": "2-pence za jednotku",
 "TransactionStatus": "U",
          "SalesItemId": 18315958002,
 "PayerGroup": "string",
 "PayerGroupName": "12119008 – SHELL GROUP OF COMPANIES",
 "RefundFlag": "string",
 "OriginalSalesItemId": "string",
 "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
          "DelcoCode": "14",
 "PayerNumber": "NL10042616",
 "PayerName": "V.M. LE COMTE",
          "CardExpiryPeriod": "1901",
 "AuthorisationCode": "1011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
 "CRMNumber": "string",
 "DisputeStatus": "No Dispute",
 "RebateRate": 28,279,
          "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 0,
 "EuroVATAmount": 0,
          "ParentCustomerNumber": "řetězec",
 "ParentCustomerName": "řetězec",
 "ParentCustomerId": 0,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
          "IncomingCurrencyCode": "GBP",
 "IncomingProductCode": "30",
 "CreditDebitCode": "D",
 "CorrectionFlag": "Y",
 "Additional1": "string",
          "Additional2": "string",
 "Additional3": "string",
 "Additional4": "string",
 "RebateonNetAmountInCustomerCurrency": -0,735,
 "RebateonNetAmountInTransactionCurrency": "AVEE PTUAZONW CUBFAO COSFS",
 "TrnIdentifier": "řetězec",
 "CardType": "řetězec",
 "DelcoListPriceUnitNet": 30,5,
 "DelcoRetailPriceUnitNet": 1,921,
          "DelcoRetailPriceUnitGross": 0,
 "DelcoRetailValueTotalNet": 0,
 "DelcoRetailValueTotalGross": 0,
 "CustomerRetailPriceUnitGross": 0,
 "CustomerRetailValueTotalNet": 0,
          "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "string"
 }
 ]
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 15
}

Příklad 3: Získání souhrnu transakcí s cenami

Žádost:

POST /transaction-data/v1/pricedtransactionssummary

{
    "Filters": {
 "ColCoCode": 9,
 "PayerId": 12,
 "InvoiceStatus": "A",
 "FromDate": "2024-03-20",
 "ToDate": "2024-09-17",
 "PurchasedInCountryCode": "AT"
    }
}

Odpověď:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
      "ProductName": "Diesel AGO",
 "ProductGroupId": 1,
 "ProductGroupName": "Paliva",
 "TotalFuelQuantity": 1250,75,
 "TotalNetAmount": 5420,50,
      "CelkováHrubáČástka": 6504,60,
 "KódMěnyFaktury": "GBP",
 "InvoiceCurrencySymbol": "£",
 "CustomerRetailValueTotalNet": 5420,50,
 "CustomerRetailValueTotalGross": 6504,60
    }
  ]
}

Příklad 4: Získání souhrnu cen

Žádost:

 POST /transaction-data/v1/pricedsummary
 
 {
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "CardId": 275549,
    "FromDate": "20240225",
    "ToDate": "20240225",
    "FuelOnly": false
  }
}

Odpověď:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114,13,
 "CustomerRetailValueTotalNet": 95,11,
            "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
 "ProductCode": "21",
 "ProductGroupId": 3,
 "ProductGroupName": "Motorový benzín",
 "ProductId": 21,
            "ProductName": "Bezolovnatý – vysokooktanový",
 "SiteGroupId": 104,
            "Název skupiny čerpacích stanic": "Výchozí čerpací stanice Shell v Rakousku",
 "Celkové množství paliva": 17,0,
 "Celková hrubá částka": 114,13,
 "Celková čistá částka": 95,11
 }
    ]
}

Příklad 5: Načtení transakcí s cenami pro více plátců

Žádost:

POST /transaction-data/v1/multipayerspricedtransactions

{
  "ColCoCode": 86,
  "Accounts": [
    {
 "PayerId": 12345,
 "PayerNumber": "GB987654322"
    },
    {
 "PayerId": 12346,
 "PayerNumber": "GB000000124"
    }
  ],
  "InvoiceStatus": "A",
  "FromDate": "20220101",
  "ToDate": "20220131",
  "PageSize": 50,
  "Page": 1
}

Odpověď:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
        {
 "Type": "SalesItem"
 }
 ],
 "CardId": 275549,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
 "TransactionTime": "14:30:45",
 "UTCOffset": "+01:00:00",
      "FleetIdInput": "XYZ1234",
 "OdometerInput": 12345,
      "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
      "InvoiceCurrencySymbol": "£",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "£",
 "TransactionNetAmount": 47,71,
      "TransactionTax": 9,54,
 "TransactionGrossAmount": 57,25,
 "InvoiceNetAmount": 47,71,
 "InvoiceTax": 9,54,
 "InvoiceGrossAmount": 57,25,
 „PurchasedInCountry“: „Německo“,
 „AccountId“: 29484,
 „AccountNumber“: „GB99215176“,
 „AccountName“: „MATTHEW ALGIE & COMPANY LIMITED“,
      "Zkrácený název účtu": "MATTHEW",
 "Množství": 43,28,
 "Palivový produkt": true,
 "Jednotková cena v měně transakce": 1,1074,
 „Jednotková cena v měně transakce“: 1,1024,
 „Jednotková sleva v měně transakce": -0,005,
 "UnitDiscountInvoiceCurrency": -0,0051,
 "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
      "Datum faktury": "20250815 09:30:00",
 "Kód lokality": "050001",
 "Název lokality": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Země lokality": "Němany",
 "Location": {
 "Latitude": "53.83606",
 "Longitude": "-1.61854"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "6803",
 "ProductCode": "10",
 "ProductName": "Bezolovnatý – vysokooktanový",
 "ProductGroupId": 2,
 "ProductGroupName": "Všechna paliva",
 "DelCoExchangeRate": 0,851858,
 "ColCoExchangeRate": 0,851858,
 „IsShellSite“: true,
 „Network“: „SHELL“,
 „SiteGroupId“: 202,
      "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20250812 14:30:45",
      "IssuerCode": "7002",
 "PurchasedInCountryCode": "DE",
      "Kód země zákazníka": "NL",
 "Země zákazníka": "Nizozemsko",
 "Kód vydání": "8",
 "ID skupiny karet": "40000",
 "Sekvenční číslo karty": "617",
      "Kontrolní číslice": "6",
 "Popis ID vozového parku": "YG67OUM",
      "Sazba DPH": 0,2,
 "Kategorie DPH": "1-Standardní sazba",
 "DPH z čisté částky": 9,54,
 "Země DPH": "Nizozemsko",
 "EffectiveDiscountInTrxCurrency": -0,22,
 "TransactionType": "Nákup",
 "PINIndicator": "PIN použit",
      "VATApplicable": "Y",
 "NetInvoiceIndicator": "N",
 "CustomerCurrencyCode": "GBP",
      "Znak měny zákazníka": "£",
 "Efektivní jednotková sleva v měně zákazníka": -0,0051,
 "Efektivní sleva v měně zákazníka": -0,22,
      "VATonNetAmountInCustomerCurrency": 9,54,
 "DiscountType": "2 pence za jednotku",
 "TransactionStatus": "I“,
 „SalesItemId“: 18315958002,
 „PayerGroup“: "H312066",
 "PayerGroupName": "12119008 - SHELL GROUP OF COMPANIES",
 "RefundFlag": "N",
      "OriginalSalesItemId": null,
 "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "014",
 "PayerNumber": "GB987654322",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "2504",
      "AuthorisationCode": "011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
      "Číslo v CRM": null,
 "Stav sporu": "Žádný spor",
 "Sazba slevy": 28,279,
      "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
 "ParentCustomerNumber": "GB12121212",
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
      "ID nadřazeného zákazníka": 6494,
 "Číslo přijímacího místa": "100021",
 "Popis přijímacího místa": "HN3 INTI_02-82.02",
 "Kód přijímací měny": "GBP",
 "Kód příchozího produktu": "30",
 "Kód úvěru/debitu": "D",
 "Příznak opravy": "N",
 "Dodatečné údaje 1": "GBALLEGO0002452",
 "Dodatečné údaje 2": null,
 „Additional3“: null,
 „Additional4“: null,
 „RebateonNetAmountInCustomerCurrency“: -0,735,
 „Sleva z čisté částky v měně transakce": -0,735,
 "Identifikátor transakce": "H305908971030",
 "Typ karty": "GB STD FLT NAT SINGLE R9",
 "DelcoListPriceUnitNet": 30,5,
 "DelcoRetailPriceUnitNet": 1,1074,
 "DelcoRetailPriceUnitGross": 1,32888,
      "DelcoRetailValueTotalNet": 47,93,
 "DelcoRetailValueTotalGross": 57,52,
      "CustomerRetailPriceUnitGross": 1,32888,
 "CustomerRetailValueTotalNet": 47,93,
 "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "Fleet Card"
    }
  ],
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 15,
  "TotalRecords": 300
}

Příklad 6: Načtení pravidel cenového stanovení na základě objemu

Žádost:

POST /transaction-data/v1/volumebasedpricing

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "IncludeHistory": true,
  "IncludeCurrentPeriodVolume": true
}

Odpověď:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
          "PricingAccountShortName": "ABCD1234",
 "PricingAccountFullName": "ABCD1234",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
          "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Pay to Payer",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
          "Frequency": "3-Týdně – pondělí",
 "NextCalculationDate": "20231223",
 "PreviousCalculatedDate": "20231223",
          "Základ pravidla poplatku": "3-jednorázová částka",
 "Kód měny pravidla poplatku": "GBP",
 "Symbol měny pravidla poplatku": "£",
 "Platnost pravidla poplatku od": "20231223",
 "Platnost pravidla pro poplatky do": "20231223",
 "Umístění pravidla pro poplatky": [
 {
 "ID Delco": 866,
 "Země": "Spojené království",
 "Kód země": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
              "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
              "Název lokality": "VALERO ENERGY LTD"
 }
 ],
 "Produkty s pravidly poplatků": [
 {
              "ProductGroupID": 3,
 "ProductGroupName": "Motorový benzín",
 "ProductCode": "30 pro naftu AGO",
 "ProductId": "30 pro naftu AGO",
 "ProductName": "Nafta AGO"
 }
 ],
          "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
              "TierMaximum": 1234,
 "Value": 1234,12
 }
 ]
 }
 ],
 "CurrentPeriodConsumption": [
 {
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "PriceRuleID": 100005,
 "Popis cenového pravidla": "PL/GAGO/GMOT/UL0.055",
 "Celkový objem": 10000,78,
 "Datum vytvoření dalšího poplatku": "20231223"
 }
 ],
 "History": [
 {
 "FromDate": "20231223",
 "ToDate": "20231223",
          "FeesRuleID": 8081,
 "FeesRuleDescription": "PT/P067/D120/P4.0",
 "TotalVolume": 12356,66
 }
      ],
 „Warnings“: [
 {
 „Message“: „Systém je mimo provoz z důvodu aktualizace.",
 "Type": "Výpadek systému"
 }
 ]
    }
  ]
}

Příklad 7: Získání pravidel pro bonusy založené na objemu

Žádost:

POST /transaction-data/v1/volumebasedbonus

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "IncludeHistory": true,
  "IncludeCurrentPeriodVolume": true
}

Odpověď:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "MATTHEW",
 "PricingAccountFullName": "MATTHEW",
 "FeeRuleId": 1,
          "Popis pravidla poplatku": "NL/GAGO/D018/UP0.0120>1",
 "Datum účinnosti pravidla poplatku": "20231223",
 "Datum ukončení platnosti pravidla poplatku": "20231223",
          "BonusPaidTo": "1-Pay to Payer",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
          "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": „3-Týdně – pondělí“,
 „NextCalculationDate“: „20231223“,
 „PreviousCalculatedDate“: „20231223“,
 „FeeRuleBasis“: "3-jednorázová platba",
 "FeeRuleCurrencyCode": "GBP",
 "FeeRuleCurrencySymbol": "£",
 "FeeRuleAvailableFrom": "20231223",
 "FeeRuleAvailableTo": "20231223",
 "FeeRuleLocations": [
 {
 "DelcoId": 866,
 "Country": "Spojené království",
 "CountryCode": "UK",
 „FuelNetworkId“: 100007,
 „NetworkName“: „VALERO“,
 „SiteGroupId“: 100007,
 „SiteGroupName“: "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": "VALERO ENERGY LTD"
 }
 ],
 "FeeRuleProducts": [
            {
 „ProductGroupID“: 3,
              "ProductGroupName": "Motorový benzín",
 "ProductCode": "30 pro naftu AGO",
 "ProductId": "30 pro naftu AGO",
 "ProductName": "Nafta AGO"
 }
 ],
 "FeeRuleTiers": [
            {
 „TierMinimum“: 1234,
 „TierMaximum“: 1234,
 „Value“: 1234,12
 }
          ],
 „AssociatedAccounts“: [
 {
 „AssociatedAccountId": 12345,
 "AssociatedAccountNumber": "GB000000123",
 "AssociatedAccountShortName": "Zkrácený název účtu",
 "AssociatedAccountFullName": "Úplný název účtu"
 }
 ]
 }
 ],
      "Spotřeba v aktuálním období": [
 {
 "ID pravidla poplatků": 12345,
 "Popis pravidla poplatků": "NL/GAGO/D018/UP0.0120>1",
          "Month": 1,
 "Year": 2018,
          "TotalVolume": 10000,78
 }
 ],
 "HistoricalBonusPaid": [
 {
 "PayerId": 12345,
          "PayerNumber": "GB000000123",
 "PayerShortName": "Jorden",
 "PayerFullName": "MATTHEW",
 "AccountId": 123456,
 "AccountNumber": "GB000000123",
 "Zkrácený název účtu": "SALT",
 "Úplný název účtu": "ABCD1234",
 "ID fakturačního účtu": 12345,
 "Číslo fakturačního účtu": "GB000000123",
 "Zkrácený název fakturačního účtu": "DFE1234",
 "Plný název fakturačního účtu": "AZAD PVT LMT",
 "ID pravidla poplatku": 12345,
 „FeeRuleDescription“: „NL/GAGO/D018/UP0.0120>1“,
 „FromDate“: „20231223“,
 „ToDate“: „20231223“,
          "BonusPaidTo": "5-Vyplatit přidruženým zákazníkům",
 "FeeItemId": 12345,
 "FeeRuleBasis": "2-Procento z přirážky“,
 „FeeItemCurrencyCode“: „GBP“,
 „FeeItemCurrencySymbol“: „$“,
 „ProratedVolume“: 123,12,
 „TotalVolume": 123,12,
 "FeeProduct": "1562-Bonusová nafta Shell",
 "InvoiceGrossAmount": 123,12,
 "InvoiceNetAmount": 123,12,
 "InvoiceVATAmount": 123,12,
          "IsFeeCancelled": true,
 "FeeItemTierProratedVolume": 123,12,
 "FeeItemTierTotalVolume": 123,12,
 "TierMinimum": 123,
 "TierRate": 123,12
 }
 ]
    }
  ],
  "Warnings": [
    {
 "Message": "Systém je mimo provoz z důvodu aktualizace.",
 "Type": "Výpadek systému"
    }
  ]
}

Příklad 8: Získání přehledu poplatků

Žádost:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Poplatky za kartu"
}

Odpověď:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "FeeTypeGroup": "Poplatky za kartu",
 "FeeTypeId": 1,
 "FeeType": "Roční poplatek za kartu",
 "ProductId": 1234,
 "ProductCode": "FEE",
      "ProductName": "Poplatek za kartu",
 "TotalFeeAmount": 125,00,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

Příklad 9: Získání výjimek transakcí

Žádost:

POST /transaction-data/v1/exceptions

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "TransactionsFromDate": "20231223",
  "TransactionsToDate": "20240131",
  "Value": 100,
  "Condition": 5,
  "OutputType": "Transaction"
}

Odpověď:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
      "CardsExceptions": [
 {
 "AccountId": 29484,
 "CardId": 1234,
 „PAN“: „ABCD1234“,
 „DriverName“: „ANDREW GILBERRY“,
 „VRN“: „34235“,
 „PayerId“: 123455,
          "PayerNumber": "GB000000123",
 "AccountNumber": "GB99215176",
 "AccountShortName": "MATTHEW",
 "PayerShortName": "MATTHEW",
 "Day": 2,
 "Week": 2,
          "Month": 5,
 "Year": 2017,
 "TotalTransactions": 4,
 "TotalSalesItems": 4,
 "TotalQuantity": 261,
 „Celková částka“: 100,21,
 „Kód měny“: „GBP“,
 „Symbol měny“: „$“
        }
 ],
 „TransactionsExceptions“: [
 {
 „SalesItemId“: 18315958002,
 „CardId“: 1234,
 „ProductId“: 2,
          "TransactionGUID": "ABCD1234",
 "TransactionDate": "20231223",
 "CustomerInvoiceValueTotalGross": 123,12,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20311223 12:12:12",
 "TransactionTime": "12:12:12",
 "UTCOffset": "+12:12:12",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 1234,
 "DriverName": "SALT",
 "VehicleRegistration": "MV65YLH",
 "Kód měny faktury": "GBP",
          "Symbol měny faktury": "$",
 "Kód měny transakce": "GBP",
 "Symbol měny transakce": "£",
 "Čistá částka transakce": 123,12,
          "TransactionTax": 123,12,
 "TransactionGrossAmount": 123,12,
 "InvoiceNetAmount": 123,12,
          "InvoiceTax": 123,12,
 "InvoiceGrossAmount": 123,1,
 "PurchasedInCountry": „Francie“,
 „AccountId“: 1234,
 „AccountNumber“: „GB99215176“,
 „AccountName“: „MATTHEW ALGIE & COMPANY LIMITED“,
          "AccountShortName": "MATTHEW ALGIE & COMPANY LIMITED",
          "Množství": 123,12,
 "Palivový produkt": true,
 "Jednotková cena v měně transakce": 123,12,
 "Jednotková cena v měně faktury": 123,12,
 "Slevová jednotková cena v měně transakce": 123,12,
 "Slevová jednotková cena v měně faktury": 123,12,
 "Je fakturováno": true,
 "Číslo faktury": "S04500493",
 "Datum fakturyDate": "20231223",
 "SiteCode": "50001",
 "SiteName": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "Německo",
 "Location": {
 "Lat": "37.4224764",
 "Lng": "122.0842499"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
          "ReceiptNumber": "1234",
 "ProductCode": "TMF Charges",
 "ProductName": "Bezolovnatý – vysokooktanový“,
 „ProductGroupId“: 1234,
 „ProductGroupName“: „Nadřazená skupina produktů“,
 „DelCoExchangeRate“: 123,12,
 „ColCoExchangeRate“: 123,12,
 „IsShellSite“: true,
 „Network“: „Shell PH“,
 „SiteGroupId“: 202,
 „SiteGroupName“: „CZ 9100 ECONOMY NETWORK“,
          "PostingDate": "20231223 12:12:12",
 "IssuerCode": "7077 = CRT",
          "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Nizozemsko",
 "ReleaseCode": "8 pro 702188",
 "CardGroupId": "200",
          "CardSequenceNumber": "2",
 "CheckDigit": "GHE1234",
 "FleetIDDescription": "Příklad popisu",
 "VATRate": 0,2,
 "VATCategory": "3 – osvobozeno od DPH",
          "VATonNetAmount": 12,21,
 "VATCountry": "Nizozemsko",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Nákup při fyzickém předložení karty, jinak prázdné",
          "PINIndicator": "Y",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
          "Kód měny zákazníka": "GBP",
 "Symbol měny zákazníka": "£",
 "Efektivní jednotková sleva v měně zákazníka": 123,12,
          "EffectiveDiscountInCustomerCurrency": 123,12,
 "VATonNetAmountInCustomerCurrency": 123,12,
 "DiscountType": "3-Percentage",
 "TransactionStatus": "U",
 "Skupina plátců": "12119008",
 "Příznak vrácení": "N",
 "ID původní prodejní položky": "1231",
          "NázevDelco": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "KódDelco": "NL10042616",
 "Jménoplátce": "V.M. LE COMTE",
 "DobaPlatnostiKarty": "1901",
 "AuthorisationCode": "11256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
          "AllowClearing": "Y",
 "CRMNumber": "ABCD1234",
 "DisputeStatus": "6\tZpětné zúčtování na web",
 "RebateRate": 28,279,
          "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 37,93,
 "EuroRebateAmount": 0,
 "EuroVATAmount": 7,96,
          "ParentCustomerNumber": "DRG1234"
 }
 ]
    }
  ]
}

Příklad 10: Získání souhrnu použití karty

Žádost:

POST /transaction-data/v1/cardusagesummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "AccountId": 1234,
  "AccountNumber": "GB000000123",
  "CardId": 1234,
  "PAN": "7882861007636000020",
  "CardExpiry": "20311223"
}

Odpověď:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "UsageSummary": [
 {
 "Date": "20170930",
 "ProductId": 1,
 "ProductCode": "2",
 "ProductName": "Diesel AGO",
 "IsFuelProduct": true,
 "SiteGroupId": 1234,
 "SiteGroupName": "UK 9500 MOTORWAY NETWORK",
 "TotalVolume": 123,12,
 "TotalGross": 123,12,
 "TotalNet": 123,12,
 "CurrencyCode": „GBP“,
 „CurrencySymbol“: „£“,
 „ProductGroupId“: 1234,
 „ProductGroupName“: „Motorový benzín"
 }
 ]
    }
  ]
}

Zpracování chyb

Běžné kódy chyb

Stav HTTP	Kód chyby	Popis	Řešení
200	N/A	Stav: ÚSPĚCH	N/A
200	E0001	Chyba ověření	Zkontrolujte parametry požadavku
401	E0003	Neoprávněný přístup	Ověřte platnost tokenu OAuth
403	E0003	Přístup zakázán	Zkontrolujte oprávnění uživatele
404	E0005	Zdroj nebyl nalezen	Ověřte, zda existuje URL koncového bodu a zdroj
500	E0002	Neznámá chyba / Interní chyba serveru	Kontaktujte podporu

Osvědčené postupy

1. Přechod na ověřování OAuth 2.0

DŮLEŽITÉ: Všichni zákazníci by měli přejít na ověřování OAuth 2.0. Zaveďte správnou správu tokenů:

Ukládejte přístupové tokeny do mezipaměti a znovu je používejte až do vypršení platnosti
Obnovujte tokeny před vypršením jejich platnosti (doporučeno 60 sekund předem)
Ukládejte přihlašovací údaje klienta bezpečně (používejte proměnné prostředí nebo správce tajných klíčů)
Nikdy nezaznamenávejte ani nezveřejňujte přístupové tokeny v kódu na straně klienta

2. Používejte ID požadavků

Vždy uvádějte jedinečné ID požadavku (ve formátu GUID) pro sledovatelnost od začátku do konce

3. Implementujte stránkování

U rozsáhlých datových sad transakcí používejte stránkování, abyste předešli vypršení časového limitu:

Nastavte vhodnou velikost stránky (PageSize) (doporučeno: 50–100 záznamů)
Zpracovávejte stránky postupně nebo paralelně
Zpracovávejte parametry TotalPages a TotalRecords v odpovědích

4. Rozumně využívejte filtry podle data

Při dotazování na transakční data:

Omezte časová rozmezí, abyste se vyhnuli rozsáhlým výsledným sadám
Filtry FromDate a ToDate používejte důsledně
Zvažte dotazování podle měsíce nebo týdne pro lepší výkon

5. Testujte v prostředí Sandbox

Vždy otestujte integraci v testovacím/Sandboxovém prostředí před přesunem do produkčního prostředí

6. Ukládejte referenční data do mezipaměti

Ukládejte do mezipaměti pravidla pro cenotvorbu podle objemu a bonusová pravidla, abyste minimalizovali počet volání API:

Tato pravidla se mění jen zřídka
Meziúložiště pravidelně aktualizujte (např. denně)
Parametr IncludeHistory používejte pouze v případě potřeby

SDK a ukázky kódu

Shell poskytuje oficiální SDK a komplexní ukázky kódu, které urychlí vaši integraci s API transakčních dat

Dostupné jazyky SDK

Python – Plnohodnotné SDK s podporou OAuth 2.0
TypeScript – Typově bezpečné SDK s úplnými definicemi typů
Java – SDK na podnikové úrovni
C#/.NET – Kompletní integrace s .NET
PHP – Snadno použitelná knihovna PHP
Ruby – Ruby gem pro hladkou integraci

Zobrazit oficiální SDK a dokumentaci

Podpora a zdroje

Technická podpora

Podpora: Technická podpora Shell
Migrace na OAuth 2.0: Podpora migrace na OAuth 2.0

Dokumentace

Získání pomoci

Při kontaktování podpory uveďte:

Vaše client_id (nikdy nesdílejte své client_secret ani přístupové tokeny)
RequestId z odpovědi API
Časové razítko požadavku
Prostředí (produkční/testovací)

Poslední aktualizace: 1. července 2026
Verze dokumentu: 1.0
Verze API: 2.3.5

Vyberte jazyk

API pro transakční data karet Shell B2B Mobility – Průvodce rychlým startem

Přehled

Klíčové funkce

Důležité upozornění - OAuth 2.0

Ověřování

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

Průběh OAuth 2.0

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

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

Správa tokenů

Strategie zavádění OAuth 2.0

Proč přejít na OAuth 2.0?

Výhody z hlediska bezpečnosti:

Provozní výhody:

Cesta migrace

Prostředí

Rychlý start

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

2. Získejte přístupový token

Příklad příkazu cURL:

Odpověď:

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

Příklad s cURL:

Příklad odpovědi:

Referenční příručka koncových bodů API

Transakce s cenou

Souhrny transakcí

Správa poplatků

Pravidla založená na objemu

Výjimky

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

Případ použití 1: Denní odsouhlasení transakcí

Případ použití 2: Ověření a kontrola faktury

Případ použití 3: Analýza spotřeby paliva a vytváření reportů

Případ použití 4: Správa více vozových parků

Použití Případ 5: Sledování výjimek a detekce podvodů

Případ použití 6: Analýza poplatků a nákladů

Případ použití 7: Sledování výdajů jednotlivých karet

Případ použití 8: Kontrola způsobilosti pro cenové úrovně založené na objemu

Případ použití 9: Sledování bonusů a slev

Příklady použití

Příklad 1: Získání oceněných transakcí (včetně EV)

Žádost:

Odpověď:

Příklad 2: Získání podrobností o transakci s palivem

Žádost:

Odpověď:

Příklad 3: Získání souhrnu transakcí s cenami

Žádost:

Odpověď:

Příklad 4: Získání souhrnu cen

Žádost:

Odpověď:

Příklad 5: Načtení transakcí s cenami pro více plátců

Žádost:

Odpověď:

Příklad 6: Načtení pravidel cenového stanovení na základě objemu

Žádost:

Odpověď:

Příklad 7: Získání pravidel pro bonusy založené na objemu

Žádost:

Odpověď:

Příklad 8: Získání přehledu poplatků

Žádost:

Odpověď:

Příklad 9: Získání výjimek transakcí

Žádost:

Odpověď:

Příklad 10: Získání souhrnu použití karty

Žádost:

Odpověď:

Zpracování chyb

Běžné kódy chyb

Osvědčené postupy

1. Přechod na ověřování OAuth 2.0

2. Používejte ID požadavků

3. Implementujte stránkování

4. Rozumně využívejte filtry podle data

5. Testujte v prostředí Sandbox