Selectați limba dvs.

Traducere automată (Beta)

B2B Mobility Card Transaction Data 2.3.5

Obțineți actualizări de stare, întreținere și versiune despre acest API.

API-ul Shell pentru date privind tranzacțiile cu cardul de mobilitate B2B – Ghid de pornire rapidă

Versiunea API: 2.3.5 | Autentificare: OAuth 2.0 | Stare: Producție

Prezentare generală

API-ul pentru datele tranzacțiilor cu cardul Shell este un API bazat pe REST care permite dezvoltatorilor să preia și să analizeze programatic datele tranzacțiilor de pe cardurile de combustibil Shell. API-ul oferă acces la tranzacții cu prețuri, comisioane, tarife bazate pe volum, reguli de bonus, excepții și rezumate privind utilizarea cardurilor.

Notă: Acest ghid acoperă doar punctele finale autentificate prin OAuth 2.0 (cale de bază: /transaction-data/v1). Punctele de capăt vechi cu autentificare Basic (/fleetmanagement/v1/transaction) nu sunt incluse, deoarece sunt în curs de eliminare treptată.

Caracteristici cheie

  • Preluarea detaliilor tranzacțiilor cu preț, inclusiv a tranzacțiilor cu vehicule electrice
  • Accesarea detaliilor tranzacțiilor de combustibil, împreună cu și comisioane
  • Obțineți date sumare privind tranzacțiile cu combustibil și tranzacțiile NFR
  • Interogare prețuri în funcție de volum și reguli privind bonusurile
  • Preluarea elementelor de comision și a datelor de sinteză privind comisioanele
  • Accesarea excepțiilor legate de carduri și tranzacții
  • Analizați datele privind utilizarea cardului și cheltuielile
  • Suport pentru interogări privind tranzacțiile cu mai mulți plătitori

Notificare importantă – OAuth 2.0

IMPORTANT: OAuth 2.0 este acum metoda standard de autentificare

  • Noi integrări: Utilizați OAuth 2.0 încă de la început
  • Integrări existente: Planificați-vă migrarea către OAuth 2.0
  • Metode vechi: Autentificarea de bază este în curs de eliminare

Contactați Serviciul de asistență tehnică Shell pentru a obține datele de autentificare OAuth 2.0 (client_id și client_secret).

Autentificare

OAuth 2.0 (metoda standard de autentificare)

API-ul Shell Card Transaction Data utilizează fluxul de acreditări client OAuth 2.0 pentru autentificare securizată.

AVERTISMENT: Toți clienții ar trebui să planifice adoptarea autentificării OAuth 2.0. Aceasta este metoda de autentificare recomandată și adaptată viitorului pentru API-ul de date privind tranzacțiile cu cardul Shell. Metodele de autentificare vechi sunt eliminate treptat.

Fluxul OAuth 2.0

Pasul 1: Obțineți un token de acces

Solicitați un token de acces de la punctul final al tokenului OAuth:

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

grant_type=client_credentials&client_id=ID-ul-dumneavoastră-de-client&client_secret=secretul-dumneavoastră-de-client

Pasul 2: Utilizați tokenul de acces în solicitările API

Authorization: Bearer 
Content-Type: application/json

Gestionarea tokenurilor

Cele mai bune practici privind gestionarea tokenurilor:

  • Tokenurile de acces au o durată de viață limitată (de obicei 15 minute)
  • Implementați stocarea în cache a tokenurilor pentru a evita solicitările inutile de tokenuri
  • Reîmprospătați tokenurile înainte de expirare pentru a asigura un serviciu neîntrerupt
  • Nu partajați niciodată client_secret-ul și nu îl încorporați în codul de pe partea clientului

Strategia de adoptare a OAuth 2.Strategia de adoptare a OAuth 2.0

De ce să migrați la OAuth 2.0?

Avantaje de securitate:

  • Protocol de autentificare conform standardelor din industrie
  • Tokenurile de acces cu durată limitată reduc riscurile de securitate
  • Nu se transmit date de autentificare odată cu fiecare solicitare
  • Suport îmbunătățit pentru rotația și revocarea tokenurilor

Avantaje operaționale:

  • Scalabilitate și performanță îmbunătățite
  • Capacități îmbunătățite de monitorizare și audit
  • Gestionare simplificată a datelor de autentificare
  • Integrare adaptată la viitor

Calea de migrare

Dacă utilizați în prezent metode de autentificare învechite, urmați această cale de migrare:

  1. Solicitați credențialele OAuth 2.0 de la Suportul tehnic Shell
  2. Implementați gestionarea tokenurilor OAuth în aplicația dvs.
  3. Testați temeinic în mediul de testare/Sandbox
  4. Rulați autentificarea în paralel (OAuth + metoda veche) în timpul tranziției
  5. Monitorizați și validați integrarea OAuth
  6. Treceți exclusiv la OAuth odată ce integrarea a fost validată
  7. Dezactivați autentificarea veche după migrarea cu succes

Mediile

API-ul este disponibil în două medii:

Mediu URL de bază Scop
Producție https://api.shell.com Mediu de producție activ
Test (Sandbox) https://api-test.shell.com/test Mediu de testare și dezvoltare

Sfat: Testați întotdeauna integrarea în mediul de testare înainte de a trece la producție.

Ghid de pornire rapidă

1. Obțineți datele de autentificare OAuth

2. Obțineți un token de acces

Mai întâi, obțineți tokenul de acces OAuth:

Exemplu 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=ID-ul-tău-de-client&client_secret=secretul-tău-de-client"

Răspuns:

