Válassza ki a nyelvet

Gépi fordítás (Beta)

B2B Mobility Card Transaction Data 2.3.5

Állapotváltozások, karbantartási és verziófrissítések lekérdezése erről a API.

Shell B2B Mobility Card tranzakciós adatok API – Gyors útmutató

API-verzió: 2.3.5 | Hitelesítés: OAuth 2.0 | Állapot: Termelési környezet

Tovább

A Shell kártya tranzakciós adatok API egy REST-alapú API, amely lehetővé teszi a fejlesztők számára, hogy programozási úton lekérjék és elemezzék a Shell üzemanyagkártyák tranzakciós adatait. Az API hozzáférést biztosít az árazott tranzakciókhoz, a díjakhoz, a mennyiségalapú árazáshoz, a bónuszszabályokhoz, a kivételekhez és a kártyahasználati összefoglalókhoz.

Megjegyzés: Ez az útmutató kizárólag az OAuth 2.0 hitelesítésű végpontokat tárgyalja (alapútvonal: /transaction-data/v1). A régi Basic Auth végpontok (/fleetmanagement/v1/transaction) nem szerepelnek benne, mivel azokat fokozatosan kivonják a forgalomból.

Főbb jellemzők

  • Árazott tranzakciós adatok lekérése, beleértve az elektromos járművekkel kapcsolatos tranzakciókat is
  • Hozzáférés az üzemanyag-tranzakciók részleteihez, az értékesítési tételekkel és díjakkal együtt
  • Az üzemanyag- és NFR-tranzakciók tranzakciós összefoglaló adatainak lekérése
  • Mennyiségalapú árazási és bónuszszabályok lekérdezése
  • Díjtételek és díjösszefoglaló adatok lekérése
  • Hozzáférés a kártya- és tranzakciós kivételekhez
  • Kártyahasználati és kiadási adatok elemzése
  • Támogatás több fizetőfélre vonatkozó tranzakciós lekérdezésekhez

Fontos tudnivaló – OAuth 2.0

FONTOS: Az OAuth 2.0 mostantól a szabványos hitelesítési módszer

  • Új integrációk: Használja az OAuth 2.0-t a kezdetektől fogva
  • Meglévő integrációk: Tervezze meg az OAuth 2.0-ra való áttérést
  • Régi módszerek: A Basic Auth fokozatosan kivezetésre kerül

Vegye fel a kapcsolatot a Shell műszaki támogatásával, hogy megkapja az OAuth 2.0 hitelesítő adatait (client_id és client_secret).

Hitelesítés

OAuth 2.0 (szabványos hitelesítési módszer)

A Shell kártyatranzakciós adat-API a biztonságos hitelesítéshez az OAuth 2.0 kliens hitelesítőadatok áramlását használja.

FIGYELMEZTETÉS: Minden ügyfélnek érdemes az OAuth 2.0 hitelesítésre való áttérést terveznie. Ez a Shell Card Transaction Data API számára ajánlott és jövőbiztos hitelesítési módszer. A régi hitelesítési módszerek fokozatosan kivezetésre kerülnek.

OAuth 2.0 folyamat

1. lépés: Hozzáférési token beszerzése

Kérjen hozzáférési tokent az OAuth token végponttól:

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

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

2. lépés: A hozzáférési token használata az API-kérelmekben

Authorization: Bearer 
Content-Type: application/json

Tokenkezelés

A tokenkezelés bevált gyakorlatai:

  • Az hozzáférési tokenek élettartama korlátozott (általában 15 perc)
  • Vezessen be token-gyorsítótárazást a felesleges token-lekérdezések elkerülése érdekében
  • Frissítse a tokeneket lejáratuk előtt a szolgáltatás zavartalan működésének biztosítása érdekében
  • Soha ne ossza meg a client_secret értékét, és ne ágyazza be azt a kliensoldali kódba

OAuth 2.0 bevezetési stratégia

Miért érdemes áttérni az OAuth 2.0-ra?

Biztonsági előnyök:

  • Iparági szabványnak megfelelő hitelesítési protokoll
  • Az időkorlátozott hozzáférési tokenek csökkentik a biztonsági kockázatokat
  • Minden kérésnél hitelesítő adatok továbbítása nélkül
  • A tokenek cseréjének és visszavonásának jobb támogatása

Üzemeltetési előnyök:

  • Jobb skálázhatóság és teljesítmény
  • Jobb felügyeleti és ellenőrzési képességek
  • Egyszerűsített hitelesítőadatok-kezelés
  • Jövőbiztos integráció

Áttérési út

Ha jelenleg régebbi hitelesítési módszereket használ, kövesse ezt az átállási útvonalat:

  1. Kérjen OAuth 2.0 hitelesítő adatokat a Shell műszaki támogatásától
  2. Vezesse be az OAuth-tokenkezelést az alkalmazásában
  3. Végezzen alapos tesztelést a teszt-/sandbox környezetben
  4. Az átállás ideje alatt párhuzamos hitelesítést (OAuth + régi rendszer) hajtson végre
  5. Figyelje és ellenőrizze az OAuth-integrációt
  6. Az érvényesítés után váltson át kizárólag OAuth-ra
  7. A sikeres áttérés után a régi hitelesítési módszer leállítása

Környezetek

Az API két környezetben érhető el:

Környezet Alap-URL Cél
Termelés https://api.shell.com Élő termelési környezet
Teszt (Sandbox) https://api-test.shell.com/test Teszt- és fejlesztési környezet

Tipp: Mindig tesztelje az integrációt a Tesztkörnyezetben, mielőtt átállna a termelésre.

Gyors útmutató

1. Szerezze be OAuth-hitelesítő adatait

2. Hozzáférési token beszerzése

Először szerezze be az OAuth hozzáférési tokenjét:

cURL példa:

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=your-client-id&client_secret=your-client-secret"

Válasz:

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

3. Az első API-lekérdezés elvégzése

Példa: Árazott tranzakciók lekérése

cURL-példa:

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élda a válaszra:

