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

Različica API-ja: 2.3.5 | Preverjanje pristnosti: OAuth 2.0 | Stanje: Produkcijska različica

Pregled

API za podatke o transakcijah s karticami Shell je API na podlagi REST, ki razvijalcem omogoča programsko pridobivanje in analizo podatkov o transakcijah s karticami Shell za gorivo. API omogoča dostop do transakcij s cenami, provizij, cen na podlagi količine, pravil za bonuse, izjem in povzetkov uporabe kartic.

Opomba: Ta vodnik zajema le končne točke, avtentificirane prek OAuth 2.0 (osnovna pot: /transaction-data/v1). Stare končne točke z avtentifikacijo Basic Auth (/fleetmanagement/v1/transaction) niso vključene, saj se postopno umikajo iz uporabe.

Ključne funkcije

Pridobivanje podrobnosti o transakcijah s cenami, vključno s transakcijami za električna vozila
Dostop do podrobnosti o transakcijah z gorivom, vključno s prodajnimi artikli in pristojbinami
Pridobite podatke o povzetku transakcij za transakcije z gorivom in NFR
Poizvedujte o
Pridobite postavke provizij in podatke o povzetku provizij
Dostop do izjem pri karticah in transakcijah
Analiza podatkov o uporabi kartice in izdatkih
Podpora za poizvedbe o transakcijah z več plačniki

Pomembno obvestilo – OAuth 2.0

POMEMBNO: OAuth 2.0 je zdaj standardna metoda avtentifikacije

Nove integracije: Uporabljajte OAuth 2.0 že od samega začetka
Obstoječe integracije: Načrtujte prehod na OAuth 2.0
Starejše metode: Osnovno avtentificiranje se postopno opušča

Obrnite se na tehnično podporo Shell, da pridobite svoje poverilnice OAuth 2.0 (client_id in client_secret).

Preverjanje pristnosti

OAuth 2.0 (standardna metoda preverjanja pristnosti)

API za podatke o transakcijah s kartico Shell uporablja postopek »OAuth 2.0 Client Credentials« za varno avtentifikacijo.

OPOZORILO: Vsi uporabniki naj se pripravijo na prehod na avtentifikacijo OAuth 2.0. To je priporočena in prihodnosti odporna metoda avtentifikacije za API za podatke o transakcijah s karticami Shell. Stare metode avtentifikacije se postopno ukinjajo.

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

Korak 2: Uporaba dostopnega žetona v zahtevkih API

Authorization: Bearer 
Content-Type: application/json

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 vključujte v kodo na strani odjemalca

Strategija uvedbe OAuth 2.0

Zakaj preiti na OAuth 2.0?

Varnostne prednosti:

Protokol avtentifikacije po industrijskih standardih
Časovno omejeni dostopni žetoni zmanjšujejo varnostna tveganja
Pri vsakem zahtevku se ne prenašajo nobena pooblastila
Boljša podpora za menjavo in preklic žetonov

Operativne prednosti:

Izboljšana skalabilnost in zmogljivost
Boljše zmogljivosti spremljanja in revizije
Poenostavljeno upravljanje
Integracija, pripravljena na prihodnost

Pot migracije

Če trenutno uporabljate zastarele metode avtentifikacije, sledite tej poti migracije:

Zahtevajte poverilnice OAuth 2.0 pri tehnični podpori Shell
V vaši aplikaciji implementirajte upravljanje OAuth žetonov
Temeljito preizkusite v okolju Test/Sandbox
Med prehodom izvajajte vzporedno avtentifikacijo (OAuth + stari sistem)
Spremljajte in preverite integracijo OAuth
Prehod na izključno OAuth po potrditvi
Ukinitev stare avtentifikacije po uspešni migraciji

Okolja

API je na voljo v dveh okoljih:

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

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

Hiter začetek

1. Pridobite svoje OAuth-overitvene podatke

Obrnite se na tehnično podporo Shell
Zahtevajte poverilnice OAuth 2.0 (client_id in client_secret)
Preberite 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-stranke&client_secret=vaša-skrivnost-stranke"

Odgovor:

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

3. Pošljite svojo prvo zahtevo API

Primer: Pridobite transakcije s cenami

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

Primer odgovora:

{
  "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,
 "InvoiceCurrencySymbol": "GBP",
 "CorrectionFlag": true,
 "CRMNumber": 10,
 „CustomerCountry“: „Združeno kraljestvo“,
 „CustomerCurrencyCode“: „GBP“,
 „CustomerCurrencySymbol“: „£“,
 „RebateonNetAmountInCustomerCurrency“: 0,
 "EffectiveDiscountInCustomerCurrency": -0,22,
 "EffectiveUnitDiscountInCustomerCurrency": -0,0051,
 "UnitPriceInInvoiceCurrency": 1,1024,
      "Davek na računu": 0,
 "Bruto znesek računa": 57,25,
 "Neto znesek računa": 47,71,
      "DDV na neto znesek v valuti stranke": 9,54,
 "Bruto maloprodajna cena na enoto za stranko": 0,
 "Skupna bruto maloprodajna vrednost za stranko": 57,52,
 "Skupna neto maloprodajna vrednost za stranko": 47,93,
      "Opis vrste transakcije": 9,59,
      "Rabatt na neto znesek v valuti transakcije": -0,22,
 "Dejanski popust v valuti transakcije": -0,22,
 "Menjalni tečaj med valuto izdajatelja in valuto prejemnika": 0,
 "Kartice": [
        275549
      ],
 "Popust na enoto v valuti transakcije": -0,005,
 "Bruto znesek transakcije": 57,25,
 "Neto znesek transakcije": 47,71,
 "Davek na transakcijo": 9,54,
 "DDV na neto znesek": 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",
      "Čas objave": "14:15:22",
 "Koda izdelka": 30,
      "ProductName": "Brezolovno – srednji oktanski števil",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Lokacija": "Shell Broadway Ring",
 "Ime lokacije": "Shell Broadway Ring",
 "Koda lokacije": 32,
 "Številka lokacije": 15,
      "Koda valute računa": "GBP",
 "Datum računa": "20210802",
 "Številka računa": 3201016193,
 "Gorivo": true,
 "Velja DDV": "Y",
 "PayerName": "Colours Services Ltd",
 "PayerNumber": "GB12121212",
 "ParentCustomerNumber": "GB12121212",
      "Skupina plačnika": "H312066",
 "Ime skupine plačnika": "12162566 - STORITEV GORIVNE KARTICE",
 "Kontrolna številka": 6,
 "Kazalnik neto zneska računa": "Y",
      "DelcoCode": 5,
 "NetworkCode": 3,
 "PurchasedInCountry": "Združeno kraljestvo",
 "SiteCountry": "Združeno kraljestvo",
      "VATCountry": "Združeno kraljestvo",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
      "Opis ID voznega parka": "YG67OUM",
 "ID nadrejenega stranke": 6494,
 "Kazalnik PIN": "Y, N",
 "Ime skupine izdelkov": "Pristojbine",
 "Koda države nakupa": "GB",
      "Količina": 43,28,
 "Stopnja popusta": 0,0022,
 "Številka računa": 6803,
 "Oznaka vračila": "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 ali C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Nakup",
 "UTCOffset": "Europe/London",
 "VATCategory": "Standardna stopnja DDV v Združenem kraljestvu",
 "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",
      "Pogostost": 1,
 "ID pravila provizije": 1,
 "Datum vnosa v sistem": "20210828",
      "SystemEntryTime": "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": "National Road",
 "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",
      "Številka podjetja, ki zbira podatke": 0,
 "ID transakcije": 0,
 "Samo gorivo": true,
      "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 5
}