{secret-client"

Răspuns:

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

3. Efectuați prima solicitare API

Exemplu: Obțineți tranzacțiile cu prețuri

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

Răspuns de exemplu:

{
  "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": "Regatul Unit",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
 "Reducere pe suma netă în moneda clientului": 0,
 "Reducere efectivă în moneda clientului": -0,22,
      "ReducereUnitarăEfectivăÎnMonedaClientului": -0,0051,
 "PrețUnitarÎnMonedaFacturii": 1,1024,
 "TaxăFactură": 0,
 „Suma brută a facturii”: 57,25,
 „Suma netă a facturii”: 47,71,
 „TVA pe suma netă în moneda clientului”: 9,54,
      „Prețul cu amănuntul unitar brut al clientului”: 0,
 „Valoarea totală brută cu amănuntul a clientului”: 57,52,
 „ValoareaTotalăNetădeVânzareCuAmănuntulPentruClient”: 47,93,
 „DescriereaTipului deTranzacție”: 9,59,
 „ReducerepeSumaNetăînMonedaTranzacției”: -0,22,
 „ReducereEfectivăînMonedaTranzacției”: -0,22,
 „Curs de schimb între moneda de livrare și moneda de destinație”: 0,
      "Carduri": [
 275549
 ],
 "ReducereUnitară în MonedaTranzacției": -0,005,
 "SumaBrutăaTranzacției": 57,25,
 „Suma netă a tranzacției”: 47,71,
 „Taxa tranzacției”: 9,54,
 „TVA pe suma netă”: 9,54,
 „Prețul de listă Delco pe unitate (net)”: 0,
      "Preț cu amănuntul Delco pe unitate brut": 1,32888,
 "Preț unitar în moneda tranzacției": 1,1074,
 "Preț cu amănuntul Delco pe unitate net": 1,1074,
 "Valoare totală cu amănuntul Delco brut": 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”: „Fără plumb – octan mediu”,
 „ProductGroupId”: 22,
 „IncomingCurrencyCode”: „GBP”,
      "Descriere stație de intrare": "Shell Broadway Ring",
 "Locație": "Shell Broadway Ring",
 "Numele stației": "Shell Broadway Ring",
 "Cod stație": 32,
 "Număr stație de intrare": 15,
      "Codul monedei facturii": "GBP",
 "Data facturii": "20210802",
      "InvoiceNumber": 3201016193,
 "FuelProduct": true,
 "VATApplicable": "Y",
 "PayerName": "Colours Services Ltd",
 "PayerNumber": "GB12121212",
 "ParentCustomerNumber": "GB12121212",
 "PayerGroup": "H312066",
      "NumeleGrupuluiPlătitor": "12162566 - SERVICIU CARD DE COMBUSTIBIL",
 "CifrăDeVerificare": 6,
 "IndicatorFacturăNetă": "Y",
 "DelcoCode": 5,
 "NetworkCode": 3,
 "PurchasedInCountry": "Regatul Unit",
 "SiteCountry": "Regatul Unit",
 "VATCountry": "Regatul Unit",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
      "ID-ul inițial al articolului de vânzare": "Null",
 "Descrierea ID-ului flotei": "YG67OUM",
 "ID-ul clientului părinte": 6494,
 "Indicator PIN": "Y, N",
      "ProductGroupName": "Taxe",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
 „Rata de rabat”: 0,0022,
 „Număr chitanță”: 6803,
 „Indicator rambursare”: „Y”,
 „ID grup locații”: 202,
 „Denumire grup locații”: „CZ 9100 ECONOMY NETWORK”,
 „Latitudine”: 53,83606,
 „Longitudine”: -1,61854,
 „Curs de schimb DelCo”: 0,851858,
 „EuroRebateAmount": -0,258259,
 "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
      „ParentCustomerName”: „FUEL CARD SERVICES LTD”,
 „IsInvoiced”: false,
 „TransactionCurrencyCode”: „GBP”,
 „CreditDebitCode”: „D sau C”,
      "DataTranzacției": "20210801",
 "OraTranzacției": "12:16:58",
 "IDElementTranzacție": "H305908971030",
      "TrnIdentifier": "H305908971030",
 "Type": "VÂNZARE",
 "TransactionLine": 1,
 "TransactionType”: „Achiziție”,
 „UTCOffset”: „Europe/London”,
 „VATCategory”: „Cota standard de TVA din Regatul Unit”,
 „VATRate”: 0,2,
 „VehicleRegistration”: „YG67OUM”,
      "IsCancelled": "Y",
      "SumaBrutăColCo": 57,25,
 "SumaNetăColCo": 47,71,
 "SumaTVA ColCo": 9,54,
 "SimbolMonedăOriginală": "$",
 "CodMonedăOriginală": "$",
 „SumaTVA inițială”: 0,
 „Text embosat”: „PARKLANE PROPERTIES LTD”,
 „Cursul de schimb inițial”: 0,
 „Data facturii elementului de tranzacție inițial”: „20220202”,
 „FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "Taxă simplă",
 "Frequency": 1,
 "FeeRuleId": 1,
 "SystemEntryDate": „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”: „Drum național”,
 „CustomerCountryIsoCode”: „DE”,
 „EVOperator”: „Shell Recharge”,
 „EVSerialId”: „GBALLEGO0002452",
 „Număr de serie punct de încărcare EV”: „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
}

Referință puncte finale API

Tranzacții cu preț

Punct final Metodă Descriere
/transaction-data/v1/priced POST Obține detalii despre tranzacțiile cu preț, inclusiv tranzacțiile pentru vehicule electrice (OAuth 2.0)
/transaction-data/v1/pricedtransaction POST Obține detalii despre tranzacțiile de combustibil, inclusiv articolele vândute și comisioanele (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions POST Obține detalii despre tranzacțiile cu preț pentru mai mulți plătitori (OAuth 2.0)

Cazuri de utilizare comune:

  • Preluarea tranzacțiilor după interval de date
  • Filtrare după starea facturii (facturată, nefacturată etc.)
  • Căutare după numărul cardului (PAN) sau numărul de înmatriculare al vehiculului
  • Obțineți tranzacțiile de încărcare a vehiculelor electrice
  • Interogare tranzacții pentru mai mulți plătitori

Rezumatele tranzacțiilor

Punct de interfață Metodă Descriere
/transaction-data/v1/pricedtransactionssummary POST Obține date de sinteză privind tranzacțiile tarifate pentru Combustibil și NFR, incluzând articolele vândute și comisioanele (OAuth 2.0)
/transaction-data/v1/cardusagesummary POST Obține analiza cheltuielilor și rezumatul utilizării pentru un card (OAuth 2.0)

Returnează:

  • Date agregate privind tranzacțiile pe perioadă
  • Volumele și sumele totale
  • Defalcare pe tip de produs și categorie
  • Analiza cheltuielilor la nivel de card

Gestionarea comisioanelor

Punct final Metodă Descriere
/transaction-data/v1/feessummary POST Obține datele rezumative privind elementele de comision pentru plătitorul specificat (OAuth 2.0)

Informații privind comisioanele:

  • Preluarea elementelor de comision aplicate tranzacțiilor
  • Rezumatul tuturor comisioanelor pe perioadă
  • Detalierea comisioanelor pe tip și categorie
  • Analiza comisioanelor la nivel de plătitor

Reguli bazate pe volum

Punct de acces Metodă Descriere
/transaction-data/v1/volumebasedpricing POST Obține configurarea regulilor privind comisioanele de întârziere pentru plătitorul dat (OAuth 2.0)
/transaction-data/v1/volumebasedbonus POST Obține configurarea regulilor privind bonusurile și bonusurile de asociere pentru plătitorul dat (OAuth 2.0)

Funcționalități bazate pe volum:

  • Accesare reguli de tarifare bazate pe volum
  • Recuperează regulile de calcul al bonusului
  • Obțineți configurațiile bonusurilor de asociere

Excepții

Punct de capăt Metodă Descriere
/transaction-data/v1/exceptions POST Obține excepții legate de card sau tranzacție (OAuth 2.0)

Tipuri de excepții:

  • Eșecuri de validare a tranzacțiilor
  • Anomalii în utilizarea cardurilor
  • Excepții de autorizare

Cazuri de utilizare comune

Această secțiune corelează scenarii de afaceri comune cu punctele finale API corespunzătoare, pentru a vă ajuta să identificați rapid ce API-uri să utilizați pentru nevoile dvs. specifice.

Caz de utilizare 1: Reconcilierea zilnică a tranzacțiilor

Scenariu: Trebuie să reconciliați zilnic toate tranzacțiile efectuate cu cardurile flotei dvs. în scopuri contabile.

API recomandat: /transaction-data/v1/priced

De ce acest API: Acest punct de interfață oferă detalii complete despre tranzacții, inclusiv tranzacțiile de încărcare a vehiculelor electrice, acceptă filtrarea flexibilă după dată și include atât tranzacțiile facturate, cât și cele nefacturate. Este perfect pentru reconcilierea zilnică, cu suport pentru paginare în cazul seturilor mari de date.

Parametri cheie:

  • PostingDateFrom și PostingDateTo – Setați la data de ieri
  • InvoiceStatus – Utilizați „A” pentru toate tranzacțiile
  • PageSize - Setați la 100 pentru o recuperare eficientă a datelor

Caz de utilizare 2: Validarea și verificarea facturilor

Scenariu: Ați primit o factură și trebuie să verificați toate detaliile tranzacției, inclusiv comisioanele și taxele.

API recomandat: /transaction-data/v1/pricedtransaction

De ce acest API: Conceput special pentru a oferi informații detaliate despre tranzacțiile cu combustibil, inclusiv articolele vândute și toate comisioanele asociate. Ideal pentru validarea facturilor, deoarece se potrivește cu structura facturii.

Parametri cheie:

  • InvoiceNumber - Factura specifică de validat
  • Data facturii – Data facturii din sistemul dvs. de facturare
  • IncludeFees - Setați la „true” pentru a vedea toate elementele de taxă

Caz de utilizare 3: Analiza și raportarea consumului de combustibil

Scenariu: Trebuie să analizați modelele de consum de combustibil ale flotei dvs. din ultima lună pentru a optimiza rutele și a reduce costurile.

API-uri recomandate:

  • /transaction-data/v1/pricedtransactionssummary - Pentru date agregate

De ce aceste API-uri: Punctele finale de tip „rezumat” furnizează date agregate pe produs, grup de locații și perioadă de timp, fiind ideale pentru analiza tendințelor fără a fi necesară procesarea unor volume mari de tranzacții.

Parametri cheie:

  • PostingDateFrom și PostingDateTo - Setează la ultimele 30 de zile
  • ProductCode – Filtrează după tipuri specifice de combustibil
  • ProductGroupName - Grupare după categorii de combustibil

Caz de utilizare 4: Gestionarea mai multor flote

Scenariu: Gestionați mai multe subconturi sau plătitori și trebuie să extrageți datele tranzacțiilor de la toți aceștia pentru raportare consolidată.

API recomandat: /transaction-data/v1/multipayerspricedtransactions

De ce acest API: Conceput special pentru a interoga tranzacțiile de la mai mulți plătitori printr-un singur apel API, reducând semnificativ numărul de solicitări și îmbunătățind performanța în scenarii cu flote multiple.

Parametri cheie:

  • Conturi - Matrice de ID-uri și numere ale plătitorilor (maxim 10 plătitori)
  • InvoiceStatus - „A” pentru toate tranzacțiile
  • PostingDateFrom și PostingDateTo - Perioada de raportare

Caz de utilizare 5: Monitorizarea excepțiilor și detectarea fraudelor

Scenariu: Doriți să identificați tipare de tranzacții neobișnuite, cum ar fi tranzacții cu valoare mare, volume excesive de combustibil sau carduri cu utilizare anormală, pentru a preveni frauda sau utilizarea abuzivă.

API recomandat: /transaction-data/v1/exceptions

De ce acest API: Creat special pentru identificarea tranzacțiilor care depășesc pragurile definite, fiind astfel ideal pentru monitorizarea excepțiilor și a potențialelor fraude.

Parametri cheie:

  • Condiție - Setați tipul pragului (ValueGreaterThan, VolumeGreaterThan etc.)
  • Valoare - Definiți pragul
  • Tipul de ieșire - „Tranzacție” pentru excepțiile de tranzacție
  • TransactionsFromDate și TransactionsToDate - Perioada de monitorizare

Caz de utilizare 6: Analiza comisioanelor și taxelor

Scenariu: Trebuie să înțelegeți toate comisioanele și taxele aplicate contului dvs. pentru a identifica oportunități de reducere a costurilor sau pentru a valida facturarea.

API recomandat: /transaction-data/v1/feessummary

De ce acest API: Oferă informații agregate privind comisioanele în funcție de tipul de comision, grupul de produse și grupul de comisioane, facilitând analiza structurilor de comisioane și identificarea domeniilor cu costuri ridicate.

Parametri cheie:

  • InvoiceStatus - „I” numai pentru comisioanele facturate
  • FeeTypeGroup – Filtrare după „Taxe de card”, „Comisioane de cont” etc.
  • PostingDateFrom și PostingDateTo – Perioada de analiză

Caz de utilizare 7: Urmărirea cheltuielilor individuale pe card

Scenariu: Un șofer solicită istoricul tranzacțiilor sale din ultimele 6 luni sau trebuie să analizați modelele de cheltuieli pentru un anumit card.

API recomandat: /transaction-data/v1/cardusagesummary

De ce acest API: Oferă o analiză detaliată a cheltuielilor pentru fiecare card în parte din ultimele 7 luni, grupate pe locație și produs, fiind ideal pentru raportarea la nivel de card.

Parametri cheie:

  • CardId sau PAN – Cardul specific care urmează să fie analizat
  • CardExpiry – Pentru validare suplimentară
  • AccountId - Filtru opțional pentru cont

Caz de utilizare 8: Verificarea eligibilității pentru tarifarea bazată pe volum

Scenariu: Doriți să verificați dacă contul dvs. se califică pentru și să înțelegeți nivelurile actuale de consum în raport cu pragurile definite.

API recomandat: /transaction-data/v1/volumebasedpricing

De ce acest API: Afișează regulile privind comisioanele de întârziere, configurațiile nivelurilor de tarifare, precum și consumul actual de volum, ajutându-vă să înțelegeți structurile de tarifare și să vă planificați atingerea unor niveluri mai bune.

Parametri cheie:

  • PayerNumber - Contul dvs. de plătitor
  • IncludeHistory - Setați la „true” pentru a vedea calculele istorice
  • IncludeCurrentPeriodVolume - Setați la „true” pentru defalcare lunară

Caz de utilizare 9: Urmărirea bonusurilor și a rabatelor

Scenariu: Aveți acorduri de bonusuri bazate pe volum și doriți să urmăriți progresul către pragurile de bonus și să vizualizați bonusurile câștigate anterior.

API recomandat: /transaction-data/v1/volumebasedbonus

De ce acest API: Oferă detalii complete despre regulile privind bonusurile, consumul din perioada curentă și calculele istorice ale bonusurilor, permițându-vă să optimizați achizițiile pentru a maximiza bonusurile.

Parametri cheie:

  • PayerNumber - Contul dvs. de plătitor
  • IncludeHistory – Setați la „true” pentru a vedea plățile de bonusuri anterioare
  • IncludeCurrentPeriodVolume - Setați la „true” pentru a urmări progresul din perioada curentă

Exemple de utilizare

Exemplul 1: Obțineți tranzacțiile cu preț (inclusiv EV)

Solicitare:

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

Răspuns:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountName": "Blue Colour Ltd",
 "AccountId": 29484,
 "AccountNumber": "DE26667080",
 "AccountShortName": "Mathew",
 "Additional1": "GBALLEGO0002452",
 "Additional2": "GBALLEGO0002452",
      "Informații suplimentare 3": "GBALLEGO0002452",
 "Informații suplimentare 4": "GBALLEGO0002452",
 "Permite compensare": "Null",
 „AuthorisationCode”: 300796,
 „TransactionStatus”: „Y”,
 „DriverName”: „SATTY BHAMRA”,
 „CardExpiryPeriod”: 2204,
      "DataExpirareCard": "20220101",
 "IDGrupCard": 40000,
 "DenumireGrupCard": "006240 FIRE BRIGHT SOLUTIONS",
 "CodEmitent": 7002,
 "PANCardPAN”: „7002053465789891000”,
 „ReleaseCode”: 9,
 „CardSequenceNumber”: 617,
 „CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0,0051,
 "ColCoExchangeRate": 0,851858,
 "Simbolul monedei facturii": "GBP",
 "Indicator de corecție": true,
 "Număr CRM": 10,
      "CustomerCountry": "Regatul Unit",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
 "RebateonNetAmountInCustomerCurrency": 0,
      "Reducere efectivă în moneda clientului": -0,22,
 "Reducere unitară efectivă în moneda clientului": -0,0051,
 "Preț unitar în moneda facturii": 1,1024,
 "Taxă factură": 0,
      "Suma brută a facturii": 57,25,
 "Suma netă a facturii": 47,71,
 "TVA aplicat asupra sumei nete în moneda clientului": 9,54,
 „Prețul de vânzare cu amănuntul unitar brut al clientului”: 0,
 „Valoarea totală brută de vânzare cu amănuntul a clientului”: 57,52,
 „Valoarea totală netă de vânzare cu amănuntul a clientului”: 47,93,
      "Descriere tip tranzacție": 9,59,
 "Reducere asupra sumei nete în moneda tranzacției": -0,22,
 "Reducere efectivă în moneda tranzacției": -0,22,
 „Curs de schimb între moneda de livrare și moneda de destinație”: 0,
 „Carduri”: [
 275549
 ],
 „ReducereUnitară în MonedaTranzacției”: -0,005,
 „SumaBrutăaTranzacției”: 57,25,
 „SumaNetăaTranzacției”: 47,71,
      "Taxă tranzacție": 9,54,
 "TVA pe suma netă": 9,54,
      "PrețUnitarDelcoNet": 0,
 "PrețUnitarDelcoBrut": 1,32888,
 "PrețUnitarÎnMonedaTranzacției": 1,1074,
      "PrețUnitarVânzareCuAmănuntulDelcoNet": 1,1074,
 "ValoareTotalăVânzareCuAmănuntulDelcoBrut": 57,52,
      "ValoareaTotalăNetăDelco": 47,93,
 "SimbolMonedăTranzacție": "$",
 "TipReducere": 1,
 "StareLitigiu": fals,
      "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
 "IncomingProductCode": 23,
 "PostingDate": "20210802",
      „Ora publicării”: „14:15:22”,
 „Codul produsului”: 30,
 „Denumirea produsului”: „Fără plumb – octan mediu”,
 „ID-ul grupului de produse”: 22,
 „Codul monedei de intrare”: „GBP”,
      "Descriere stație de intrare": "Shell Broadway Ring",
 "Locație": "Shell Broadway Ring",
 "Numele stației": "Shell Broadway Ring",
 "Cod stație": 32,
 "Număr stație de intrare": 15,
 "Cod monedă factură": "GBP”,
 „Data facturii”: „20210802”,
 „Număr factură”: 3201016193,
      "FuelProduct": true,
 "VATApplicable": "Y",
 "PayerName": "Colours Services Ltd",
 "PayerNumber": "GB12121212",
      "ParentCustomerNumber": "GB12121212",
 "PayerGroup": "H312066",
 "PayerGroupName": "12162566 - FUEL CARD SERVICE",
 "CheckDigit": 6,
      "Indicator factură netă": "Y",
 "Cod Delco": 5,
 "Cod rețea": 3,
 "Țară de achiziție": "Regatul Unit",
 "Țara locației": "Regatul Unit",
      "VATCountry": "Regatul Unit",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
      "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Taxe",
 "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 sau C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
      "VATCategory": "Cota standard de TVA din Regatul Unit",
 "VATRate": 0,2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
      "SumaBrutăColCo": 57,25,
 "SumaNetăColCo": 47,71,
 "SumaTVA ColCo": 9,54,
 "SimbolMonedăOriginală": "$",
      "Codul monedei originale": "$",
 "Suma TVA originală": 0,
 "Textul imprimat": "PARKLANE PROPERTIES LTD",
 "Cursul de schimb original": 0,
 "Data facturii elementului de tranzacție originală": "20220202",
 "FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "Taxă simplă",
 "Frequency": 1,
 "FeeRuleId": 1,
 "Data introducerii în sistem": "20210828",
 "Ora introducerii în sistem": "20:21:08",
 "Este manuală": "Y",
 "ID-ul elementului tranzacției originale": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
 "OriginalTransactionItemInvoiceId": 234,
 "PayerShortName": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "OriginalGrossAmount": 57,25,
 "OriginalNetAmount": 57,25,
 "UnitOfMeasure": "L",
      "RoadType": "Drum național",
 "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
}

Exemplul 2: Obținerea detaliilor tranzacției de combustibil

Solicitare:

POST /transaction-data/v1/pricedtransaction

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

Răspuns:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
 "Type": "SalesItem /FeeItem",
          "CardId": 0,
 "CardPAN": "7002051006629891000",
          "CardExpiry": "2026-06-16",
 "TransactionDate": "2026-06-16",
 "TransactionTime": "string",
 "UTCOffset”: „string”,
 „FleetIdInput”: „XYZ1234”,
 „OdometerInput”: 12345,
 „DriverName”: „ANDREW GILBERRY”,
 „VehicleRegistration”: „MV65YLH”,
 „InvoiceCurrencyCode”: „GBP”,
 „InvoiceCurrencySymbol”: „$”,
 „TransactionCurrencyCode”: „GBP”,
          "Simbolul monedei tranzacției": "$",
 "Suma netă a tranzacției": 0,
 "Taxa tranzacției": 0,
 "Suma brută a tranzacției": 0,
 "Suma netă a facturii": 0,
          "Taxa factură": 0,
 "Suma brută factură": 0,
 "Țara de achiziție": "Germania",
 "ID cont": 29484,
          "NumărCont": "GB99215176",
 "NumeleContului": "MATTHEW ALGIE & COMPANY LIMITED",
 "DenumireScurtăCont": "string",
          "Cantitate": 0,
 "ProdusCombustibil": true,
 "PrețUnitarÎnMonedaTranzacției": 0,
 "PrețUnitarÎnMonedaFacturii": 0,
 "ReducereUnitarăÎnMonedaTranzacției": 0,
          "ReducereUnitarăÎnMonedaFacturii": 0,
 "EsteFacturat": true,
 "NumărFactură": "S04500493",
 "DataFacturii": "string",
 "CodLocație": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Numele locației": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 „Țara locației”: „Germania”,
 „Locație”: {
 „Latitudine”: „37.4224764”,
 „Longitudine”: „122.0842499”
          },
 „CardGroupName”: „006240 FIRE BRIGHT SOLUTIONS”,
 „ReceiptNumber”: „1234”,
 „ProductCode”: „10 - TMF Charges”,
          "ProductName": "Fără plumb - Octanaj ridicat",
 "ProductGroupId": 1,
          "ProductGroupName": "Grup de produse părinte",
 "DelCoExchangeRate": 0,
 "ColCoExchangeRate": 0,
 "IsShellSite": true,
          "Rețea": "100013\tSTEINDORFER",
 "IdGrupStații": 202,
 "NumGrupStații": "CZ 9100 ECONOMY NETWORK",
          "PostingDate": "string",
 "IssuerCode": "7002",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
          "CountryClient": "Olanda",
 "CodVersiune": "8",
 "IDGrupCarduri": "șir",
          "CardSequenceNumber": "2",
 "CheckDigit": "string",
 "FleetIDDescription": "string",
 "VATRate": "0,20 pentru 20%",
 "VATCategory": "1-Cota zero",
          "VATonNetAmount": 0,
 "VATCountry": "Olanda",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Achiziție cu cardul prezent, altfel lăsat necompletat",
 "PINIndicator": "„PIN utilizat”",
 „VATApplicable”: „Y”,
 „NetInvoiceIndicator”: „Y”,
 „CustomerCurrencyCode”: „GBP”,
 „CustomerCurrencySymbol”: „£”,
 „ReducereUnitarăEfectivăÎnMonedaClientului": 0,
 "ReducereEfectivăÎnMonedaClientului": 0,
 "TVA pe SumaNetăÎnMonedaClientului": 0,
 "TipReducere": "2 pence pe unitate",
          "Starea tranzacției": "U",
 "ID articol de vânzare": 18315958002,
 "Grup plătitor": "șir de caractere",
 "Denumire grup plătitor": "12119008 - SHELL GROUP OF COMPANIES",
 "RefundFlag": "string",
 "OriginalSalesItemId": "string",
 "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
          "DelcoCode": "14",
 "PayerNumber": "NL10042616",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
 "AuthorisationCode": "1011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
 "CRMNumber": "string",
          "StareContestare": "Fără contestare",
 "RatăRambursare": 28,279,
 "CursDeSchimbDelCoToColCo": 1,
 "SumaNetaÎnEuro": 0,
 "SumaTVAÎnEuro": 0,
          "ParentCustomerNumber": "șir de caractere",
 "ParentCustomerName": "șir de caractere",
 "ParentCustomerId": 0,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
 "IncomingCurrencyCode": "GBP",
 "IncomingProductCode": "30",
 "CreditDebitCode": "D",
          "IndicatorCorecție": "Y",
 "Suplimentar1": "șir de caractere",
 "Suplimentar2": „șir de caractere”,
 „Informație suplimentară 3”: „șir de caractere”,
 „Informație suplimentară 4”: „șir de caractere”,
 „Reducere asupra sumei nete în moneda clientului”: -0,735,
 „Reducere asupra sumei nete în moneda tranzacției”: "AVEE PTUAZONW CUBFAO COSFS",
 "IdentificatorTranzacție": "șir de caractere",
 "TipCard": "șir de caractere",
 „Unitate de preț de listă Delco netă”: 30,5,
 „Unitate de preț de vânzare cu amănuntul Delco netă”: 1,921,
 „Unitate de preț de vânzare cu amănuntul Delco brută”: 0,
 „Valoare totală de vânzare cu amănuntul Delco netă”: 0,
 „DelcoValoareTotalăCuValoareBrută": 0,
 "UnitatePrețVânzareCuAmănuntulClientBrută": 0,
 "ValoareTotalăVânzareCuAmănuntulClientNetă": 0,
 "NumărImprimatEV": „3792”,
 „IsRFID”: true,
 „TokenTypeDescription”: „string”
        }
 ]
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 15
}