{
  "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",
 "Kártyacsoport-azonosító": 40000,
 "Kártyacsoport-név": "006240 FIRE BRIGHT SOLUTIONS",
      "Kibocsátói kód": 7002,
 "Kártya PAN-kódja": "7002053465789891000",
 "Engedélyezési kód": 9,
 "Kártya sorszáma": 617,
      "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
      "UnitDiscountInvoiceCurrency": -0,0051,
 "ColCoExchangeRate": 0,851858,
 "InvoiceCurrencySymbol": "GBP",
 "CorrectionFlag": true,
 "CRMszám": 10,
 "Ügyfél országa": "Egyesült Királyság",
 "Ügyfél pénznemkódja": "GBP",
      "Vevői pénznemjel": "£",
 "Visszatérítés a vevői pénznemben kifejezett nettó összegre": 0,
 "Érvényes kedvezmény a vevői pénznemben": -0,22,
      "hatásos egységár-kedvezmény az ügyfél pénznemében": -0,0051,
 "egységár a számla pénznemében": 1,1024,
      "Számla adója": 0,
 "Számla bruttó összege": 57,25,
 "Számla nettó összege": 47,71,
 "ÁFA az ügyfél pénznemében kifejezett nettó összegre": 9,54,
      "Ügyfél kiskereskedelmi bruttó egységár": 0,
 "Ügyfél kiskereskedelmi bruttó összérték": 57,52,
 "Ügyfél kiskereskedelmi nettó összérték": 47,93,
      "TransactionTypeDescription": 9,59,
 "RebateonNetAmountInTransactionCurrency": -0,22,
 "EffectiveDiscountInTrxCurrency": -0,22,
 "DelCoToColCoExchangeRate": 0,
 "Cards": [
        275549
 ],
 "Egységnyi kedvezmény a tranzakciós pénznemben": -0,005,
      "Tranzakció bruttó összege": 57,25,
 "Tranzakció nettó összege": 47,71,
 "Tranzakciós adó": 9,54,
 "Nettó összegre vonatkozó áfa": 9,54,
 "Delco listaár egység nettó": 0,
 "Delco kiskereskedelmi egységár bruttó": 1,32888,
 "Egységár a tranzakciós pénznemben": 1,1074,
 "Delco kiskereskedelmi egységár nettó": 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”,
      "Termék kód": 30,
 "Termék neve": "Ólmentes – közepes oktánszámú",
 "Termékcsoport azonosító": 22,
      "Bejövő pénznemkód": "GBP",
 "Bejövő telephely leírása": "Shell Broadway Ring",
 "Helyszín": "Shell Broadway Ring",
 "Telephely neve": "Shell Broadway Ring",
 "Telephelykód": 32,
 "Bejövő telephelyszám": 15,
 "Számla pénznemkódja": "GBP",
 "Számla dátuma": "20210802",
 "Számlaszám": 3201016193,
 "Üzemanyag-termék": true,
 "ÁFA alkalmazandó": "Y",
 "Fizető neve": "Colours Services Ltd”,
 „Fizetőszám”: „GB12121212”,
 „Szülőügyfélszám”: „GB12121212”,
 „Fizetőcsoport”: „H312066”,
 „Fizetőcsoport neve”: „12162566 – ÜZEMANYAGKÁRTYA-SZOLGÁLTATÁS”,
 „CheckDigit”: 6,
 „NetInvoiceIndicator”: „Y”,
 „DelcoCode”: 5,
 „NetworkCode”: 3,
      "PurchasedInCountry": "Egyesült Királyság",
 "SiteCountry": "Egyesült Királyság",
 "VATCountry": "Egyesült Királyság",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Díjak",
 "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 vagy C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
      "UTCOffset": "Europe/London",
 "VATCategory": "Egyesült Királyság általános áfa-kulcsa",
 "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,
      "Eredeti tranzakciós tétel számla dátuma": "20220202",
 "Díjtípus-azonosító": 1,
 "Sor tétel leírása": true,
 "Díjszabály leírása": "Egyszerű díj",
      "Gyakoriság": 1,
 "Díjszabály azonosító": 1,
 "Rendszerbeviteli dátum": "20210828",
 "Rendszerbeviteli idő": "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": "Országút",
 "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": 1,
  "PageSize": 1,
  "TotalPages": 5
}

API végpontok referencia

Árazott tranzakciók