Referenca končnih točk API-ja

Transakcije s ceno

Končna točka	Metoda	Opis
/transaction-data/v1/priced	POST	Pridobivanje podrobnosti o transakcijah z določeno ceno, vključno s transakcijami za električna vozila (OAuth 2.0)
/transaction-data/v1/pricedtransaction	POST	Pridobivanje podrobnosti o transakcijah za gorivo s prodajnimi postavkami in pristojbinami (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions	POST	Pridobite podrobnosti o transakcijah s cenami za več plačnikov (OAuth 2.0)

Pogosti primeri uporabe:

Pridobivanje transakcij po časovnem obdobju
Filtriranje po statusu računa (zaračunano, neizstavljeno, itd.)
Iskanje po številki kartice (PAN) ali registrski številki vozila
Pridobite transakcije polnjenja električnih vozil
Povpraševanje po transakcijah več plačnikov

Povzetki transakcij

Končna točka	Metoda	Opis
/transaction-data/v1/pricedtransactionssummary	POST	Pridobivanje podatkov o povzetku transakcij z določeno ceno za gorivo in NFR s prodajnimi artikli in pristojbinami (OAuth 2.0)
/transaction-data/v1/cardusagesummary	POST	Pridobivanje analize izdatkov in povzetka uporabe za kartico (OAuth 2.0)

Vrne:

Zbirnipodatke o transakcijah po obdobju
Skupni obsegi in zneski
Razčlenitev po vrsti in kategoriji izdelka
Analiza izdatkov na ravni kartice

Upravljanje

Končna točka	Metoda	Opis
/transaction-data/v1/feessummary	POST	Pridobivanje povzetka podatkov o postavkah provizij za danega plačnika (OAuth 2.0)

Informacije o provizijah:

Pridobivanje postavk provizij, uporabljenih pri transakcijah
Povzetek vseh provizij po obdobju
Razčlenitev provizij po vrsti in kategoriji
Analiza pristojbin na ravni plačnika

Pravila na podlagi obsega

Končna točka	Metoda	Opis
/transaction-data/v1/volumebasedpricing	POST	Pridobitev nastavitev pravil za provizije za zamude pri plačilu za danega plačnika (OAuth 2.0)
/transaction-data/v1/volumebasedbonus	POST	Pridobitev nastavitev pravil za bonuse in povezane bonuse za danega plačnika (OAuth 2.0)

Funkcije, ki temeljijo na obsegu:

Dostop do pravil za določanje cen na podlagi obsega
Pridobite pravila za izračun bonusov
Pridobite konfiguracije bonusov za povezave

Izjeme

Končna točka	Metoda	Opis
/transaction-data/v1/exceptions	POST	Pridobivanje izjem, povezanih s kartico ali transakcijo (OAuth 2.0)

Vrste izjem:

Napake pri preverjanju transakcij
Nenormalnosti pri uporabi kartice
Izjeme pri avtorizaciji

Pogosti primeri uporabe

V tem poglavju so pogosti poslovni scenariji povezani z ustreznimi končnimi točkami API-ja, da boste lahko hitro ugotovili, katere API-je uporabiti za svoje specifične potrebe.

Primer uporabe 1: Dnevno usklajevanje transakcij

Scenarij: Potrebujete vsak dan uskladiti vse transakcije s svojih voznih kartic za namene računovodstva.

Priporočeni API: /transaction-data/v1/priced

Zakaj ta API: Ta končna točka zagotavlja izčrpne podrobnosti o transakcijah, vključno s transakcijami polnjenja električnih vozil, podpira prilagodljivo filtriranje po datumu ter vključuje tako zaračunane kot nezaračunane transakcije. Idealna je za dnevno usklajevanje, saj omogoča paginacijo za obsežne nize podatkov.

Ključni parametri:

PostingDateFrom in PostingDateTo – nastavite na včerajšnji datum
InvoiceStatus – za vse transakcije uporabite »A«
PageSize – nastavite vrednost 100 za učinkovito pridobivanje podatkov

Primer uporabe 2: Preverjanje in potrjevanje računov

Scenarij: Prejeli ste račun in morate preveriti vse podrobnosti transakcije, vključno s pristojbinami in stroški.

Priporočeni API: /transaction-data/v1/pricedtransaction

Zakaj ta API: Posebej zasnovan za zagotavljanje podrobnih informacij o transakcijah z gorivom, vključno s prodajnimi postavkami in vsemi povezanimi pristojbinami. Idealno za preverjanje računov, saj ustreza strukturi računa.

Ključni parametri:

InvoiceNumber – Številka računa, ki ga želite preveriti
Datum računa – Datum računa iz vašega obračuna
IncludeFees – Nastavite na »true«, da se prikažejo vse postavke pristojbin

Primer uporabe 3: Analiza porabe goriva in poročanje

Scenarij: Analizirati morate vzorce porabe goriva v vašem voznem parku za pretekli mesec, da bi optimizirali poti in zmanjšali stroške.

Priporočeni API-ji:

/transaction-data/v1/pricedtransactionssummary – Za agregirane podatke

Zakaj ti API-ji: Končne točke za povzetke zagotavljajo agregirane podatke po izdelek, skupino spletnih mest in časovno obdobje, kar jih naredi idealne za analizo trendov brez obdelave velikih količin transakcij.

Ključni parametri:

PostingDateFrom in PostingDateTo – Nastavljeno na zadnjih 30 dni
ProductCode – filtriranje po določenih vrstah goriva
ProductGroupName - Razvrsti po kategorijah goriva

Primer uporabe 4: Upravljanje več voznih parkov

Scenarij: Upravljate več podračunov ali plačnikov in morate pridobiti podatke o transakcijah za vse te račune za konsolidirano poročanje.

Priporočeni API: /transaction-data/v1/multipayerspricedtransactions

Zakaj ta API: Posebej zasnovan za poizvedovanje transakcij pri več plačnikih z enim samim klicem API-ja, kar znatno zmanjša število zahtevkov in izboljša zmogljivost v scenarijih z več vozniškimi parki.

Ključni parametri:

Računi – Niz ID-jev in številk plačnikov (največ 10 plačnikov)
Stanje računa – »A« za vse transakcije
Datum knjiženja od in PostingDateTo – Obdobje poročanja

Primer uporabe 5: Spremljanje izjem in odkrivanje goljufij

Scenarij: Želite prepoznati neobičajne vzorce transakcij, kot so transakcije z visoko vrednostjo, prekomerne količine goriva ali kartice z nenormalno uporabo, da bi preprečili goljufije ali zlorabe.

Priporočeni API: /transaction-data/v1/exceptions

Zakaj ta API: Narejen je posebej za prepoznavanje transakcij, ki presegajo določene mejne vrednosti, zato je idealen za spremljanje izjem in morebitnih goljufij.

Ključni parametri:

Pogoj – Nastavite vrsto praga (ValueGreaterThan, VolumeGreaterThan itd.)
Vrednost – Določite mejno vrednost
Vrsta izhoda – »Transakcija« za izjeme pri transakcijah
TransactionsFromDate in TransactionsToDate – Obdobje spremljanja

Primer uporabe 6: Analiza provizij in stroškov

Scenarij: Morate razumeti vse provizije in stroške, ki se zaračunavajo na vaš račun, da bi lahko identificirali možnosti za zmanjšanje stroškov ali preverili pravilnost zaračunavanja.

Priporočeni API: /transaction-data/v1/feessummary

Zakaj ta API: Zagotavlja agregirane podatke o provizijah po vrsti provizije, skupini izdelkov in skupini provizij, kar olajša analizo struktur provizij in prepoznavanje področij z visokimi stroški.

Ključni parametri:

InvoiceStatus – »I« za provizije, ki so bile zaračunane
FeeTypeGroup – filtriranje po »stroških kartic«, »Stroški na računu« itd.
PostingDateFrom in PostingDateTo – Obdobje analize

Primer uporabe 7: Sledenje izdatkom posamezne kartice

Scenarij: Voznik zahteva zgodovino transakcij za zadnjih 6 mesecev ali pa morate analizirati vzorce porabe za določeno kartico.

Priporočeni API: /transaction-data/v1/cardusagesummary

Zakaj ta API: Zagotavlja podrobno analizo izdatkov za posamezne kartice v zadnjih 7 mesecih, razvrščeno po lokacijah in izdelkih, kar je idealno za poročanje na ravni kartice.

Ključni parametri:

CardId ali PAN – konkretna kartica, ki jo želite analizirati
CardExpiry – Za dodatno preverjanje
AccountId – Izbirni filter računa

Primer uporabe 8: Preverjanje upravičenosti do cenovnih stopenj na podlagi obsega

Scenarij: Želite preveriti, ali je vaš račun upravičen do cenovnih stopenj na podlagi obsega, ter razumeti svoje trenutne ravni porabe v primerjavi z določenimi pragovi.

Priporočeni API: /transaction-data/v1/volumebasedpricing

Zakaj ta API: Prikaže pravila za zamudne obresti, konfiguracije stopenj in trenutno porabo po obsegu, kar vam pomaga razumeti cenovne strukture in načrtovati doseganje boljših stopenj.

Ključni parametri:

PayerNumber – Vaš račun plačnika
IncludeHistory – Nastavite na »true«, da si ogledate pretekle izračune
IncludeCurrentPeriodVolume – Nastavite na »true«, če želitepo posameznih mesecih

Primer uporabe 9: Sledenje bonusom in popustom

Scenarij: Imate sporazume o bonusih na podlagi obsega in želite spremljati svoj napredek pri doseganju pragov za bonuse ter si ogledati prej pridobljene bonuse.

Priporočeni API: /transaction-data/v1/volumebasedbonus

Zakaj ta API: Zagotavlja popolne podrobnosti o pravilih za bonuse, porabi v tekočem obdobju in zgodovinskih izračunih bonusov, kar vam omogoča optimizacijo nakupov za doseganje največjih možnih bonusov.

Ključni parametri:

PayerNumber – Vaš plačniški račun
IncludeHistory – Nastavite na »true«, da si ogledate pretekla izplačila bonusov
IncludeCurrentPeriodVolume – Nastavite na »true«, da spremljate napredek v tekočem obdobju

Primeri uporabe

Primer 1: Pridobivanje transakcij s ceno (vključno z EV)

Zahteva:

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

Odgovor:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "USPEŠNO",
  "Podatki": [
    {
 "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,
 "InvoiceCurrencySymbol": "GBP",
 "CorrectionFlag": true,
 "CRMNumber": 10,
 "CustomerCountry": "Združeno kraljestvo",
 "CustomerCurrencyCode": "GBP",
      "Simbol valute stranke": "£",
 "Popust na neto znesek v valuti stranke": 0,
 "Dejanski popust v valuti stranke": -0,22,
 "Dejanski popust na enoto v valuti stranke": -0,0051,
 "Cena na enoto v valuti računa": 1,1024,
 "Davek na računu": 0,
 "Bruto znesek računa": 57,25,
 "Neto znesek računa": 47,71,
      "DDV na neto znesek v valuti stranke": 9,54,
 "Bruto maloprodajna cena na enoto za stranko": 0,
 "Skupna bruto maloprodajna vrednost za stranko": 57,52,
 "Skupna maloprodajna vrednost v valuti stranke (neto)": 47,93,
 "Opis vrste transakcije": 9,59,
 "Popust na neto znesek v valuti transakcije": -0,22,
      "EffectiveDiscountInTrxCurrency": -0,22,
      "Menjalni tečaj med DelCo in ColCo": 0,
 "Kartice": [
 275549
 ],
 "Popust na enoto v valuti transakcije": -0,005,
 "Bruto znesek transakcije": 57,25,
 "neto znesek transakcije": 47,71,
 "davek na transakcijo": 9,54,
 "DDV na neto znesek": 9,54,
 "neto cena na enoto po ceniku Delco": 0,
      "DelcoRetailPriceUnitGross": 1,32888,
 "UnitPriceInTransactionCurrency": 1,1074,
 "DelcoRetailPriceUnitNet": 1,1074,
      "Skupna maloprodajna vrednost Delco (bruto)": 57,52,
 "Skupna maloprodajna vrednost Delco (neto)": 47,93,
 "Simbol valute transakcije": "$",
 "Vrsta popusta": 1,
 "Stanje spora": false,
      "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
 "IncomingProductCode": 23,
 "PostingDate": "20210802",
 "PostingTime": "14:15:22",
 "ProductCode": 30,
 "ProductName": "Brezolovno – srednji oktanski števil",
      "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
 "SiteName": "Shell Broadway Ring",
 "SiteCode": 32,
      "Številka lokacije": 15,
 "Koda valute računa": "GBP",
 "Datum računa": "20210802",
 "Številka računa": 3201016193,
 "Gorivo": true,
 "VATApplicable": "Y",
 "PayerName": "Colours Services Ltd",
 "Številka plačnika": "GB12121212",
 "Številka nadrejenega stranke": "GB12121212",
 "Skupina plačnika": "H312066",
 "Ime skupine plačnika": "12162566 – STORITEV GORIVNE KARTICE",
 "Kontrolna številka": 6,
 "Kazalnik neto računa": "Y",
 "DelcoCode": 5,
      "NetworkCode": 3,
 "PurchasedInCountry": "Združeno kraljestvo",
 "SiteCountry": "Združeno kraljestvo",
 "VATCountry": "Združeno kraljestvo",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Pristojbine",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
 »Stopnja popusta«: 0,0022,
 »Številka računa«: 6803,
 »Oznaka vračila«: »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 ali C",
 "Datum transakcije": "20210801",
 "Čas transakcije": "12:16:58",
 "ID postavke transakcije": "H305908971030",
      "TrnIdentifier": "H305908971030",
 "Type": "SALE",
      "TransactionLine": 1,
 "TransactionType": "Nakup",
 "UTCOffset": "Europe/London",
 "VATCategory": "Standardna stopnja DDV v Združenem kraljestvu",
 "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,
      "Opis postavke": true,
 "Opis pravila provizije": "Enostavna provizija",
 "Pogostost": 1,
 "ID pravila provizije": 1,
 "Datum vnosa v sistem": "20210828",
      "SystemEntryTime": "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": "National Road",
 "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
}

Primer 2: Pridobivanje podrobnosti o transakcijah za gorivo

Zahteva:

POST /transaction-data/v1/pricedtransaction

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

Odgovor:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
      "Transakcije": [
 {
 "Vrsta": "Prodajni artikel / Stroškovni artikel",
 "ID kartice": 0,
 "PAN kartice": "7002051006629891000",
          "CardExpiry": "2026-06-16",
 "TransactionDate": "2026-06-16",
          "Čas transakcije": "niz",
 "UTC-razlika": "niz",
 "ID voznega parka": "XYZ1234",
 "Stanje števca kilometrov": 12345,
 "Ime voznika": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
          "Simbol valute transakcije": "$",
 "Neto znesek transakcije": 0,
 "Davek na transakcijo": 0,
 "Bruto znesek transakcije": 0,
 "neto znesek računa": 0,
 "davek na računu": 0,
 "bruto znesek računa": 0,
 "država nakupa": "Nemčija",
 "ID računa": 29484,
 "Številka računa": "GB99215176",
 "Ime računa": "MATTHEW ALGIE & COMPANY LIMITED",
 "Kratko ime računa": "niz",
          "Količina": 0,
 "Gorivo": true,
 "Cena na enoto v valuti transakcije": 0,
 "Cena na enoto v valuti računa": 0,
 "UnitDiscountTransactionCurrency": 0,
 "UnitDiscountInvoiceCurrency": 0,
 "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "InvoiceDate": "niz",
 "Koda lokacije": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Ime lokacije": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Država lokacije": "Nemčija",
 "Lokacija": {
 "Zemljepisna širina": "37.4224764",
 "Zemljepisna dolžina": "122.0842499"
 },
 "Ime skupine kartic": "006240 FIRE BRIGHT SOLUTIONS",
 "Številka potrdila": "1234",
 "ProductCode": "10 - TMF stroški",
 "ProductName": "Brezolovno – visok oktanski",
 "ProductGroupId": 1,
 "ProductGroupName": "Nadrejena skupina izdelkov",
          "DelCoExchangeRate": 0,
 "ColCoExchangeRate": 0,
 "IsShellSite": true,
 "Network": "100013\tSTEINDORFER",
 "SiteGroupId": 202,
          "ImeSkupineLokacij": "CZ 9100 ECONOMY NETWORK",
 "DatumObjave": "niz",
 "KodaIzdajatelja": "7002",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Nizozemska",
          "ReleaseCode": "8",
 "CardGroupId": "niz",
 "CardSequenceNumber": "2",
 "CheckDigit": "niz",
 "FleetIDDescription": "niz",
          "VATRate": "0,20 za 20 %",
 "VATCategory": "1 – brez DDV",
 "VATonNetAmount": 0,
 "VATCountry": "Nizozemska",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Nakup ob predložitvi kartice, sicer prazno",
 "PINIndicator": "„Uporabljen PIN“",
          "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
          "EffectiveUnitDiscountInCustomerCurrency": 0,
 "EffectiveDiscountInCustomerCurrency": 0,
 "VATonNetAmountInCustomerCurrency": 0,
 "DiscountType": "2 pence na enoto",
 "TransactionStatus": "U",
 "SalesItemId": 18315958002,
 "PayerGroup": "niz",
 "PayerGroupName": "12119008 – SHELL GROUP OF COMPANIES",
 "Oznaka vračila": "niz",
 "ID prvotne prodajne postavke": "niz",
 "Ime Delco": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
          "DelcoCode": "14",
 "PayerNumber": "NL10042616",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
 "AuthorisationCode": "1011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
 "CRMNumber": "niz",
 "DisputeStatus": "Brez spora",
          "Stopnja popusta": 28,279,
 "Menjalni tečaj DelCoToColCo": 1,
 "Neto znesek v evrih": 0,
 "Znesek DDV v evrih": 0,
          "ParentCustomerNumber": "niz",
 "ParentCustomerName": "niz",
 "ParentCustomerId": 0,
 "IncomingSiteNumber": "100021",
 "Opis lokacije prejemnika": "HN3 INTI_02-82.02",
 "Koda valute prejemnika": "GBP",
 "Koda izdelka prejemnika": "30",
 "Koda kredit/debet": "D",
          "Oznaka popravka": "Y",
 "Dodatno1": "niz",
 "Dodatno2": "niz",
 "Dodatno3": "niz",
 "Dodatno4": "niz",
          "Rabatt na neto znesek v valuti stranke": -0,735,
 "Rabatt na neto znesek v valuti transakcije": "AVEE PTUAZONW CUBFAO COSFS",
 "Identifikator transakcije": "niz",
 "Vrsta kartice": "niz",
 "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
}

Primer 3: Pridobivanje povzetka transakcij s cenami

Zahteva:

POST /transaction-data/v1/pricedtransactionssummary

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

Odgovor:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
 "ProductName": "Diesel AGO",
 "ProductGroupId": 1,
 "ProductGroupName": "Goriva",
 "TotalFuelQuantity": 1250,75,
 "TotalNetAmount": 5420,50,
 "TotalGrossAmount": 6504,60,
      "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "CustomerRetailValueTotalNet": 5420,50,
 "CustomerRetailValueTotalGross": 6504,60
    }
  ]
}