Exemplul 3: Obținerea rezumatului tranzacțiilor cu preț

Solicitare:

POST /transaction-data/v1/pricedtransactionssummary

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

Răspuns:

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

Exemplul 4: Obținerea rezumatului prețurilor

Solicitare:

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

Răspuns:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114,13,
 "CustomerRetailValueTotalNet": 95,11,
            "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
            "ProductCode": "21",
 "ProductGroupId": 3,
 "ProductGroupName": "Benzină pentru autovehicule",
 "ProductId": 21,
 "ProductName": "Fără plumb – Octanaj ridicat",
 "SiteGroupId": 104,
            "NumeleGrupuluiDeStații": "Stații Shell implicite din Austria",
 "CantitateaTotalăDeCombustibil": 17,0,
 "SumaTotalăBrută": 114,13,
 "TotalNetAmount": 95,11
 }
    ]
}

Exemplul 5: Obținerea tranzacțiilor cu prețuri pentru mai mulți plătitori

Solicitare:

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
}

Răspuns:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
          "Type": "SalesItem"
 }
 ],
 "CardId": 275549,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
 "TransactionTime": "14:30:45",
 "UTCOffset": "+01:00:00",
 "FleetIdInput": "XYZ1234",
      "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "£",
 "SumaNetăTranzacție": 47,71,
 "TaxăTranzacție": 9,54,
 "SumaBrutăTranzacție": 57,25,
      "Suma netă factură": 47,71,
 "Taxă factură": 9,54,
 "Suma brută factură": 57,25,
 "Țara de achiziție": "Germania",
 "ID cont": 29484,
 "Număr cont": "GB99215176",
 "Numele contului": "MATTHEW ALGIE & COMPANY LIMITED",
      "Denumire scurtă cont": "MATTHEW",
 "Cantitate": 43,28,
 "Produs combustibil": true,
 "Preț unitar în moneda tranzacției": 1,1074,
      "PrețUnitarÎnMonedaFacturii": 1,1024,
 "ReducereUnitarăÎnMonedaTranzacției": -0,005,
 "ReducereUnitarăÎnMonedaFacturii": -0,0051,
 "EsteFacturat": true,
      "InvoiceNumber": "S04500493",
 "InvoiceDate": "20250815 09:30:00",
 "SiteCode": "050001",
      "SiteName": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "Germania",
 "Location": {
        "Latitudine": "53.83606",
 "Longitudine": "-1.61854"
 },
 "NumeleGrupuluiDeCarduri": "006240 FIRE BRIGHT SOLUTIONS",
 "NumărChitanță": "6803",
 "ProductCode": "10",
 "ProductName": "Fără plumb – Cifra octanică ridicată",
      "ProductGroupId": 2,
 "ProductGroupName": "Toate combustibilii",
 "DelCoExchangeRate": 0,851858,
 "ColCoExchangeRate": 0,851858,
 „IsShellSite”: true,
 „Network”: „SHELL”,
 „SiteGroupId”: 202,
      "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20250812 14:30:45",
 "IssuerCode": "7002",
      "PurchasedInCountryCode": "DE",
 "CustomerCountryCode": "NL",
 "CustomerCountry": „Olanda”,
 „ReleaseCode”: „8”,
 „CardGroupId”: „40000”,
 „CardSequenceNumber”: „617”,
 „CheckDigit”: „6”,
      "DescriereIDflotă": "YG67OUM",
 "RatăTVA": 0,2,
      "CategorieTVA": "1-Cotă standard",
 "TVA pe suma netă": 9,54,
 "Țara TVA": "Olanda",
 "Reducere efectivă în moneda tranzacției": -0,22,
 "Tipul tranzacției": "Achiziție",
 "IndicatorPIN": "PIN utilizat",
 "TVA aplicabil": "Da",
 "Indicatorfacturănetă": "N",
 "Codul monedei clientului": "GBP",
 "Simbolul monedei clientului": "£",
 "Reducere unitară efectivă în moneda clientului": -0,0051,
      "Reducere efectivă în moneda clientului": -0,22,
 "TVA pe suma netă în moneda clientului": 9,54,
 „TipulReducerii”: „2 pence pe unitate”,
 „StareaTranzacției”: „I”,
 „ID-ulArticoluluiVândut”: 18315958002,
 „GrupulPlătitorului": "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",
      "Număr CRM": null,
 "Stare contestație": "Fără contestație",
 "Rată reducere": 28,279,
 "Curs de schimb DelCoToColCo": 1,
      "Suma netă în euro": 56,01,
 "Suma TVA în euro": 11,2,
 "Număr client principal": "GB12121212",
 "Numele clientului principal": "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,
 "Reducere pe suma netă în moneda clientului": -0,735,
 "Reducere pe suma netă în moneda tranzacției": -0,735,
      "IdentificatorTranzacție": "H305908971030",
      "TipCard": "GB STD FLT NAT SINGLE R9",
 "UnitatePrețListăDelcoNet": 30,5,
 "UnitatePrețVânzareCuAmănuntulDelcoNet": 1,1074,
      "Unitatea de preț cu amănuntul Delco brută": 1,32888,
 "Valoarea totală cu amănuntul Delco netă": 47,93,
 "Valoarea totală cu amănuntul Delco brută": 57,52,
 "Unitatea de preț cu amănuntul pentru client brută": 1,32888,
 „CustomerRetailValueTotalNet”: 47,93,
 „EVPrintedNumber”: „3792”,
 „IsRFID”: true,
 „TokenTypeDescription”: „Fleet Card”
    }
  ],
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 15,
  "TotalRecords": 300
}