Végpont Módszer Leírás
/transaction-data/v1/priced POST Árazott tranzakciók részleteinek lekérése, beleértve az elektromos járművel kapcsolatos tranzakciókat is (OAuth 2.0)
/transaction-data/v1/pricedtransaction POST Üzemanyag-tranzakciók részleteinek lekérése az értékesítési tételekkel és díjakkal együtt (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions POST Több fizetőre vonatkozó árazott tranzakciós adatok lekérése (OAuth 2.0)

Gyakori felhasználási esetek:

  • Tranzakciók lekérése dátumtartomány szerint
  • Szűrés számlaállapot szerint (számlázott, nem számlázott stb.)
  • Keresés kártyaszám vagy jármű rendszám alapján
  • Elektromos járművek töltési tranzakcióinak lekérése
  • Több fizetőre vonatkozó tranzakciók lekérdezése

Tranzakciós összefoglalók

Végpont Módszer Leírás
/transaction-data/v1/pricedtransactionssummary POST Árazott tranzakciós összefoglaló adatok lekérése az üzemanyag és a nem üzemanyag-kapcsolatos (NFR) tételekről, az értékesítési tételekkel és díjakkal együtt (OAuth 2.0)
/transaction-data/v1/cardusagesummary POST Kártyára vonatkozó kiadási elemzés és használati összefoglaló lekérése (OAuth 2.0)

Visszatérési értékek:

  • Időszakonként összesített tranzakciós adatok
  • Teljes forgalom és összegek
  • Terméktípus és kategória szerinti bontás
  • Kártyaszintű kiadási elemzés

Díjkezelés

Végpont Módszer Leírás
/transaction-data/v1/feessummary POST A megadott fizető fél díjtételeinek összefoglaló adatainak lekérése (OAuth 2.0)

Díjinformációk:

  • A a tranzakciókra alkalmazott díjtételek
  • Az összes díj összefoglalása időszakonként
  • A díjak típus és kategória szerinti bontása
  • Díjelemzés fizető szintjén

Mennyiségalapú szabályok

Végpont Módszer Leírás
/transaction-data/v1/volumebasedpricing POST A hátralékdíj-szabályok lekérése beállítások lekérése az adott fizető számára (OAuth 2.0)
/transaction-data/v1/volumebasedbonus POST A bónusz és a társult bónusz szabályok beállításainak lekérése az adott fizető számára (OAuth 2.0)

Mennyiségalapú funkciók:

  • Hozzáférés a forgalom alapú árazási szabályokhoz
  • Bónuszszámítási szabályok lekérése
  • Társulási bónuszkonfigurációk lekérése

Kivételek

Végpont Módszer Leírás
/transaction-data/v1/exceptions POST Kártyával vagy tranzakcióval kapcsolatos kivételek lekérése (OAuth 2.0)

Kivételtípusok:

  • Tranzakciós érvényesítési hibák
  • Kártyahasználati rendellenességek
  • Engedélyezési kivételek

Gyakori felhasználási esetek

Ez a szakasz a gyakori üzleti forgatókönyveket a megfelelő API-végpontokhoz rendeli hozzá, hogy segítsen gyorsan azonosítani, mely API-kat kell használnia az Ön konkrét igényeinek.

1. használati eset: Napi tranzakció-egyeztetés

Forgatókönyv: Számviteli célokból naponta egyeztetnie kell a flotta kártyáin végzett összes tranzakciót.

Ajánlott API: /transaction-data/v1/priced

Miért ez az API: Ez a végpont átfogó tranzakciós részleteket nyújt, beleértve az elektromos járművek töltési tranzakcióit is, támogatja a rugalmas dátumszűrést, és tartalmazza mind a kiszámlázott, mind a még nem számlázott tranzakciókat. Tökéletes a napi egyeztetéshez, nagy adathalmazok esetén oldalszámozási támogatással.

Főbb paraméterek:

  • PostingDateFrom és PostingDateTo – Állítsa be tegnapi dátumra
  • InvoiceStatus – Minden tranzakcióhoz használja az „A” értéket
  • PageSize – Állítsa be 100-ra a hatékony adatlekérés érdekében

2. felhasználási eset: Számlák érvényesítése és ellenőrzése

Helyzet: Számlát kapott, és ellenőriznie kell az összes tranzakciós adatot, beleértve a díjakat és költségeket is.

Ajánlott API: /transaction-data/v1/pricedtransaction

Miért ez az API: Kifejezetten az üzemanyag-tranzakciók részletes adatainak szolgáltatására lett kialakítva, beleértve értékesítési tételeket és az összes kapcsolódó díjat. Ideális a számla érvényesítéséhez, mivel megegyezik a számla felépítésével.

Főbb paraméterek:

  • InvoiceNumber – Az ellenőrizendő konkrét számla
  • Számla dátuma – A számlázáson szereplő számla dátuma
  • IncludeFees – Állítsa „true”-ra az összes díjtétel megjelenítéséhez

3. felhasználási eset: Üzemanyag-fogyasztás elemzése és jelentése

Forgatókönyv: El kellemeznie az üzemanyag-fogyasztási mintákat az elmúlt hónapra vonatkozóan az útvonalak optimalizálása és a költségek csökkentése érdekében.

Ajánlott API-k:

  • /transaction-data/v1/pricedtransactionssummary – Összesített adatokhoz

Miért éppen ezek az API-k: Az összefoglaló végpontok termék, telephelycsoport és időszak szerinti összesített adatokat nyújtanak, így kiválóan alkalmasak trendelemzésre anélkül, hogy nagy tranzakciós mennyiségeket kellene feldolgozni.

Főbb paraméterek:

  • PostingDateFrom és PostingDateTo – Állítsa be az elmúlt 30 napra
  • ProductCode – Szűrés meghatározott üzemanyag-típusok szerint
  • ProductGroupName – Csoportosítás üzemanyag-kategóriák szerint

4. felhasználási eset: Több járműpark kezelése

Forgatókönyv: Több alfiókot vagy fizetőt kezel, és összesített jelentéskészítés céljából be kell szereznie az összesre vonatkozó tranzakciós adatokat.

Ajánlott API: /transaction-data/v1/multipayerspricedtransactions

Miért ez az API: Kifejezetten arra tervezték, hogy egyetlen API-hívással több fizetőre kiterjedő tranzakciókat lekérdezzen, ami jelentősen csökkenti a kérések számát és javítja a teljesítményt többflottás esetekben.

Főbb paraméterek:

  • Fiókok – A fizető azonosítóiból és számaiból (max. 10 fizető)
  • Számlaállapot - „A” minden tranzakció esetében
  • PostingDateFrom és PostingDateTo – Jelentési időszak

5. felhasználási eset: Kivételek figyelése és csalásfelismerés

Forgatókönyv: A csalás vagy visszaélés megelőzése érdekében azonosítani szeretné a szokatlan tranzakciós mintákat, például a nagy értékű tranzakciókat, a túlzott üzemanyag-mennyiségeket vagy a rendellenes használatú kártyákat.

Ajánlott API: /transaction-data/v1/exceptions

Miért ez az API: Kifejezetten a meghatározott küszöbértékeket meghaladó tranzakciók azonosítására készült, így ideális a kivételek és a potenciális csalások figyelemmel kísérésére.

Főbb paraméterek:

  • Feltétel – Állítsa be a küszöbérték típusát (ValueGreaterThan, VolumeGreaterThan stb.)
  • Érték – Határérték meghatározása
  • Kimeneti típus – „Tranzakció” tranzakciós kivételek esetén
  • TransactionsFromDate és TransactionsToDate – Figyelési időszak

6. felhasználási eset: Díj- és költségelemzés

Forgatókönyv: Meg kell ismernie a számlájára alkalmazott összes díjat és költséget, hogy azonosíthassa a költségmegtakarítási lehetőségeket, illetve ellenőrizhesse a számlázást.

Ajánlott API: /transaction-data/v1/feessummary

Miért ez az API?: Összesített díjinformációkat nyújt díjtípus, termékcsoport és díjcsoport szerint összesített díjinformációkat nyújt, megkönnyítve ezzel a díjstruktúrák elemzését és a magas költségű területek azonosítását.

Főbb paraméterek:

  • InvoiceStatus – „I” kizárólag számlázott díjak esetén
  • FeeTypeGroup – Szűrés „Kártyadíjak”, „Számládíjak” stb. szerint.
  • PostingDateFrom és PostingDateTo – Elemzési időszak

7. felhasználási eset: Egyedi kártyakiadások Nyomon követés

Forgatókönyv: Egy járművezető az elmúlt 6 hónap tranzakciós előzményeit kéri, vagy Önnek elemeznie kell egy adott kártya kiadási szokásait.

Ajánlott API: /transaction-data/v1/cardusagesummary

Miért ez az API: Részletes kiadási elemzést nyújt az egyes kártyákról az elmúlt 7 hónapra vonatkozóan, helyszín és termék szerint csoportosítva, ami kiválóan alkalmas kártyaszintű jelentések készítésére.

Főbb paraméterek:

  • CardId vagy PAN – Az elemzendő konkrét kártya
  • CardExpiry – További érvényesítéshez
  • AccountId – Opcionális fiókszűrő

8. felhasználási eset: Jogosultság-ellenőrzés a mennyiségalapú árazáshoz

Forgatókönyv: Ellenőrizni szeretné, hogy fiókja jogosult-e a mennyiségalapú árazási szintekre, és szeretné megismerni a jelenlegi felhasználási szintjét a meghatározott küszöbértékekhez viszonyítva.

Ajánlott API: /transaction-data/v1/volumebasedpricing

Miért ez az API: Megjeleníti a késedelmi díjakra vonatkozó szabályokat, a szintkonfigurációkat és az aktuális mennyiségi felhasználást, segítve az árazási struktúrák megértését és a jobb szintek elérésének megtervezését.

Főbb paraméterek:

  • PayerNumber – A fizető fiókja
  • IncludeHistory – Állítsa true értékre a korábbi számítások megtekintéséhez
  • IncludeCurrentPeriodVolume – Állítsa „true”-ra a havi-havi bontáshoz

9. felhasználási eset: Bónuszok és visszatérítések nyomon követése

Forgatókönyv: Forgalom alapú bónuszmegállapodásai vannak, és nyomon szeretné követni a bónuszküszöbök elérése felé tett előrehaladását, valamint meg szeretné tekinteni a korábban megszerzett bónuszokat.

Ajánlott API: /transaction-data/v1/volumebasedbonus

Miért ez az API: Teljes körű részleteket nyújt a bónuszszabályokról, az aktuális időszak fogyasztásáról és a korábbi bónuszszámításokról, lehetővé téve a beszerzés optimalizálását a bónuszok maximalizálása érdekében.

Főbb paraméterek:

  • PayerNumber – A fizető fiókja
  • IncludeHistory – Állítsa true értékre a korábbi bónusz kifizetések megtekintéséhez
  • IncludeCurrentPeriodVolume – Állítsa „true”-ra a jelenlegi időszak előrehaladásának nyomon követéséhez

Használati példák

1. példa: Árazott tranzakciók lekérése (EV-vel együtt)

Kérés:

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

Válasz:

{
  "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",
      "Kártyacsoport-azonosító": 40000,
 "Kártyacsoport-név": "006240 FIRE BRIGHT SOLUTIONS",
 "Kibocsátói kód": 7002,
 "Kártya-PAN": "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": "Egyesült Királyság",
 "CustomerCurrencyCode": "GBP",
      "Ügyfél pénznemjelölése": "£",
 "Visszatérítés az ügyfél pénznemében kifejezett nettó összegre": 0,
 „EffectiveDiscountInCustomerCurrency”: -0,22,
 „EffectiveUnitDiscountInCustomerCurrency”: -0,0051,
 „UnitPriceInInvoiceCurrency”: 1,1024,
      "Számla adója": 0,
 "Számla bruttó összege": 57,25,
 "Számla nettó összege": 47,71,
 "ÁFA a nettó összegre az ügyfél pénznemében": 9,54,
 "Ügyfél kiskereskedelmi egységár bruttó": 0,
 "Ügyfél kiskereskedelmi érték összesen bruttó": 57,52,
 "Ügyfél kiskereskedelmi érték összesennettó": 47,93,
 "Tranzakciótípus leírása": 9,59,
      "Visszatérítés a tranzakciós pénznemben kifejezett nettó összegre": -0,22,
 "Érvényes kedvezmény a tranzakciós pénznemben": -0,22,
 "Szállító- és vevő pénznem közötti árfolyam": 0,
 "Kártyák": [
 275549
      ],
 „Egységnyi kedvezmény a tranzakciós pénznemben”: -0,005,
 „Tranzakció bruttó összege”: 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": "Ólmentes – közepes oktánszámú",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
 "SiteName": "Shell Broadway Ring",
 "SiteCode": 32,
      "Beérkező telephely száma": 15,
 "Számla pénznemkódja": "GBP",
 „Számla dátuma”: „20210802”,
 „Számlaszám”: 3201016193,
 „Üzemanyag-termék”: true,
 „ÁFA alkalmazandó”: „Y”,
 „Fizető neve”: „Colours Services Ltd”,
 „Fizető száma”: „GB12121212”,
 „Szülő ügyfélszáma”: „GB12121212”,
 „Fizetőcsoport”: "H312066",
 "Fizetőcsoport neve": "12162566 - ÜZEMANYAGKÁRTYA-SZOLGÁLTATÁS",
      "Ellenőrző szám": 6,
 "Nettó számla jelző": "Y",
 "Delco-kód": 5,
 "Hálózati kód": 3,
      "Vásárlás helye": "Egyesült Királyság",
 "Telephely országa": "Egyesült Királyság",
 "ÁFA-ország": "Egyesült Királyság",
      "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
      "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Díjak",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
      "Visszatérítési arány": 0,0022,
 "Bizonylat száma": 6803,
 "Visszatérítés jelző": "Y",
 "Telephelycsoport-azonosító": 202,
 "Telephelycsoport neve": "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 vagy C",
      "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 „TrnIdentifier”: „H305908971030”,
 „Type”: „SALE”,
 „TransactionLine”: 1,
 „TransactionType”: „Purchase”,
 „UTCOffset”: „Europe/London”,
 „VATCategory”: „Egyesült Királyság általános áfa-kulcsa”,
 „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,
      "Díjszabály leírása": "Egyszerű díj",
 "Gyakoriság": 1,
 "Díjszabály azonosító": 1,
 "Rendszerbeviteli dátum": "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": "Országút",
 "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
}

2. példa: Üzemanyag-tranzakciók részleteinek lekérése

Kérés:

POST /transaction-data/v1/pricedtransaction

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

Válasz:

{
  "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",
          "Tranzakció időpontja": "string",
 "UTC-eltolás": "string",
          "FleetIdInput": "XYZ1234",
 "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
          "Tranzakciós pénznemkód": "GBP",
 "Tranzakciós pénznemjel": "$",
 "Tranzakciós nettó összeg": 0,
 "Tranzakciós adó": 0,
 "Tranzakciós bruttó összeg": 0,
 „Számla nettó összege”: 0,
 „Számla adója”: 0,
 „Számla bruttó összege”: 0,
 „Vásárlás helye”: „Németország”,
 „Számlaazonosító”: 29484,
          "Számlaszám": "GB99215176",
 "Számla név": "MATTHEW ALGIE & COMPANY LIMITED",
 "Számla rövid neve": "string",
 "Mennyiség": 0,
          "FuelProduct": true,
 "UnitPriceInTransactionCurrency": 0,
 "UnitPriceInInvoiceCurrency": 0,
 "UnitDiscountTransactionCurrency": 0,
          "Egységár-kedvezmény számla pénznemében": 0,
 "Számlázva": true,
 "Számlaszám": "S04500493",
 "Számla dátuma": "string",
          "Telephelykód": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Telephelynév": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
          "SiteCountry": "Németország",
 "Location": {
 "Latitude": "37.4224764",
            "Hosszúság": "122.0842499"
 },
 "Kártyacsoport neve": "006240 FIRE BRIGHT SOLUTIONS",
 "Nyugta száma": "1234",
 "Termék kód": "10 - TMF Charges",
 "ProductName": "Ólommentes – Magas oktánszámú",
 "ProductGroupId": 1,
 "ProductGroupName": "Fő termékcsoport",
 "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”: „Hollandia”,
 „ReleaseCode”: „8”,
 „CardGroupId”: „string”,
 „CardSequenceNumber”: „2”,
 „CheckDigit”: „string”,
 „FleetIDDescription”: „string",
 „VATRate”: „0,20 (20%)”,
 „VATCategory”: „1 – Nulla százalékos”,
 „VATonNetAmount”: 0,
 „VATCountry”: "Hollandia",
 "EffectiveDiscountInTrxCurrency": 0,
          "TransactionType": "Vásárlás kártya jelenlétével, egyébként üres",
 "PINIndicator": "„PIN használata”",
 "VATApplicable": "I",
 "NetInvoiceIndicator": "I",
 "CustomerCurrencyCode": "GBP",
 "Ügyfél pénznem szimbóluma": "£",
 "Érvényes egységnyi kedvezmény az ügyfél pénznemében": 0,
 "Érvényes kedvezmény az ügyfél pénznemében": 0,
 "ÁFA a nettó összegre az ügyfél pénznemében": 0,
          "Kedvezménytípus": "2 penny darabonként",
 "Tranzakcióállapot": "U",
 "Értékesítési tétel azonosítója": 18315958002,
 "Fizetőcsoport": "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",
          "Tranzakciós sor": "1",
 "Elszámolás engedélyezve": "I",
 "CRM-szám": "string",
          "Vitás állapot": "Nincs vita",
 "Visszatérítési arány": 28,279,
 "DelCoToColCo árfolyam": 1,
 "Nettó euróösszeg": 0,
 „EuroVATAmount”: 0,
 „ParentCustomerNumber”: „string”,
 „ParentCustomerName”: „string",
 "ParentCustomerId": 0,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
 "IncomingCurrencyCode": "GBP",
 "Bejövő termék kód": "30",
 "Hitel/terhelés kód": "D",
 "Javítási jelző": "Y",
 "Kiegészítő 1": "string",
 "Additional2": "string",
 "Additional3": "string",
 "Additional4": „string”,
 „RebateonNetAmountInCustomerCurrency”: -0,735,
 „RebateonNetAmountInTransactionCurrency”: „AVEE PTUAZONW CUBFAO COSFS”,
 „TrnIdentifier”: „string”,
 „Kártyatípus": "string",
 "Delco listaári egység nettó": 30,5,
 "Delco kiskereskedelmi ári egység nettó": 1,921,
 "Delco kiskereskedelmi ári egység bruttó": 0,
 "Delco kiskereskedelmi érték összesen nettó": 0,
          "DelcoRetailValueTotalGross": 0,
 "CustomerRetailPriceUnitGross": 0,
 "CustomerRetailValueTotalNet": 0,
          "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "string"
 }
 ]
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 15
}