Primer 4: Pridobivanje povzetka cen

Zahteva:

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

Odgovor:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114,13,
 "CustomerRetailValueTotalNet": 95,11,
            "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
 "ProductCode": "21",
            "ProductGroupId": 3,
 "ProductGroupName": "Motorni bencin",
 "ProductId": 21,
 "ProductName": "Brezolovni – visok oktanski",
 "SiteGroupId": 104,
 "SiteGroupName": "Privzete bencinske črpalke Shell v Avstriji",
 "TotalFuelQuantity": 17,0,
 "TotalGrossAmount": 114,13,
 "TotalNetAmount": 95,11
 }
    ]
}

Primer 5: Pridobivanje transakcij z več plačniki

Zahteva:

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
}

Odgovor:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
 "Type": "SalesItem"
 }
 ],
      "CardId": 275549,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
 "Čas transakcije": "14:30:45",
 "UTCOffset": "+01:00:00",
 "ID flote (vnos)": "XYZ1234",
      "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "£",
 "neto znesek transakcije": 47,71,
 "davek na transakcijo": 9,54,
 "bruto znesek transakcije": 57,25,
 "neto znesek računa": 47,71,
 "davek na računu": 9,54,
 "bruto znesek računa": 57,25,
 "država nakupa": "Nemčija",
      "ID računa": 29484,
 "Številka računa": "GB99215176",
 "Ime računa": "MATTHEW ALGIE & COMPANY LIMITED",
 "Kratko ime računa": "MATTHEW",
 "Količina": 43,28,
 "Gorivo": true,
      "Cena na enoto v valuti transakcije": 1,1074,
 "Cena na enoto v valuti računa": 1,1024,
 "Popust na enoto v valuti transakcije": -0,005,
 "Popust na enoto v valuti računa": -0,0051,
 "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "Datum računa": "20250815 09:30:00",
 "Koda lokacije": "050001",
 "Ime lokacije": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Država lokacije": "Nemčija",
 "Lokacija": {
 "Zemljepisna širina": "53.83606",
 "Zemljepisna dolžina": "-1.61854"
 },
 "Ime skupine kartic": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "6803",
 "ProductCode": "10",
 "Ime izdelka": "Brezolovno – visok oktanski števil",
 "ID skupine izdelkov": 2,
 "Ime skupine izdelkov": "Vsa goriva",
 "Menjalni tečaj DelCo": 0,851858,
 "ColCoExchangeRate": 0,851858,
 "IsShellSite": true,
      "Mreža": "SHELL",
 "ID skupine lokacij": 202,
 "Ime skupine lokacij": "CZ 9100 ECONOMY NETWORK",
 "Datum objave": "20250812 14:30:45",
      "IssuerCode": "7002",
 "PurchasedInCountryCode": "DE",
 "CustomerCountryCode": "NL",
      "CustomerCountry": "Nizozemska",
 "ReleaseCode": "8",
 "CardGroupId": "40000",
 "CardSequenceNumber": "617",
 "CheckDigit": "6",
 "FleetIDDescription": "YG67OUM",
 "VATRate": 0,2,
 "VATCategory": "1-Standardna stopnja",
 "VATonNetAmount": 9,54,
 "VATCountry": "Nizozemska",
      "EffectiveDiscountInTrxCurrency": -0,22,
 "TransactionType": "Nakup",
 "PINIndicator": "Uporabljen PIN",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "N",
 "CustomerCurrencyCode": "GBP",
 "Simbol valute stranke": "£",
 "Dejanski popust na enoto v valuti stranke": -0,0051,
 "Dejanski popust v valuti stranke": -0,22,
 "DDV na neto znesek v valuti stranke": 9,54,
 "Vrsta popusta": "2 pence na enoto",
 "Stanje transakcije": "I",
 "ID prodajne postavke": 18315958002,
 "Skupina plačnikov": "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",
      "Številka CRM": null,
 "Status spora": "Brez spora",
 "Stopnja popusta": 28,279,
 "Menjalni tečaj od pošiljatelja do prejemnika": 1,
      "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
 "ParentCustomerNumber": "GB12121212",
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
 "ParentCustomerId": 6494,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
 "IncomingCurrencyCode": "GBP",
 "IncomingProductCode": "30",
 "CreditDebitCode": "D",
 "CorrectionFlag": "N",
      "Additional1": "GBALLEGO0002452",
 "Additional2": null,
 "Additional3": null,
 "Additional4": null,
      "Rabatt na neto znesek v valuti stranke": -0,735,
 "Rabatt na neto znesek v valuti transakcije": -0,735,
 "Identifikator transakcije": "H305908971030",
 "Vrsta kartice": "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
}