Exemplul 6: Obținerea regulilor de stabilire a prețurilor în funcție de volum

Solicitare:

POST /transaction-data/v1/volumebasedpricing

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

Răspuns:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Date": [
    {
 "Configurare": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
          "PricingAccountShortName": "ABCD1234",
 "PricingAccountFullName": "ABCD1234",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
          "FeeRuleDateEffective": "20231223",
 "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Plată către plătitor",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
          "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Săptămânal – Luni",
          "DataUrmătoareDeCalcul": "20231223",
 "DataAnterioarăDeCalcul": "20231223",
          "Baza regulii de comision": "3-sumă forfetară",
 "Codul monedei regulii de comision": "GBP",
 "Simbolul monedei regulii de comision": "£",
          "Data de începere a regulii de taxare": "20231223",
 "Data de încheiere a regulii de taxare": "20231223",
 "Locații ale regulii de taxare": [
 {
              "DelcoId": 866,
 "Country": "Regatul Unit",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
              "NumeleStației": "VALERO ENERGY LTD"
            }
 ],
 „FeeRuleProducts”: [
 {
 „ProductGroupID”: 3,
 „ProductGroupName”: „Benzină pentru autovehicule”,
 „ProductCode”: „30 pentru motorină AGO”,
              "ProductId": "30 pentru motorină AGO",
 "ProductName": "Motorină AGO"
 }
 ],
          "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234.12
 }
 ]
 }
 ],
 „CurrentPeriodConsumption”: [
 {
          "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "PriceRuleID": 100005,
          "PriceRuleDescription": "PL/GAGO/GMOT/UL0.055",
 "TotalVolume": 10000,78,
 "NextFeeCreationDate": "20231223"
 }
 ],
      "Istoric": [
 {
 "Data de început": "20231223",
          "ToDate": "20231223",
 "FeesRuleID": 8081,
 "FeesRuleDescription": "PT/P067/D120/P4.0",
          "TotalVolume": 12356,66
 }
 ],
 "Warnings": [
 {
 "Message": "Sistemul este indisponibil din cauza unei actualizări.",
 "Type": "Întrerupere a sistemului"
 }
 ]
    }
  ]
}