3. példa: Árazott tranzakciók összefoglalásának lekérése

Kérés:

POST /transaction-data/v1/pricedtransactionssummary

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

Válasz:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
 "ProductName": "Diesel AGO",
 "ProductGroupId": 1,
 "ProductGroupName": "Üzemanyagok",
 "TotalFuelQuantity": 1250,75,
      "TotalNetAmount": 5420,50,
 "TotalGrossAmount": 6504,60,
 "InvoiceCurrencyCode": "GBP",
      "Számla pénznem szimbóluma": "£",
 "Vevői kiskereskedelmi nettó összérték": 5420,50,
 "Vevői kiskereskedelmi bruttó összérték": 6504,60
    }
  ]
}

4. példa: Árösszefoglaló lekérése

Kérés:

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

Válasz:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114,13,
 "CustomerRetailValueTotalNet": 95,11,
 "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
 "ProductCode": "21",
            "Termékcsoport-azonosító": 3,
 "Termékcsoport-név": "Motorbenzin",
 "Termék-azonosító": 21,
 "Terméknév": "Ólmentes – Magas oktánszámú",
 "Hálózatcsoport-azonosító": 104,
 "Hálózatcsoport-név": "Alapértelmezett Shell-tankolók Ausztriában",
 "Teljes üzemanyag-mennyiség": 17,0,
 "Teljes bruttó összeg": 114,13,
 "Teljes nettó összeg": 95,11
 }
    ]
}