Primer 6: Pridobivanje pravil za določanje cen na podlagi obsega

Zahteva:

POST /transaction-data/v1/volumebasedpricing

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

Odgovor:

{
  "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-Weekly – Monday",
 "NextCalculationDate": "20231223",
          "PreviousCalculatedDate": "20231223",
 "FeeRuleBasis": "3-Lump Sum",
 "FeeRuleCurrencyCode": "GBP",
 "FeeRuleCurrencySymbol": "£",
 "FeeRuleNa voljo od": "20231223",
 "Pravilo o provizijah velja do": "20231223",
 "Lokacije pravila o provizijah": [
 {
              "DelcoId": 866,
 "Country": "Združeno kraljestvo",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": "VALERO ENERGY LTD"
 }
 ],
 "FeeRuleProducts": [
 {
              "ProductGroupID": 3,
 "ProductGroupName": "Motorni bencin",
 "ProductCode": "30 za dizelsko gorivo AGO",
 "ProductId": "30 za dizelsko gorivo AGO",
 "ProductName": "Dizelsko gorivo AGO"
 }
 ],
          "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234,12
            }
 ]
 }
 ],
 "CurrentPeriodConsumption": [
 {
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "PriceRuleID": 100005,
 "Opis pravila o ceni": "PL/GAGO/GMOT/UL0.055",
 "Skupni obseg": 10000,78,
 "NextFeeCreationDate": "20231223"
 }
 ],
 "History": [
 {
 "FromDate": "20231223",
 "ToDate": "20231223",
 "ID pravila o provizijah": 8081,
 "Opis pravila o provizijah": "PT/P067/D120/P4.0",
 "TotalVolume": 12356,66
 }
      ],
 "Opozorila": [
 {
 "Sporočilo": "Sistem je zaradi nadgradnje nedosegljiv.",
 "Vrsta": "Izpad sistema"
 }
 ]
    }
  ]
}