Exemplul 7: Obținerea regulilor privind bonusurile bazate pe volum

Solicitare:

POST /transaction-data/v1/volumebasedbonus

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

Răspuns:

{
  "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-Plată către plătitor”,
 „BonusPaidToAccountId”: 123456,
 „BonusPaidToAccountNumber”: „GB000000123”,
          "Denumire scurtă cont beneficiar bonus": "12345",
 "Denumire completă cont beneficiar bonus": "GB000000123",
 "Frecvență": "3-Săptămânal – luni”,
 „NextCalculationDate”: „20231223”,
 „PreviousCalculatedDate”: "20231223",
 "FeeRuleBasis": "3-sumă forfetară",
 "FeeRuleCurrencyCode": "GBP",
 "FeeRuleCurrencySymbol": "£",
 "FeeRuleAvailableFrom": "20231223",
 "FeeRuleAvailableTo": "20231223",
 "FeeRuleLocations": [
 {
              "DelcoId": 866,
 "Country": "Regatul Unit",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 „SiteGroupName”: „VALERO ENERGY LTD”,
 „SiteCode”: 999493,
 „SiteId”: 100007,
 „SiteName”: „VALERO ENERGY LTD”
            }
 ],
 „FeeRuleProducts”: [
 {
 „ProductGroupID”: 3,
 „ProductGroupName”: „Benzină pentru autovehicule”,
 „ProductCode”: „30 pentru motorină AGO”,
              "ProductId": "30 pentru motorină AGO",
 "ProductName": "Motorină AGO"
 }
 ],
 "FeeRuleTiers": [
            {
 „TierMinimum”: 1234,
 „TierMaximum”: 1234,
 „Value”: 1234,12
 }
 ],
 „AssociatedAccounts”: [
 {
              "ID-ul contului asociat": 12345,
 "Numărul contului asociat": "GB000000123",
 "Denumirea scurtă a contului asociat": "Denumirea scurtă a contului",
 "Denumirea completă a contului asociat": "Denumirea completă a contului"
 }
          ]
 }
 ],
 „CurrentPeriodConsumption”: [
 {
 „FeeRuleId”: 12345,
 „FeeRuleDescription”: „NL/GAGO/D018/UP0.0120>1”,
 „Luna”: 1,
 „Anul”: 2018,
 „TotalVolume”: 10000,78
 }
 ],
 „HistoricalBonusPaid”: [
 {
 „PayerId”: 12345,
 „PayerNumber”: „GB000000123",
 "PayerShortName": "Jorden",
 "PayerFullName": "MATTHEW",
 "AccountId": 123456,
 "AccountNumber": "GB000000123",
          "NumeleScurtCont": "SALT",
 "NumeleCompletCont": "ABCD1234",
 "IDContFactură": 12345,
 "NumărContFactură": "GB000000123",
 „InvoiceAccountShortName”: „DFE1234”,
 „InvoiceAccountFullName”: „AZAD PVT LMT”,
 „FeeRuleId”: 12345,
 „FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FromDate": "20231223",
 „ToDate”: „20231223”,
 „BonusPaidTo”: „5-Plată către clienții asociați”,
 „FeeItemId”: 12345,
 „FeeRuleBasis”: „2-Procent din creștere”,
          "FeeItemCurrencyCode": "GBP",
 "FeeItemCurrencySymbol": "$",
 "ProratedVolume": 123,12,
 „TotalVolume”: 123,12,
 „FeeProduct”: „1562-Bonus motorină Shell”,
 „InvoiceGrossAmount”: 123,12,
 „InvoiceNetAmount”: 123,12,
 „InvoiceVATAmount”: 123,12,
 „IsFeeCancelled”: true,
          "Volumul proporțional al nivelului de taxă": 123,12,
 "Volumul total al nivelului de taxă": 123,12,
 "Minim nivel": 123,
          "RataNivelului": 123,12
 }
 ]
    }
  ],
  "Avertismente": [
    {
 "Mesaj": "Sistemul este indisponibil din cauza unei actualizări.",
 "Tip": "Întrerupere a sistemului"
    }
  ]
}