5. példa: Több fizetővel rendelkező tranzakciók lekérése

Kérés:

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
}

Válasz:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
        {
 "Type": "SalesItem"
 }
 ],
 "CardId": 275549,
      "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
      "TranzakcióIdő": "14:30:45",
 "UTC-eltolás": "+01:00:00",
 "FlottaAzonosító": "XYZ1234",
      "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "Számla pénznem szimbóluma": "£",
 "Tranzakciós pénznem kódja": "GBP",
 "Tranzakciós pénznem szimbóluma": "£",
 "Tranzakció nettó összege": 47,71,
      "Tranzakciós adó": 9,54,
 "Tranzakciós bruttó összeg": 57,25,
 "Számla nettó összege": 47,71,
 "Számla adója": 9,54,
      "Számla bruttó összege": 57,25,
 "Vásárlás helye": "Németország",
 "Számlaazonosító": 29484,
 "Számlaszám": "GB99215176",
      "Számla név": "MATTHEW ALGIE & COMPANY LIMITED",
 "Számla rövid neve": "MATTHEW",
 "Mennyiség": 43,28,
 "Üzemanyag-termék": true,
 "Egységár a tranzakciós pénznemben": 1,1074,
 "Egységár a számla pénznemében": 1,1024,
 "Egységár-kedvezmény a tranzakciós pénznemben": -0,005,
 "Egységár-kedvezmény a számla pénznemében": -0,0051,
      "Számlázva": igaz,
 "Számlaszám": "S04500493",
 "Számla dátuma": "20250815 09:30:00",
      "SiteCode": "050001",
 "SiteName": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "Németország",
 "Location": {
 "Latitude": "53.83606",
        "Hosszúság": "-1,61854"
 },
 "Kártyacsoport-név": "006240 FIRE BRIGHT SOLUTIONS",
 "Bizonylat száma": "6803",
      "Termék kód": "10",
 "Termék neve": "Ólmentes – Magas oktánszámú",
 "Termékcsoport-azonosító”: 2,
 „Termékcsoport neve”: „Minden üzemanyag”,
 „DelCo árfolyam”: 0,851858,
 „ColCo árfolyam”: 0,851858,
 „Shell-állomás”: true,
 „Hálózat": "SHELL",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20250812 14:30:45",
 "IssuerCode": "7002",
 "PurchasedInCountryCode": "DE",
 "CustomerCountryCode": "NL",
 "Vevő országa": "Hollandia",
 "Kibocsátási kód": "8",
 "Kártyacsoport-azonosító": "40000",
 "Kártya sorszáma": "617",
 "Ellenőrző szám": "6",
      "FleetIDDescription": "YG67OUM",
 "VATRate": 0,2,
 "VATCategory": "1-Standard Rate",
 "VATonNetAmount": 9,54,
 "VATCountry": "Hollandia",
      "EffectiveDiscountInTrxCurrency": -0,22,
 "TransactionType": "Purchase",
 "PINIndicator": „PIN használata”,
 „VATApplicable”: „Y”,
 „NetInvoiceIndicator”: „N”,
 „CustomerCurrencyCode”: „GBP”,
 „CustomerCurrencySymbol”: „£”,
      "Érvényes egységár-kedvezmény az ügyfél pénznemében": -0,0051,
 "Érvényes kedvezmény az ügyfél pénznemében": -0,22,
 "ÁFA a nettó összegre az ügyfél pénznemében": 9,54,
 "Kedvezménytípus": "2 penny egységenként",
 "Tranzakciós állapot": "I",
 "Értékesítési tétel azonosítója": 18315958002,
      "Fizetőcsoport": "H312066",
 "Fizetőcsoport neve": "12119008 - SHELL VÁLLALATCSOPORT",
 "Visszatérítési jelző": "N",
 "Eredeti értékesítési tétel azonosítója": 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",
      "CRM-szám": null,
 "Vitás állapot": "Nincs vita",
 "Visszatérítési arány": 28,279,
 "Kibocsátó ország – Célország árfolyam": 1,
      "Nettó euróösszeg": 56,01,
 "Euró ÁFA-összeg": 11,2,
 "Szülőügyfélszám": "GB12121212",
 "Szülőügyfélnév": "FUEL CARD SERVICES LTD",
      "ParentCustomerId": 6494,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
      "Bejövő pénznemkód": "GBP",
 "Bejövő termékkód": "30",
 "Hitel/terhelés kód": "D",
 "Javítási jelző": "N",
 "Kiegészítő1": "GBALLEGO0002452",
      "Additional2": null,
 "Additional3": null,
 "Additional4": null,
 "RebateonNetAmountInCustomerCurrency": -0,735,
      "Visszatérítés a tranzakciós pénznemben kifejezett nettó összegre": -0,735,
 "Trn azonosító": "H305908971030",
      "CardType": "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
}