Primer 7: Pridobivanje pravil za bonuse na podlagi obsega

Zahteva:

POST /transaction-data/v1/volumebasedbonus

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

Odgovor:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "MATTHEW",
 "PricingAccountFullName": "MATTHEW",
          "FeeRuleId": 1,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
 "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Plačilo plačniku",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Weekly – Monday",
          "Datum naslednjega izračuna": "20231223",
 "Datum prejšnjega izračuna": "20231223",
          "Osnova pravila o provizijah": "3-pavšalni znesek",
 "Koda valute pravila o provizijah": "GBP",
 "Simbol valute pravila o provizijah": "£",
 "Pravilo o provizijah velja od": "20231223",
 "FeeRuleAvailableTo": "20231223",
 "FeeRuleLocations": [
 {
 "DelcoId": 866,
 "Country": "Združeno kraljestvo",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": »VALERO ENERGY LTD«
 }
 ],
 »FeeRuleProducts«: [
 {
 »ProductGroupID«: 3,
 »ProductGroupName«: "Motorni bencin",
 "ProductCode": "30 za dizelsko gorivo AGO",
 "ProductId": "30 za dizelsko gorivo AGO",
 "ProductName": "Dizelsko gorivo AGO"
 }
 ],
 "FeeRuleTiers": [
            {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234,12
            }
 ],
 "Povezani računi": [
 {
 "ID povezanega računa": 12345,
 "Številka povezanega računa": "GB000000123",
 "AssociatedAccountShortName": "Kratko ime računa",
 "AssociatedAccountFullName": "Polno ime računa"
 }
 ]
        }
 ],
 "CurrentPeriodConsumption": [
 {
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "Month": 1,
 "Year": 2018,
 "TotalVolume": 10000,78
 }
 ],
 "HistoricalBonusPaid": [
 {
 "PayerId": 12345,
 "PayerNumber": "GB000000123",
 "PayerShortName": "Jorden",
 "PayerFullName": "MATTHEW",
          "ID računa": 123456,
 "Številka računa": "GB000000123",
 "Kratko ime računa": "SALT",
 "Polno ime računa": "ABCD1234",
          "ID računskega računa": 12345,
 "Številka računskega računa": "GB000000123",
 "Kratko ime računskega računa": "DFE1234",
          "InvoiceAccountFullName": "AZAD PVT LMT",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
          "FromDate": "20231223",
          "ToDate": "20231223",
 "BonusPaidTo": "5-Izplačilo povezanim strankam",
 "FeeItemId": 12345,
 "FeeRuleBasis": "2-Odstotek povečanja",
          "FeeItemCurrencyCode": "GBP",
 "FeeItemCurrencySymbol": "$",
 "ProratedVolume": 123,12,
 "TotalVolume": 123,12,
          "FeeProduct": "1562-Bonusni dizel 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": "Sistem je nedosegljiv zaradi nadgradnje.",
 "Type": "System Outage"
    }
  ]
}