Exemplul 8: Obținerea rezumatului comisioanelor

Solicitare:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Comisioane de card"
}

Răspuns:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "FeeTypeGroup": "Comisioane de card",
 "FeeTypeId": 1,
      "FeeType": "Taxă anuală de card",
 "ProductId": 1234,
 "ProductCode": "FEE",
 "ProductName": "Taxă de card",
 "TotalFeeAmount": 125,00,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

Exemplul 9: Obținerea excepțiilor de tranzacție

Solicitare:

POST /transaction-data/v1/exceptions

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

Răspuns:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "CardsExceptions": [
 {
 "AccountId": 29484,
 "CardId": 1234,
 "PAN": "ABCD1234",
          "DriverName": "ANDREW GILBERRY",
 "VRN": "34235",
 "PayerId": 123455,
 "PayerNumber": "GB000000123",
          "AccountNumber": "GB99215176",
 "AccountShortName": "MATTHEW",
 "PayerShortName": "MATTHEW",
 "Day": 2,
 "Week": 2,
          "Lună": 5,
 "An": 2017,
 "TotalTranzacții": 4,
 "TotalArticoleVândute": 4,
 "CantitateTotală": 261,
 "SumaTotală": 100,21,
 "CodMonedă": "GBP",
 "SimbolMonedă": "$"
        }
 ],
 „Excepții tranzacții”: [
 {
 „ID articol vândut”: 18315958002,
 „ID card”: 1234,
 „ProductId”: 2,
 „TransactionGUID”: „ABCD1234”,
 „TransactionDate”: „20231223”,
 „CustomerInvoiceValueTotalGross”: 123,12,
          "CardPAN": "7002051006629891000",
 "CardExpiry": "20311223 12:12:12",
 "TransactionTime": "12:12:12",
 „UTCOffset”: „+12:12:12”,
 „FleetIdInput”: „XYZ1234”,
          "OdometerInput": 1234,
 "DriverName": "SALT",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": „GBP”,
 „InvoiceCurrencySymbol”: „$”,
 „TransactionCurrencyCode”: „GBP”,
          "Simbolul monedei tranzacției": "£",
 "Suma netă a tranzacției": 123,12,
 "Taxa tranzacției": 123,12,
 "Suma brută a tranzacției": 123,12,
          "Suma netă a facturii": 123,12,
 "Taxa facturii": 123,12,
 "Suma brută a facturii": 123,1,
 "Țara de achiziție": "Franța",
 "ID cont": 1234,
 „NumărCont”: „GB99215176”,
 „NumeCont”: „MATTHEW ALGIE & COMPANY LIMITED”,
 „NumeScurtCont”: „MATTHEW ALGIE & COMPANY LIMITED”,
 „Quantity”: 123,12,
 „FuelProduct”: true,
 „UnitPriceInTransactionCurrency”: 123,12,
 „PrețUnitarÎnMonedaFacturii”: 123,12,
          "ReducereUnitarăMonedăTranzacție": 123,12,
 "ReducereUnitarăMonedăFactură": 123,12,
 "EsteFacturat": true,
 "NumărFactură": "S04500493",
 „InvoiceDate”: „20231223”,
 „SiteCode”: „50001”,
 „SiteName”: „CHARNOCK RICHARD NTHBOUND MWSA 0755”,
 „SiteCountry”: „Germania",
 "Locație": {
 "Lat": "37.4224764",
 "Lng": "122.0842499"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "1234",
 „ProductCode”: „TMF Charges”,
 „ProductName”: „Fără plumb – Cifra octanică ridicată”,
 „ProductGroupId”: 1234,
 „ProductGroupName”: „Grupul de produse părinte”,
 „DelCoExchangeRate”: 123,12,
 „ColCoExchangeRate”: 123,12,
 „IsShellSite”: true,
 „Network”: „Shell PH”,
 „SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20231223 12:12:12",
          "IssuerCode": "7077 = CRT",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
          "Țara clientului": "Olanda",
 "Cod de eliberare": "8 pentru 702188",
 "ID grup carduri": "200",
 "Număr de ordine card": "2",
 "Cifră de control": „GHE1234”,
 „FleetIDDescription”: „Exemplu de descriere”,
 „VATRate”: 0,2,
 „VATCategory”: „3 – scutit de TVA”,
 „VATonNetAmount”: 12,21,
          "VATCountry": "Olanda",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Achiziție cu cardul fizic prezent, altfel lăsat necompletat”,
 „PINIndicator”: „Y”,
 „VATApplicable”: „Y”,
 „NetInvoiceIndicator”: „Y”,
 „CustomerCurrencyCode”: „GBP”,
 „CustomerCurrencySymbol”: „£”,
 „EffectiveUnitDiscîn moneda clientului": 123,12,
 "Reducere efectivă în moneda clientului": 123,12,
          "TVA pe suma netă în moneda clientului": 123,12,
 "Tipul reducerii": "3-Procentaj",
          "Starea tranzacției": "U",
 "Grupul plătitorului": "12119008",
 "Indicator rambursare": "N",
          "ID-ul inițial al articolului de vânzare": "1231",
 "Numele distribuitorului": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "Codul distribuitorului": "NL10042616",
 „PayerName”: „V.M. LE COMTE”,
 „CardExpiryPeriod”: „1901”,
 „AuthorisationCode”: „11256”,
 „TransactionId”: „io9KVXk1UkW57XWKyeaHHg”,
 „TransactionLine”: „1”,
 „AllowClearing”: „Y”,
 „CRMNumber”: „ABCD1234”,
 „DisputeStatus”: "6\tRambursat către site",
 "Rata de rambursare": 28,279,
 "Curs de schimb DelCoToColCo": 1,
 "Suma netă în euro": 37,93,
 „EuroRebateAmount”: 0,
 „EuroVATAmount”: 7,96,
 „ParentCustomerNumber”: „DRG1234”
 }
 ]
    }
  ]
}