6. példa: Mennyiségalapú árképzési szabályok lekérése

Kérés:

POST /transaction-data/v1/volumebasedpricing

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

Válasz:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
          "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
          "PricingAccountShortName": "ABCD1234",
 "PricingAccountFullName": "ABCD1234",
 "FeeRuleId": 12345,
 "Díjszabási szabály leírása": "NL/GAGO/D018/UP0.0120>1",
 "Díjszabási szabály hatálybalépésének dátuma": "20231223",
          "Díjszabási szabály hatályvesztésének dátuma": "20231223",
 "Bónusz kifizetési címzettje": "1-Fizetőnek",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Heti – hétfő",
 "NextCalculationDate": "20231223",
 "PreviousCalculatedDate": "20231223",
          "Díjszabály alapja": "3-Egyszeri összeg",
 "Díjszabály pénznemkódja": "GBP",
          "Díjszabály pénznemjel": "£",
 "Díjszabály érvényességi kezdete": "20231223",
 "Díjszabály érvényességi vége": "20231223",
 "Díjszabály helyszínek": [
 {
              "DelcoId": 866,
 "Country": "Egyesült Királyság",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
              "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": „VALERO ENERGY LTD”
 }
 ],
 „FeeRuleProducts”: [
 {
 „ProductGroupID”: 3,
 „ProductGroupName”: „Motorbenzin”,
 „ProductCode”: „30 for Diesel AGO”,
 „Termékazonosító": "30 a Diesel AGO-hoz",
 "Terméknév": "Diesel AGO"
 }
 ],
 "Díjszabási szintek": [
 {
              "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234,12
 }
 ]
 }
 ],
      "Jelenlegi időszak fogyasztása": [
 {
 "Díjszabály azonosító": 12345,
          "Díjszabály leírása": "NL/GAGO/D018/UP0.0120>1",
 "Árszabály azonosítója": 100005,
 "Árszabály leírása": "PL/GAGO/GMOT/UL0.055",
 "TotalVolume": 10000,78,
 "NextFeeCreationDate": "20231223"
 }
 ],
 "History": [
 {
 "FromDate": "20231223",
 "ToDate": "20231223",
 "FeesRuleID": 8081,
 "FeesRuleDescription": "PT/P067/D120/P4.0",
 "TotalVolume": 12356,66
        }
 ],
 "Figyelmeztetések": [
 {
 "Üzenet": "A rendszer frissítés miatt nem elérhető.",
 "Típus": "Rendszerleállás"
 }
 ]
    }
  ]
}

7. példa: Mennyiségalapú bónuszszabályok lekérése

Kérés:

POST /transaction-data/v1/volumebasedbonus

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

Válasz:

{
  "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",
 "Díjszabály hatálybalépésének dátuma": "20231223",
 "Díjszabály hatályvesztésének dátuma": "20231223",
 "Bónusz kifizetési cím": "1-Fizetőnek",
          "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 „BonusPaidToAccountFullName”: „GB000000123”,
 „Frequency”: „3-Heti – hétfő”,
 „NextCalculationDate”: „20231223”,
 „PreviousCalculatedDate”: "20231223",
 "FeeRuleBasis": "3-Lump Sum",
 "FeeRuleCurrencyCode": "GBP",
          "Díjszabály pénznemjel": "£",
 "Díjszabály érvényességi kezdete": "20231223",
 "Díjszabály érvényességi vége": "20231223",
 "Díjszabály helyszínei": [
 {
              "DelcoId": 866,
 "Country": "Egyesült Királyság",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "Telephelycsoport-név": "VALERO ENERGY LTD",
 "Telephelykód": 999493,
 "Telephely-azonosító": 100007,
 "Telephely-név": "VALERO ENERGY LTD"
            }
 ],
 "FeeRuleProducts": [
            {
 "Termékcsoport-azonosító": 3,
 "Termékcsoport-név": "Benzin",
 "Termékkód": "30 a Diesel AGO-hoz",
 "Termékazonosító": "30 a Diesel AGO-hoz",
 "Terméknév": "Diesel AGO"
            }
 ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
              "TierMaximum": 1234,
 "Value": 1234,12
 }
 ],
 "AssociatedAccounts": [
 {
              "Társított fiók azonosító": 12345,
 "Társított fiókszám": "GB000000123",
 "Társított fiók rövid neve": "Fiók rövid neve",
 "Társított fiók teljes neve": „Számla teljes neve”
 }
 ]
 }
 ],
 „CurrentPeriodConsumption”: [
        {
 "Díjszabály azonosító": 12345,
 "Díjszabály leírás": "NL/GAGO/D018/UP0.0120>1",
 "Hónap": 1,
          "Year": 2018,
 "TotalVolume": 10000,78
 }
 ],
 "HistoricalBonusPaid": [
 {
 "PayerId": 12345,
 "PayerNumber": "GB000000123",
 "Fizető rövid neve": "Jorden",
 "Fizető teljes neve": "MATTHEW",
 "Számlaazonosító": 123456,
 "Számlaszám": "GB000000123",
          "Számla rövid neve": "SALT",
 "Számla teljes neve": "ABCD1234",
 "Számlázási számla azonosító": 12345,
 "Számlaszám": "GB000000123",
 "Számla rövid neve": "DFE1234",
 "Számla teljes neve": "AZAD PVT LMT",
          "Díjszabály azonosító": 12345,
 "Díjszabály leírás": "NL/GAGO/D018/UP0.0120>1",
 "Érvényességi kezdő dátum": "20231223",
 "ToDate": "20231223",
 "BonusPaidTo": "5-Kifizetés a kapcsolódó ügyfeleknek",
 "FeeItemId": 12345,
 "FeeRuleBasis": "2-Az emelés százalékos aránya",
          "Díjtétel pénznemkódja": "GBP",
 "Díjtétel pénznemjelölése": "$",
 "Arányos mennyiség": 123,12,
 "Teljes mennyiség": 123,12,
          "Díjtermék": "1562-Shell bónusz dízel",
 "Számla bruttó összege": 123,12,
 "Számla nettó összege": 123,12,
          "SzámlaÁFA-összeg": 123,12,
 "A díj törölve": igaz,
 "Díjtétel-sáv arányos mennyisége": 123,12,
          "Díjtétel-sáv teljes mennyisége": 123,12,
 "Sáv minimum": 123,
 "Sáv árfolyam": 123,12
 }
 ]
    }
  ],
  "Warnings": [
    {
 "Message": "A rendszer frissítés miatt nem elérhető.",
 "Type": "System Outage"
    }
  ]
}

8. példa: Díjösszefoglaló lekérése

Kérés:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Kártyadíjak"
}

Válasz:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Adatok": [
    {
 "Díjtípuscsoport": "Kártyadíjak",
      "Díjtípus-azonosító": 1,
 "Díjtípus": "Kártya éves díja",
 "Termékazonosító": 1234,
 "Termékkód": "FEE",
 "Terméknév": "Kártyadíj",
 "TotalFeeAmount": 125,00,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

9. példa: Tranzakciós kivételek lekérése

Kérés:

POST /transaction-data/v1/exceptions

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

Válasz:

{
  "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",
          "Fizető rövid neve": "MATTHEW",
 "Nap": 2,
 "Hét": 2,
 "Hónap": 5,
 "Év": 2017,
 "Tranzakciók száma összesen": 4,
 "Értékesített tételek száma összesen": 4,
 „Összes mennyiség”: 261,
 „Összérték”: 100,21,
 „Pénznemkód”: „GBP”,
 „Pénznemjel”: „$”
 }
 ],
      "Tranzakciós kivételek": [
 {
 "Értékesítési tétel azonosító": 18315958002,
 "Kártya azonosító": 1234,
 "Termék azonosító": 2,
 "Tranzakciós GUID": „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",
 "Tranzakciós pénznem szimbóluma": "£",
 "Tranzakció nettó összege": 123,12,
 "Tranzakciós adó": 123,12,
          "Tranzakciós bruttó összeg": 123,12,
 "Számla nettó összege": 123,12,
 "Számla adója": 123,12,
 "Számla bruttó összege": 123,1,
 "PurchasedInCountry": "France",
 "AccountId": 1234,
 "AccountNumber": "GB99215176",
 "AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
 "AccountShortName": "MATTHEW ALGIE & COMPANY LIMITED",
          "Mennyiség": 123,12,
 "Üzemanyag-termék": true,
 "Egységár a tranzakciós pénznemben": 123,12,
 "Egységár a számla pénznemében": 123,12,
 "Egységár-kedvezmény a tranzakciós pénznemben": 123,12,
 „Egységár-kedvezmény számla pénznemében”: 123,12,
 „Számlázva”: true,
 „Számlaszám”: „S04500493”,
 „Számla dátuma": "20231223",
 "Telephelykód": "50001",
 "Telephelynév": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Telephelyország": "Németország",
 "Hely": {
 "Szélesség": "37.4224764",
 "Lng": "122.0842499"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
          "ReceiptNumber": "1234",
 "ProductCode": "TMF Charges",
 "ProductName": "Ólmentes – Magas oktánszámú",
 "ProductGroupId": 1234,
 "ProductGroupName": "Szülő termékcsoport",
          "DelCoExchangeRate": 123,12,
 "ColCoExchangeRate": 123,12,
 "IsShellSite": true,
          "Hálózat": "Shell PH",
 "Telephelycsoport-azonosító": 202,
 "Telephelycsoport-név": "CZ 9100 ECONOMY NETWORK",
 "Könyvelési dátum": "20231223 12:12:12",
 "IssuerCode": "7077 = CRT",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Hollandia",
 "Kibocsátási kód": "8 a 702188-hoz",
 "Kártyacsoport-azonosító": "200",
 "CardSequenceNumber": "2",
 "CheckDigit": "GHE1234",
 "FleetIDDescription": "Példa leírásra",
 "VATRate": 0,2,
 "VATCategory": "3-VAT adómentes",
 "VATonNetAmount": 12,21,
 "VATCountry": "Hollandia",
 "EffectiveDiscountInTrxCurrency": 0,
          "TransactionType": "Vásárlás kártyával, egyébként üres",
 "PINIndicator": "Y",
 "VATApplicable": "Y",
          "Nettó számla jelző": "I",
 "Ügyfél pénznemkódja": "GBP",
 "Ügyfél pénznemjelölése": "£",
 „Érvényes egységnyi kedvezmény az ügyfél pénznemében”: 123,12,
 „Érvényes kedvezmény az ügyfél pénznemében”: 123,12,
 „ÁFA a nettó összegre az ügyfél pénznemében”: 123,12,
 „Kedvezménytípus": "3-százalékos",
 "Tranzakcióállapot": "U",
 "Fizetőcsoport": "12119008",
 "Visszatérítési jelző": "N",
 "Eredeti értékesítési tétel azonosítója": "1231",
          "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "NL10042616",
 "PayerName": "V.M. LE COMTE",
          "CardExpiryPeriod": "1901",
 "AuthorisationCode": "11256",
          "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
 "CRMNumber": "ABCD1234",
 "DisputeStatus": "6\tVisszaterhelt a webhelyre",
 "RebateRate": 28,279,
          "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 37,93,
 "EuroRebateAmount": 0,
 "EuroVATAmount": 7,96,
 "ParentCustomerNumber": "DRG1234"
 }
 ]
    }
  ]
}