Primer 8: Pridobivanje povzetka provizij

Zahteva:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Stroški kartice"
}

Odgovor:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "FeeTypeGroup": "Stroški kartice",
 "FeeTypeId": 1,
 "FeeType": "Letna pristojbina za kartico",
 "ProductId": 1234,
 "ProductCode": "FEE",
 "ProductName": "Pristojbina za kartico",
 "TotalFeeAmount": 125,00,
 "InvoiceCurrencyCode": "GBP",
      "InvoiceCurrencySymbol": "£"
    }
  ]
}

Primer 9: Pridobivanje izjem pri transakcijah

Zahteva:

POST /transaction-data/v1/exceptions

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

Odgovor:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Podatki": [
    {
 "Izjeme s karticami": [
 {
 "ID računa": 29484,
 "ID kartice": 1234,
 "PAN": "ABCD1234",
          "DriverName": "ANDREW GILBERRY",
 "VRN": "34235",
 "PayerId": 123455,
 "PayerNumber": "GB000000123",
          "AccountNumber": "GB99215176",
 "AccountShortName": "MATTHEW",
 "PayerShortName": "MATTHEW",
 "Day": 2,
          "Teden": 2,
 "Mesec": 5,
 "Leto": 2017,
 "Skupno število transakcij": 4,
 "Skupno število prodajnih artiklov": 4,
          "Skupna količina": 261,
 "Skupni znesek": 100,21,
 "Koda valute": "GBP",
 "Simbol valute": "$"
 }
 ],
      "Izjeme pri transakcijah": [
 {
 "ID prodajnega artikla": 18315958002,
 "ID kartice": 1234,
 "ID izdelka": 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",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "£",
 "Neto znesek transakcije": 123,12,
 "Davek na transakcijo": 123,12,
 "Bruto znesek transakcije": 123,12,
 "Neto znesek računa": 123,12,
 "Davek na računudavek": 123,12,
 "bruto znesek računa": 123,1,
 "država nakupa": "Francija",
 "ID računa": 1234,
 "številka računa": "GB99215176",
          "AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
 "AccountShortName": "MATTHEW ALGIE & COMPANY LIMITED",
          "Količina": 123,12,
 "Gorivo": true,
 "Cena na enoto v valuti transakcije": 123,12,
 "Cena na enoto v valuti računa": 123,12,
 „UnitDiscountTransactionCurrency“: 123,12,
 „UnitDiscountInvoiceCurrency“: 123,12,
 „IsInvoiced“: true,
 „InvoiceNumber“: „S04500493",
 "Datum računa": "20231223",
 "Koda lokacije": "50001",
 "Ime lokacije": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
          "Država lokacije": "Nemčija",
 "Lokacija": {
 "Lat": "37.4224764",
 "Lng": "122.0842499"
 },
          "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "1234",
 "ProductCode": "TMF Charges",
 "ProductName": "Brezolovno – visok oktanski števil",
 "ProductGroupId": 1234,
 "ProductGroupName": "Nadrejena skupina izdelkov",
          "DelCoExchangeRate": 123,12,
 "ColCoExchangeRate": 123,12,
 "IsShellSite": true,
 "Network": "Shell PH",
 "SiteGroupId": 202,
          "Ime skupine lokacij": "CZ 9100 ECONOMY NETWORK",
 "Datum objave": "20231223 12:12:12",
 "Koda izdajatelja": "7077 = CRT",
 "Koda države nakupa": "NL",
          "Koda države stranke": "NL",
 "Država stranke": "Nizozemska",
 "Koda izdaje": "8 za 702188",
 "CardGroupId": "200",
 "CardSequenceNumber": "2",
 "CheckDigit": "GHE1234",
 "FleetIDDescription": "Primer opisa",
          "Stopnja DDV": 0,2,
 "Kategorija DDV": "3 – oproščeno DDV",
 "DDV na neto znesek": 12,21,
 "Država DDV": "Nizozemska",
          "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Nakup ob predložitvi kartice, sicer prazno",
 "PINIndicator": "Y",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "Koda valute stranke": "GBP",
 "Simbol valute stranke": "£",
 "Dejanski popust na enoto v valuti stranke": 123,12,
 "Dejanski popust v valuti stranke": 123,12,
          "DDV na neto znesek v valuti stranke": 123,12,
 "Vrsta popusta": "3-odstotni",
 "Stanje transakcije": "U",
          "Skupina plačnikov": "12119008",
 "Oznaka vračila": "N",
 "ID prvotne prodajne postavke": "1231",
 "Ime izdajatelja kartice": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "NL10042616",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
 "AuthorisationCode": "11256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
          "Številka CRM": "ABCD1234",
 "Stanje spora": "6\tZnesek vrnjen spletnemu mestu",
 "Stopnja popusta": 28,279,
          "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 37,93,
 "EuroRebateAmount": 0,
 "EuroVATAmount": 7,96,
 "ParentCustomerNumber": "DRG1234"
 }
 ]
    }
  ]
}