Exemplul 10: Obținerea rezumatului utilizării cardului

Solicitare:

POST /transaction-data/v1/cardusagesummary

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

Răspuns:

{
  "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": "Benzină pentru autovehicule"
 }
      ]
    }
  ]
}

Gestionarea erorilor

Coduri de eroare comune

Stare HTTP Cod de eroare Descriere Soluție
200 N/A Stare: SUCCES N/A
200 E0001 Eroare de validare Verificați parametrii cererii
401 E0003 Neautorizat Verificați dacă tokenul OAuth este valid
403 E0003 Acces interzis Verificați permisiunile utilizatorului
404 E0005 Resursă neidentificată Verificați dacă URL-ul punctului final și resursa există
500 E0002 Eroare necunoscută / Eroare internă a serverului Contactați serviciul de asistență

Cele mai bune practici

1. Adoptați autentificarea OAuth 2.0

IMPORTANT: Toți clienții ar trebui să migreze la autentificarea OAuth 2.0. Implementați o gestionare corespunzătoare a tokenurilor:

  • Stocați în cache tokenurile de acces și reutilizați-le până la expirare
  • Reîmprospătați tokenurile înainte de expirare (se recomandă cu 60 de secunde înainte)
  • Stocați datele de autentificare ale clientului în siguranță (utilizați variabile de mediu sau un manager de secrete)
  • Nu înregistrați și nu expuneți niciodată tokenurile de acces în codul de pe partea clientului