10. példa: Kártyahasználati összefoglaló lekérése

Kérés:

POST /transaction-data/v1/cardusagesummary

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

Válasz:

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

Hibakezelés

Gyakori hibakódok

HTTP-állapot Hibakód Leírás Megoldás
200 N/A Állapot: SIKER N/A
200 E0001 Érvényesítési hiba Ellenőrizze a kérés paraméterek ellenőrzése
401 E0003 Jogosulatlan Ellenőrizze, hogy az OAuth-token érvényes-e
403 E0003 Tiltva Ellenőrizze a felhasználói jogosultságokat
404 E0005 Az erőforrás nem található Ellenőrizze, hogy a végpont URL-je és az erőforrás létezik-e
500 E0002 Ismeretlen hiba / Belső szerverhiba Vegye fel a kapcsolatot az ügyfélszolgálattal

Bevált gyakorlatok

1. Vezesse be az OAuth 2.0 hitelesítést

FONTOS: Minden ügyfélnek át kell állnia az OAuth 2.0 hitelesítésre. Vezessen be megfelelő tokenkezelést:

  • Tárolja a hozzáférési tokeneket a gyorsítótárban, és használja újra azok lejáratáig
  • Frissítsék a tokeneket lejáratuk előtt (ajánlott: 60 másodperccel korábban)
  • Tárolják az ügyfél hitelesítő adatait biztonságosan (használjon környezeti változókat vagy titkokkezelőt)
  • Soha ne naplózza és ne tegye közzé a hozzáférési tokeneket az ügyféloldali kódban

2. Használjon kérelemazonosítókat

Mindig adjon meg egy egyedi RequestId-t (GUID formátumban) a végpontok közötti nyomonkövethetőség érdekében

3. Végrehajtás: Oldalszámozás

Nagy tranzakciós adatkészletek esetén használjon oldalszámozást az időtúllépések elkerülése érdekében:

  • Állítsa be a megfelelő PageSize értéket (ajánlott: 50–100 rekord)
  • Feldolgozza az oldalakat egymás után vagy párhuzamosan
  • A válaszokban szereplő TotalPages és TotalRecords értékek kezelése

4. A dátumszűrők okos használata

Tranzakciós adatok lekérdezésekor:

  • Korlátozza a dátumtartományokat a nagy eredményhalmazok elkerülése érdekében
  • Használja következetesen a FromDate és ToDate szűrőket
  • A jobb teljesítmény érdekében fontolja meg a havi vagy heti lekérdezést

5. Teszteljen a Sandbox környezetben

Mindig tesztelje az integrációt a Test/Sandbox környezetben, mielőtt éles környezetbe helyezné

6. Tárolja gyorsítótárban a referenciaadatokat

Tárolja gyorsítótárban aalapú árképzési és bónuszszabályokat az API-hívások minimalizálása érdekében:

  • Ezek a szabályok ritkán változnak
  • A gyorsítótárat rendszeresen frissítse (pl.pl. naponta)
  • Csak szükség esetén használja az IncludeHistory paramétert

SDK és kódpéldák

A Shell hivatalos SDK-kat és átfogó kódpéldákat biztosít a Transaction Data API-val való integráció felgyorsításához.

Elérhető SDK-nyelvek

  • Python – Teljes funkcionalitású SDK OAuth 2.0 támogatással
  • TypeScript – Típusbiztos SDK teljes típusdefiníciókkal
  • Java - Vállalati szintű SDK
  • C#/.NET - Teljes .NET-integráció
  • PHP - Könnyen használható PHP-könyvtár
  • Ruby – Ruby gem a zökkenőmentes integrációhoz

Hivatalos SDK-k és dokumentáció megtekintése

Támogatás és források

Műszaki támogatás

Dokumentáció

Segítség

A támogatáshoz forduláskor adja meg:

  1. A client_id azonosítóját (soha ne adja meg a client_secret titkát vagy az hozzáférési tokeneket)
  2. A kérés azonosítója (RequestId) az API-válaszból
  3. A kérés időbélyege
  4. Környezet (Termelés/Teszt)

Utolsó frissítés: 2026. július 1.
Dokumentum verzió: 1.0
API verzió: 2.3.5

Rólunk

A Shell Fejlesztői Portál támogatja a partnereket a Shell API-kba való bekapcsolódásban, valamint abban, hogy ötleteiket termeléskész megoldásokká alakítsák.

Shell logó

Kapcsolat

Kapcsolat

Bejelentkezés a fiókjába

Kérdezze meg az AI-asszisztenst a Shell API-jairól és API-termékeiről