Primer 10: Pridobivanje povzetka uporabe kartice

Zahteva:

POST /transaction-data/v1/cardusagesummary

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

Odgovor:

{
  "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": "Motorni bencin"
 }
 ]
    }
  ]
}

Obravnavanje napak

Pogoste kode napak

HTTP-stanje	Koda napake	Opis	Rešitev
200	N/A	Stanje: USPEŠNO	N/A
200	E0001	Napaka pri preverjanju veljavnosti	Preverite parametre zahtevka
401	E0003	Neavtorizirano	Preverite veljavnost OAuth žetona
403	E0003	Dostop prepovedan	Preverite uporabniška dovoljenja
404	E0005	Vire ni mogoče najti	Preverite, ali URL končne točke in vir obstajata
500	E0002	Neznana napaka / Notranja napaka strežnika	Obrnite se na podporo

Najboljše prakse

1. Uvedite avtentifikacijo OAuth 2.0

POMEMBNO: Vsi uporabniki morajo preiti na avtentifikacijo OAuth 2.0. Uvedite ustrezno upravljanje žetonov:

Shranite dostopne žetone v predpomnilnik in jih ponovno uporabite do izteka veljavnosti
Osvežite žetone pred iztekom veljavnosti (priporočljivo 60 sekund pred iztekom)
Varno shranjujte poverilnice odjemalca (uporabite spremenljivke okolja ali upravitelja skrivnosti)
Nikoli ne beležite ali razkrivajte dostopnih žetonov v kodi na strani odjemalca