2. Utilizați ID-urile de solicitare

Includeți întotdeauna un RequestId unic (în format GUID) pentru trasabilitate de la un capăt la altul

3. Implementați paginarea

Pentru seturi mari de date de tranzacții, utilizați paginarea pentru a evita expirarea timpului de așteptare:

  • Setați o valoare adecvată pentru PageSize adecvat (recomandat: 50-100 de înregistrări)
  • Procesați paginile secvențial sau în paralel
  • Gestionați TotalPages și TotalRecords în răspunsuri

4. Utilizați filtrele de dată în mod judicios

Când interogați datele tranzacțiilor:

  • Limitați intervalele de date pentru a evita seturi mari de rezultate
  • Utilizați în mod consecvent filtrele FromDate și ToDate
  • Luați în considerare interogarea pe lună sau săptămână pentru o performanță mai bună

5. Testați în mediul Sandbox

Testați întotdeauna integrarea în mediul de testare/Sandbox înainte de a trece la producție

6. Stocați în cache datele de referință

Stocați în cache regulile de tarifare bazate pe volum și regulile privind bonusurile pentru a minimiza apelurile API:

  • Aceste reguli se modifică rar
  • Reîmprospătați memoria cache periodic (de exemplu, zilnic)
  • Utilizați parametrul IncludeHistory numai când este necesar

SDK și exemple de cod

Shell oferă SDK-uri oficiale și exemple de cod cuprinzătoare pentru a accelera integrarea dvs. cu API-ul de date tranzacționale.

Limbaje SDK disponibile

  • Python - SDK cu funcționalități complete și suport pentru OAuth 2.0
  • TypeScript - SDK cu siguranță de tip, cu definiții complete de tipuri
  • Java - SDK de nivel enterprise
  • C#/.NET - Integrare completă cu .NET
  • PHP - Bibliotecă PHP ușor de utilizat
  • Ruby - Gem Ruby pentru integrare perfectă

Vizualizați SDK-urile oficiale și documentația

Asistență și resurse

Asistență tehnică

Documentație

Obțineți ajutor

Când contactați serviciul de asistență, furnizați:

  1. ID-ul dvs. de client (nu divulgați niciodată secretul de client sau tokenurile de acces)
  2. RequestId din răspunsul API-ului
  3. Marca temporală a cererii
  4. Mediu (Producție/Testare)

Ultima actualizare: 1 iulie 2026
Versiunea documentului: 1.0
Versiunea API: 2.3.5

Despre noi

Portalul pentru dezvoltatori Shell sprijină partenerii în procesul de integrare cu API-urile Shell și în transformarea ideilor în soluții gata de punere în producție.

Logo Shell

Persoană de contact

Contactați-ne

Conectați-vă la contul dvs.

Întreabă Asistentul AI despre API-urile Shell și produsele API