2. Uporabljajte ID-je zahtevkov

Vedno vključite edinstven ID zahtevka (v formatu GUID) za sledljivost od začetka do konca

3. Izvedite stranjenje

Pri velikih naborih podatkov o transakcijah uporabite stranjenje , da se izognete časovnim omejitvam:

Nastavite ustrezno velikost strani (PageSize) (priporočeno: 50–100 zapisov)
Strani obdelujte zaporedno ali vzporedno
Obdelajte TotalPages in TotalRecords v odgovorih

4. Razumno uporabljajte datumske filtre

Pri poizvedovanju po transakcijskih podatkih:

Omejite časovna obdobja, da se izognete velikim naborom rezultatov
Dosledno uporabljajte filtre FromDate in ToDate
Za boljšo zmogljivost razmislite o poizvedovanju po mesecih ali tednih

5. Testiranje v okolju Sandbox

Integracijo vedno preizkusite v testnem/Sandbox okolju, preden prehoda v produkcijsko okolje

6. Shranite referenčne podatke v predpomnilnik

Shranite pravila za obračunavanje na podlagi obsega in pravila za bonuse v predpomnilnik, da zmanjšate število klicov API:

Ta pravila se redko spreminjajo
Pomnilnik redno osvežujte (npr. dnevno)
Parameter IncludeHistory uporabljajte le, kadar je to potrebno

SDK in primeri kode

Shell ponuja uradne SDK-je in izčrpne primere kode za pospešitev vaše integracije z API-jem za transakcijske podatke.

Razpoložljivi jeziki za SDK

Python – SDK s polno funkcionalnostjo in podporo za OAuth 2.0
TypeScript - Tipsko varen SDK s popolnimi definicijami tipov
Java - SDK na ravni podjetij
C#/.NET - Popolna integracija z .NET
PHP - Enostavnauporabna knjižnica PHP
Ruby – Ruby gem za nemoteno integracijo

Oglejte si uradne SDK-je in dokumentacijo

Podpora in viri

Tehnična podpora

Podpora: Tehnična podpora Shell
Prehod na OAuth 2.0: Podpora za migracijo na OAuth 2.0

Dokumentacija

Pomoč

Ko se obrnete na podporo, navedite:

Vaš client_id (nikoli ne delite svojega client_secret ali dostopnih žetonov)
RequestId iz odgovora API-ja
Časovni žig zahtevka
Okolje (Proizvodno/Testno)

Zadnja posodobitev: 1. julij 2026
Različica dokumenta: 1.0
Različica API-ja: 2.3.5

Izberite svoj jezik

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

Pregled

Ključne funkcije

Pomembno obvestilo – OAuth 2.0

Preverjanje pristnosti

OAuth 2.0 (standardna metoda preverjanja pristnosti)

Postopek OAuth 2.0

Korak 1: Pridobite dostopni žeton

Korak 2: Uporaba dostopnega žetona v zahtevkih API

Upravljanje žetonov

Strategija uvedbe OAuth 2.0

Zakaj preiti na OAuth 2.0?

Varnostne prednosti:

Operativne prednosti:

Pot migracije

Okolja

Hiter začetek

1. Pridobite svoje OAuth-overitvene podatke

2. Pridobite dostopni žeton

Primer cURL:

Odgovor:

3. Pošljite svojo prvo zahtevo API

Primer cURL:

Primer odgovora:

Referenca končnih točk API-ja

Transakcije s ceno

Povzetki transakcij

Upravljanje

Pravila na podlagi obsega

Izjeme

Pogosti primeri uporabe

Primer uporabe 1: Dnevno usklajevanje transakcij

Primer uporabe 2: Preverjanje in potrjevanje računov

Primer uporabe 3: Analiza porabe goriva in poročanje

Primer uporabe 4: Upravljanje več voznih parkov

Primer uporabe 5: Spremljanje izjem in odkrivanje goljufij

Primer uporabe 6: Analiza provizij in stroškov

Primer uporabe 7: Sledenje izdatkom posamezne kartice

Primer uporabe 8: Preverjanje upravičenosti do cenovnih stopenj na podlagi obsega

Primer uporabe 9: Sledenje bonusom in popustom

Primeri uporabe

Primer 1: Pridobivanje transakcij s ceno (vključno z EV)

Zahteva:

Odgovor:

Primer 2: Pridobivanje podrobnosti o transakcijah za gorivo

Zahteva:

Odgovor:

Primer 3: Pridobivanje povzetka transakcij s cenami

Zahteva:

Odgovor:

Primer 4: Pridobivanje povzetka cen

Zahteva:

Odgovor:

Primer 5: Pridobivanje transakcij z več plačniki

Zahteva:

Odgovor:

Primer 6: Pridobivanje pravil za določanje cen na podlagi obsega

Zahteva:

Odgovor:

Primer 7: Pridobivanje pravil za bonuse na podlagi obsega

Zahteva:

Odgovor:

Primer 8: Pridobivanje povzetka provizij

Zahteva:

Odgovor:

Primer 9: Pridobivanje izjem pri transakcijah

Zahteva:

Odgovor:

Primer 10: Pridobivanje povzetka uporabe kartice

Zahteva:

Odgovor:

Obravnavanje napak

Pogoste kode napak

Najboljše prakse

1. Uvedite avtentifikacijo OAuth 2.0

2. Uporabljajte ID-je zahtevkov

3. Izvedite stranjenje

4. Razumno uporabljajte datumske filtre

5. Testiranje v okolju Sandbox