Selezionare la lingua

Tradotto a macchina (Beta)

B2B Mobility Card Transaction Data 2.3.5

Ottenere aggiornamenti sullo stato, la manutenzione e la versione di questo API.

API dei dati delle transazioni della Shell B2B Mobility Card - Guida rapida

Versione API: 2.3.5 | Autenticazione: OAuth 2.0 | Stato: Produzione

Panoramica

L’API dei dati delle transazioni delle carte Shell è un’API basata su RESTche consente agli sviluppatori di recuperare e analizzare i dati delle transazioni delle carte carburante Shell in modo programmatico. L’API fornisce accesso alle transazioni con prezzo, alle commissioni, ai prezzi basati sul volume, alle regole sui bonus, alle eccezioni e ai riepiloghi sull’utilizzo delle carte.

Nota: Questa guida tratta esclusivamente gli endpoint autenticati tramite OAuth 2.0 (percorso di base: /transaction-data/v1). Gli endpoint legacy con autenticazione Basic (/fleetmanagement/v1/transaction) non sono inclusi in quanto in fase di dismissione.

Caratteristiche principali

  • Recupero dei dettagli delle transazioni con prezzo, comprese le transazioni EV
  • Accedere ai dettagli delle transazioni relative al carburante con le voci di vendita e le commissioni
  • Ottenere i dati di riepilogo delle transazioni relative a carburante e NFR
  • Interrogare ie le regole relative ai bonus
  • Recupera le voci relative alle commissioni e i dati di riepilogo delle commissioni
  • Accedere alle eccezioni relative alle carte e alle transazioni
  • Analisi dei dati relativi all’utilizzo della carta e alle spese
  • Supporto per le query sulle transazioni con più pagatori

ImportaAvviso - OAuth 2.0

IMPORTANTE: OAuth 2.0 è ora il metodo di autenticazione standard

  • Nuove integrazioni: Utilizza OAuth 2.0 sin dall’inizio
  • Integrazioni esistenti: Pianifica la migrazione a OAuth 2.0
  • Metodi legacy: L’autenticazione di base (Basic Auth) verrà gradualmente dismessa

Contatta il supporto tecnico di Shell per ottenere le tue credenziali OAuth 2.0 (client_id e client_secret).

Autenticazione

OAuth 2.0 (metodo di autenticazione standard)

L’API Shell Card Transaction Data utilizza il flusso delle credenziali client OAuth 2.0 per un’autenticazione sicura.

AVVISO: Tutti i clienti dovrebbero pianificare l’adozione dell’autenticazione OAuth 2.0. Questo è il metodo di autenticazione raccomandato e a prova di futuro per l’API dei dati delle transazioni con carta Shell. I metodi di autenticazione legacy vengono gradualmente eliminati.

Flusso OAuth 2.0

Passaggio 1: Ottenere il token di accesso

Richiedere un token di accesso dall’endpoint dei token OAuth:

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

grant_type=client_credentials&client_id=il-tuo-id-cliente&client_secret=il-tuo-segreto-cliente

Passaggio 2: Utilizzare il token di accesso nelle richieste API

Authorization: Bearer 
Content-Type: application/json

Gestione dei token

Migliori pratiche per la gestione dei token:

  • I token di accesso hanno una durata limitata (in genere 15 minuti)
  • Implementare la memorizzazione dei token nella cache per evitare richieste di token non necessarie
  • Aggiornare i token prima della scadenza per garantire un servizio ininterrotto
  • Non condividere mai il tuo client_secret né incorporarlo nel codice lato client

Strategia di adozione di OAuth 2.0

Perché migrare a OAuth 2.0?

Vantaggi in termini di sicurezza:

  • Protocollo di autenticazione standard del settore
  • I token di accesso a durata limitata riducono i rischi per la sicurezza
  • Nessuna credenziale trasmessa con ogni richiesta
  • Migliore supporto per la rotazione e la revoca dei token

Vantaggi operativi:

  • Maggiore scalabilità e prestazioni
  • Migliori funzionalità di monitoraggio e audit
  • Gestione semplificata delle credenziali
  • Integrazione a prova di futuro

Percorso di migrazione

Se attualmente utilizzi metodi di autenticazione legacy, segui questo percorso di migrazione:

  1. Richiedi le credenziali OAuth 2.0 al Supporto tecnico di Shell
  2. Implementa la gestione dei token OAuth nella tua applicazione
  3. Esegui test approfonditi nell’ambiente di test/sandbox
  4. Esegui l’autenticazione in parallelo (OAuth + legacy) durante la transizione
  5. Monitorare e convalidare l’integrazione OAuth
  6. Passare esclusivamente a OAuth una volta convalidata
  7. Disattivare l’autenticazione legacy dopo aver completato con successo la migrazione

Ambienti

L’API è disponibile in due ambienti:

Ambiente URL di base Scopo
Produzione https://api.shell.com Ambiente di produzione live
Test (Sandbox) https://api-test.shell.com/test Ambiente di test e sviluppo

Suggerimento: Verificate sempre l’integrazione nell’ambiente di test prima di passare alla produzione.

Guida rapida

1. Ottenete le vostre credenziali OAuth

2. Ottenere il token di accesso

Per prima cosa, ottenere il proprio token di accesso OAuth:

Esempio 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=il-tuo-id-client&client_secret=il-tuo-segreto-client"

Risposta:

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

3. Effettua la tua prima richiesta API

Esempio: recupera le transazioni con prezzo

Esempio con 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
}'

Risposta di esempio:

{
  "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,
 "ScadenzaCarta": "20220101",
 "IDGruppoCarta": 40000,
      "NomeGruppoCarta": "006240 FIRE BRIGHT SOLUTIONS",
 "CodiceEmittente": 7002,
 "PANCarta": "7002053465789891000",
 "CodiceRilascio": 9,
      "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
      "ValutaScontoUnitarioFattura": -0,0051,
 "TassoDiCambioColCo": 0,851858,
 "SimboloValutaFattura": "GBP",
 "FlagCorrezione": true,
 "NumeroCRM": 10,
 "Paese del cliente": "Regno Unito",
 "Codice valuta del cliente": "GBP",
 "Simbolo valuta del cliente": "£",
 "Sconto sull’importo netto nella valuta del cliente": 0,
      "Sconto effettivo nella valuta del cliente": -0,22,
 "Sconto unitario effettivo nella valuta del cliente": -0,0051,
 "Prezzo unitario nella valuta della fattura": 1,1024,
      "Imposta sulla fattura": 0,
 "Importo lordo della fattura": 57,25,
 "InvoiceNetAmount": 47,71,
 "VATonNetAmountInCustomerCurrency": 9,54,
 "CustomerRetailPriceUnitGross": 0,
      "Valore al dettaglio totale lordo del cliente": 57,52,
 "Valore al dettaglio totale netto del cliente": 47,93,
 "DescrizioneTipoTransazione": 9,59,
 "Sconto sull’importo netto nella valuta della transazione": -0,22,
 "Sconto effettivo nella valuta della transazione": -0,22,
      "Tasso di cambio da valuta di origine a valuta di destinazione": 0,
 "Carte": [
 275549
 ],
 "Sconto unitario in valuta della transazione": -0,005,
 "Importo lordo della transazione": 57,25,
      "Importo netto della transazione": 47,71,
 "Imposta sulla transazione": 9,54,
 "IVA sull'importo netto": 9,54,
 "Prezzo di listino Delco unitario netto": 0,
 "Prezzo al dettaglio Delco unitario lordo": 1,32888,
 "Prezzo unitario nella valuta della transazione": 1,1074,
 "PrezzoAlDettaglioDelcoAlNettoPerUnità": 1,1074,
 "ValoreTotaleAlDettaglioDelcoAlLordo": 57,52,
 "ValoreTotaleAlDettaglioDelcoAlNetto": 47,93,
      "TransactionCurrencySymbol": "$",
 "DiscountType": 1,
 "DisputeStatus": false,
 "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
      "CodiceProdottoIn entrata": 23,
 "DataRegistrazione": "20210802",
 "OraRegistrazione": "14:15:22",
 "CodiceProdotto": 30,
      "ProductName": "Senza piombo - Ottani medi",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
      "NomeStazione": "Shell Broadway Ring",
 "CodiceStazione": 32,
 "NumeroStazioneIn entrata": 15,
 "CodiceValutaFattura": "GBP",
 "DataFattura": "20210802",
 "NumeroFattura": 3201016193,
 "ProdottoCarburante": true,
 "IVAApplicabile": "S",
 "NomePagatore": "Colours Services Ltd",
 "NumeroPagatore": "GB12121212",
 "NumeroClientePrincipale": "GB12121212",
 "Gruppo pagatore": "H312066",
 "Nome gruppo pagatore": "12162566 - SERVIZIO CARTA CARBURANTE",
 "CheckDigit": 6,
 "NetInvoiceIndicator": "Y",
 "DelcoCode": 5,
 "NetworkCode": 3,
 "PurchasedInCountry": "Regno Unito",
      "Paese della Stazione di Servizio": "Regno Unito",
 "Paese IVA": "Regno Unito",
 "Nome Delco": "Shell U.K. Oil Products Limited",
 "Rete": "Shell",
      "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Commissioni",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
      "TassoSconto": 0,0022,
 "NumeroScontrino": 6803,
 "IndicatoreRimborso": "Y",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 53.83606,
      "Longitudine": -1,61854,
 "Tasso di cambio DelCo": 0,851858,
 "Importo dello sconto in euro": -0,258259,
 "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
      "NomeClientePrincipale": "FUEL CARD SERVICES LTD",
 "ÈFatturato": false,
 "CodiceValutaTransazione": "GBP",
      "CreditDebitCode": "D o C",
 "TransactionDate": "20210801",
      "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "VENDITA",
 "RigaTransazione": 1,
 "TipoTransazione": "Acquisto",
 "UTCOffset": "Europe/London",
 "CategoriaIVA": "Aliquota IVA standard del Regno Unito",
 "AliquotaIVA": 0,2,
 "TargaVeicolo": "YG67OUM",
      "IsCancelled": "Y",
 "ColCoGrossAmount": 57,25,
 "ColCoNetAmount": 47,71,
 "ColCoVATAmount": 9,54,
 "OriginalCurrencySymbol": "$",
      "CodiceValutaOriginale": "$",
 "ImportoIVAOriginale": 0,
 "TestoIn rilievo": "PARKLANE PROPERTIES LTD",
 "TassoDiCambioOriginale": 0,
 "OriginalTransactionItemInvoiceDate": "20220202",
 "FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "Commissione semplice",
 "Frequenza": 1,
 "ID regola commissione": 1,
 "Data inserimento nel sistema": "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": "Strada nazionale",
 "CustomerCountryIsoCode": "DE",
 "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
 "EVChargePointConnectorType": 5,
 "DescrizioneTipoConnettorePuntoRicaricaEV": "CC 50 kW",
 "DurataRicaricaEV": "PT3205S",
 "DataInizioRicaricaEV": "2021-08-01",
 "OraInizioRicaricaEV": "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
}

Riferimento agli endpoint API

Transazioni a prezzo

Endpoint Metodo Descrizione
/transaction-data/v1/priced POST Recupera i dettagli delle transazioni a pagamento, comprese le transazioni EV (OAuth 2.0)
/transaction-data/v1/pricedtransaction POST Recupera i dettagli delle transazioni relative al carburante con le voci di vendita e le commissioni (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions POST Recupera i dettagli delle transazioni con prezzo per più pagatori (OAuth 2.0)

Casi d’uso comuni:

  • Recupera le transazioni per intervallo di date
  • Filtra per stato della fattura (Fatturato, Non fatturato, ecc.)
  • Cerca per PAN della carta o targa del veicolo
  • Recupera transazioni di ricarica veicoli elettrici
  • Interroga le transazioni relative a più pagatori

Riepiloghi delle transazioni

Endpoint Metodo Descrizione
/transaction-data/v1/pricedtransactionssummary POST Recupera i dati di riepilogo delle transazioni con prezzo per carburante e NFR con articoli venduti e commissioni (OAuth 2.0)
/transaction-data/v1/cardusagesummary POST Recupera l’analisi delle spese e il riepilogo di utilizzo per una carta (OAuth 2.0)

Restituisce:

  • Dati aggregati delle transazioni per periodo
  • Volumi e importi totali
  • Ripartizione per tipo di prodotto e categoria
  • Analisi delle spese a livello di carta

Gestione delle commissioni

Endpoint Metodo Descrizione
/transaction-data/v1/feessummary POST Recupera i dati di riepilogo delle voci di commissione per il pagatore specificato (OAuth 2.0)

Informazioni sulle commissioni:

  • Recupera le voci relative alle commissioni applicate alle transazioni
  • Riepilogo di tutte le commissioni per periodo
  • Ripartizione delle commissioni per tipo e categoria
  • Analisi delle commissioni a livello di pagatore

Regole basate sul volume

Fine Metodo Descrizione
/transaction-data/v1/volumebasedpricing POST Recupera la configurazione delle regole sulle commissioni di mora per il pagatore specificato (OAuth 2.0)
/transaction-data/v1/volumebasedbonus POST Recupera le impostazioni relative alle regole sui bonus e sui bonus di associazione per il pagatore specificato (OAuth 2.0)

Funzionalità basate sul volume:

  • Accedere alle regole di tariffazione basate sul volume
  • Recupera le regole di calcolo dei bonus
  • Ottieni le configurazioni dei bonus di associazione

Eccezioni

Endpoint Metodo Descrizione
/transaction-data/v1/exceptions POST Recupera le eccezioni relative alla carta o alla transazione (OAuth 2.0)

Tipi di eccezione:

  • Errori di convalida delle transazioni
  • Anomalie nell’utilizzo della carta
  • Eccezioni di autorizzazione

Casi d’uso

Questa sezione mette in relazione gli scenari aziendali più comuni con gli endpoint API appropriati per aiutarti a identificare rapidamente quali API utilizzare per le tue esigenze specifiche.

Caso d’uso 1: Riconciliazione giornaliera delle transazioni

Scenario: Devi riconciliare quotidianamente tutte le transazioni effettuate con le carte della tua flotta a fini contabili.

API consigliata: /transaction-data/v1/priced

Perché questa API: Questo endpoint fornisce dettagli completi sulle transazioni, comprese quelle relative alla ricarica dei veicoli elettrici, supporta un filtraggio flessibile per data e include sia le transazioni fatturate che quelle non fatturate. Perfetto per la riconciliazione giornaliera, con supporto alla paginazione per set di dati di grandi dimensioni.

Parametri chiave:

  • PostingDateFrom e PostingDateTo - Impostare sulla data di ieri
  • InvoiceStatus - Utilizzare "A" per tutte le transazioni
  • PageSize - Impostare su 100 per un recupero efficiente dei dati

Caso d’uso 2: Convalida e verifica delle fatture

Scenario: Hai ricevuto una fattura e devi verificare tutti i dettagli della transazione, comprese le commissioni e gli addebiti.

API consigliata: /transaction-data/v1/pricedtransaction

Perché questa API: Progettata specificatamente per fornire informazioni dettagliate sulle transazioni relative al carburante, inclusi gli articoli venduti e tutte le commissioni associate. Ideale per la convalida delle fatture poiché corrisponde alla struttura della fattura.

Parametri chiave:

  • InvoiceNumber - Numero specifico della fattura da convalidare
  • DataFattura - Data della fattura dalla vostra fatturazione
  • IncludeFees - Impostare su "true" per visualizzare tutte le voci relative alle commissioni

Caso d’uso 3: Analisi e reportistica sul consumo di carburante

Scenario: È necessario analizzare i modelli di consumo di carburante della propria flotta relativi all’ultimo mese per ottimizzare i percorsi e ridurre i costi.

API consigliate:

  • /transaction-data/v1/pricedtransactionssummary - Per i dati aggregati

Perché queste API: Gli endpoint di riepilogo forniscono dati aggregati per prodotto, gruppo di siti, e periodo di tempo, rendendoli perfetti per l’analisi delle tendenze senza dover elaborare grandi volumi di transazioni.

Parametri chiave:

  • PostingDateFrom e PostingDateTo - Impostati sugli ultimi 30 giorni
  • ProductCode - Filtra in base a tipi specifici di carburante
  • ProductGroupName - Raggruppa per categorie di carburante

Caso d’uso 4: Gestione di flotte multiple

Scenario: Gestisci più sotto-account o pagatori e devi recuperare i dati delle transazioni relativi a tutti loro per la reportistica consolidata.

API consigliata: /transaction-data/v1/multipayerspricedtransactions

Perché questa API: Progettata specificatamente per interrogare le transazioni relative a più pagatori con un’unica chiamata API, riducendo significativamente il numero di richieste e migliorando le prestazioni negli scenari con flotte multiple.

Parametri chiave:

  • Accounts - Array di ID e numeri dei pagatori (max 10 pagatori)
  • Stato della fattura - "A" per tutte le transazioni
  • PostingDateFrom e PostingDateTo - Periodo di rendicontazione

Caso d’uso 5: Monitoraggio delle eccezioni e rilevamento delle frodi

Scenario: Si desidera identificare modelli di transazione insoliti, quali transazioni di importo elevato, volumi eccessivi di carburante o carte con un utilizzo anomalo, al fine di prevenire frodi o abusi.

API consigliata: /transaction-data/v1/exceptions

Perché questa API: Progettata appositamente per identificare le transazioni che superano le soglie definite, rendendola ideale per il monitoraggio delle eccezioni e delle potenziali frodi.

Parametri chiave:

  • Condizione - Imposta il tipo di soglia (ValueGreaterThan, VolumeGreaterThan, ecc.)
  • Valore - Definire il valore di soglia
  • Tipo di output - "Transazione" per le eccezioni relative alle transazioni
  • TransactionsFromDate e TransactionsToDate - Periodo di monitoraggio

Caso d’uso 6: Analisi di commissioni e addebiti

Scenario: È necessario comprendere tutte le commissioni e gli addebiti applicati al proprio conto per individuare opportunità di risparmio o verificare la fatturazione.

API consigliata: /transaction-data/v1/feessummary

Perché questa API: Fornisce informazioni aggregate sulle commissioni per tipo di commissione, gruppo di prodotti e gruppo di commissioni, facilitando l’analisi delle strutture tariffarie e l’identificazione delle aree ad alto costo.

Parametri chiave:

  • InvoiceStatus - "I" solo per le commissioni fatturate
  • FeeTypeGroup - Filtra per "Addebiti su carta", "Addebiti sul conto", ecc.
  • PostingDateFrom e PostingDateTo - Periodo di analisi

Caso d’uso 7: Monitoraggio delle spese per singola carta

Scenario: Un autista richiede la cronologia delle transazioni degli ultimi 6 mesi, oppure è necessario analizzare i modelli di spesa relativi a una carta specifica.

API consigliata: /transaction-data/v1/cardusagesummary

Perché questa API: Fornisce un’analisi dettagliata delle spese relative a singole carte negli ultimi 7 mesi, raggruppate per sede e prodotto, ideale per la reportistica a livello di carta.

Parametri chiave:

  • CardId o PAN - Carta specifica da analizzare
  • CardExpiry - Per una convalida aggiuntiva
  • AccountId - Filtro opzionale per l’account

Caso d’uso 8: Verifica dell’idoneità alla tariffazione basata sul volume

Scenario: Si desidera verificare se il proprio account è idoneo ai e di comprendere i propri livelli di consumo attuali rispetto alle soglie definite.

API consigliata: /transaction-data/v1/volumebasedpricing

Perché questa API: Mostra le regole relative alle commissioni di mora, le configurazioni dei livelli tariffari e l’attuale consumo in volume, aiutandoti a comprendere le strutture tariffarie e a pianificare il raggiungimento di livelli migliori.

Parametri chiave:

  • PayerNumber - Il tuo account pagatore
  • IncludeHistory - Impostare su true per visualizzare i calcoli storici
  • IncludeCurrentPeriodVolume - Impostare su "true" per ottenere una ripartizione mese per mese

Caso d'uso 9: Monitoraggio di bonus e sconti

Scenario: Hai accordi sui bonus basati sul volume e desideri monitorare i tuoi progressi verso le soglie di bonus e visualizzare i bonus guadagnati in precedenza.

API consigliata: /transaction-data/v1/volumebasedbonus

Perché questa API: Forniscefornisce dettagli completi sulle regole dei bonus, sul consumo del periodo corrente e sui calcoli storici dei bonus, consentendoti di ottimizzare gli acquisti per massimizzare i bonus.

Parametri chiave:

  • PayerNumber - Il proprio conto pagatore
  • IncludeHistory - Impostare su true per visualizzare i pagamenti dei bonus passati
  • IncludeCurrentPeriodVolume - Impostare su "true" per monitorare l’andamento del periodo corrente

Esempi di utilizzo

Esempio 1: Recupera le transazioni con prezzo (incluso EV)

Richiesta:

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

Risposta:

{
  "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,
      "StatoTransazione": "Y",
 "NomeConducente": "SATTY BHAMRA",
 "PeriodoScadenzaCarta": 2204,
 "ScadenzaCarta": "20220101",
 "ID gruppo carta": 40000,
 "Nome gruppo carta": "006240 FIRE BRIGHT SOLUTIONS",
 "Codice emittente": 7002,
      "PAN della carta": "7002053465789891000",
      "ReleaseCode": 9,
 "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "ValutaScontoUnitarioFattura": -0,0051,
 "TassoDiCambioColCo": 0,851858,
 "SimboloValutaFattura": "GBP",
      "CorrectionFlag": true,
 "CRMNumber": 10,
      "Paese del cliente": "Regno Unito",
 "Codice valuta del cliente": "GBP",
 "Simbolo valuta del cliente": "£",
 "Sconto sull'importo netto nella valuta del cliente": 0,
      "Sconto effettivo nella valuta del cliente": -0,22,
 "Sconto unitario effettivo nella valuta del cliente": -0,0051,
 "Prezzo unitario nella valuta della fattura": 1,1024,
 "Imposta sulla fattura": 0,
 "Importo lordo della fattura": 57,25,
 "Importo netto della fattura": 47,71,
      "IVA sull’importo netto nella valuta del cliente": 9,54,
 "Prezzo al dettaglio unitario lordo del cliente": 0,
      "ValoreLordoTotaleAlDettaglioCliente": 57,52,
 "ValoreNettoTotaleAlDettaglioCliente": 47,93,
 "DescrizioneTipoTransazione": 9,59,
 "ScontoSull'importoNettoNellaValutaDellaTransazione": -0,22,
 "Sconto effettivo nella valuta della transazione": -0,22,
 "Tasso di cambio da valuta del paese di origine a valuta del paese di destinazione": 0,
 "Carte": [
 275549
 ],
 "Sconto unitario nella valuta della transazione": -0,005,
 "Importo lordo della transazione": 57,25,
 "Importo netto della transazione": 47,71,
 "Imposta sulla transazione": 9,54,
      "IVA sull’importo netto": 9,54,
 "Prezzo di listino Delco unitario netto": 0,
 "Prezzo al dettaglio Delco unitario lordo": 1,32888,
      "PrezzoUnitarioNellaValutaDellaTransazione": 1,1074,
 "PrezzoAlDettaglioDelcoUnitarioNetto": 1,1074,
      "ValoreLordoTotaleAlDettaglioDelco": 57,52,
 "ValoreNettoTotaleAlDettaglioDelco": 47,93,
 "SimboloValutaTransazione": "$",
 "TipoSconto": 1,
 "StatoControversia": false,
      "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
 "IncomingProductCode": 23,
 "Data di registrazione": "20210802",
 "Ora di registrazione": "14:15:22",
 "Codice prodotto": 30,
 "Nome prodotto": "Senza piombo - Ottani medi",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Ubicazione": "Shell Broadway Ring",
 "NomeStazione": "Shell Broadway Ring",
 "CodiceStazione": 32,
 "NumeroStazioneIn entrata": 15,
 "CodiceValutaFattura": "GBP",
 "DataFattura": "20210802",
 "NumeroFattura": 3201016193,
 "ProdottoCarburante": true,
 "IVAApplicabile": "Y",
 "NomePagatore": "Colours Services Ltd",
      "Numero del pagatore": "GB12121212",
 "Numero cliente principale": "GB12121212",
 "Gruppo pagatore": "H312066",
      "NomeGruppoPagatore": "12162566 - SERVIZIO CARTA CARBURANTE",
 "CifraDiControllo": 6,
 "IndicatoreFatturaNetta": "Y",
 "CodiceDelco": 5,
 "CodiceRete": 3,
 "Paese di acquisto": "Regno Unito",
 "Paese della sede": "Regno Unito",
 "Paese IVA": "Regno Unito",
 "Nome Delco": "Shell U.K. Oil Products Limited",
 "Rete": "Shell",
      "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Commissioni",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
 "RebateRate": 0,0022,
      "ReceiptNumber": 6803,
 "RefundFlag": "Y",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
      "Latitudine": 53,83606,
 "Longitudine": -1,61854,
 "Tasso di cambio DelCo": 0,851858,
 "EuroRebateAmount": -0,258259,
 "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
 "IsInvoiced": false,
 "TransactionCurrencyCode": "GBP",
 "CreditDebitCode": "D o C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
      "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
 "VATCategory": "Aliquota IVA standard del Regno Unito",
 "VATRate": 0,2,
      "VettoreImmatricolazione": "YG67OUM",
 "ÈAnnullato": "Y",
 "ImportoLordoColCo": 57,25,
 "ImportoNettoColCo": 47,71,
 "ColCoVATAmount": 9,54,
 "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
 "OriginalVATAmount": 0,
      "Testo impresso": "PARKLANE PROPERTIES LTD",
 "Tasso di cambio originale": 0,
 "Data fattura voce transazione originale": "20220202",
 "ID tipo commissione": 1,
 "Descrizione voce di transazione": true,
 "Descrizione regola commissione": "Commissione semplice",
 "Frequenza": 1,
 "ID regola commissione": 1,
 "Data inserimento nel sistema": "20210828",
 "Ora inserimento nel sistema": "20:21:08",
 "È manuale": "Y",
 "OriginalTransactionItemId": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
 "OriginalTransactionItemInvoiceId": 234,
 "PayerShortName": "FUEL CARD SERVICES LTD",
      "ReverseCharge": "Y",
 "OriginalGrossAmount": 57,25,
 "OriginalNetAmount": 57,25,
 "UnitOfMeasure": "L",
 "RoadType": "Strada nazionale",
      "Codice ISO Paese Cliente": "DE",
 "Operatore VE": "Shell Recharge",
 "ID seriale VE": "GBALLEGO0002452",
 "Seriale del punto di ricarica EV": "GBALLEGO0002452",
 "Tipo di connettore del punto di ricarica EV": 5,
 "Descrizione del tipo di connettore del punto di ricarica EV": "CC 50 kW",
      "Durata ricarica EV": "PT3205S",
 "Data inizio ricarica EV": "2021-08-01",
 "Ora inizio ricarica EV": "20:08:01",
      "Data di fine ricarica EV": "2022-08-01",
 "Ora di fine ricarica EV": "20:08:01",
 "Numero società di raccolta ospitante": 0,
 "ID transazione": 0,
 "Solo carburante": true,
      "Numero stampato EV": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 3,
  "PageSize": 30,
  "TotalPages": 5
}

Esempio 2: Recupero dei dettagli di una transazione di rifornimento

Richiesta:

POST /transaction-data/v1/pricedtransaction

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

Risposta:

{
  "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",
 "OraTransazione": "stringa",
 "OffsetUTC": "stringa",
 "IDFlottaInserito": "XYZ1234",
 "ChilometraggioInserito": 12345,
 "NomeConducente": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
 "SimboloValutaTransazione": "$",
 "ImportoNettoTransazione": 0,
 "ImpostaTransazione": 0,
 "ImportoLordoTransazione": 0,
          "InvoiceNetAmount": 0,
 "InvoiceTax": 0,
 "InvoiceGrossAmount": 0,
 "PurchasedInCountry": "Germania",
 "AccountId": 29484,
 "AccountNumber": "GB99215176",
 "AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
 "AccountShortName": "string",
 "Quantity": 0,
 "ProdottoCarburante": true,
 "PrezzoUnitarioValutaTransazione": 0,
 "PrezzoUnitarioValutaFattura": 0,
 "ScontoUnitarioValutaTransazione": 0,
 "ScontoUnitarioValutaFattura": 0,
 "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "InvoiceDate": "string",
          "CodiceSito": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "NomeSito": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "PaeseSito": "Germania",
 "Posizione": {
 "Latitudine": "37.4224764",
 "Longitudine": "122.0842499"
 },
 "NomeGruppoSchede": "006240 FIRE BRIGHT SOLUTIONS",
 "NumeroScontrino": "1234",
 "CodiceProdotto": "10 - Addebiti TMF",
 "ProductName": "Senza piombo - Alto numero di ottani",
 "ProductGroupId": 1,
 "ProductGroupName": "Gruppo di prodotti principale",
          "Tasso di cambio DelCo": 0,
 "Tasso di cambio ColCo": 0,
 "È sito Shell": true,
 "Rete": "100013\tSTEINDORFER",
 "ID gruppo di siti": 202,
          "NomeGruppoSiti": "CZ 9100 ECONOMY NETWORK",
 "DataRegistrazione": "stringa",
 "CodiceEmittente": "7002",
          "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Paesi Bassi",
 "ReleaseCode": "8",
 "CardGroupId": "string",
          "CardSequenceNumber": "2",
 "CheckDigit": "string",
          "Descrizione ID flotta": "stringa",
 "Aliquota IVA": "0,20 per il 20%",
 "Categoria IVA": "1-Aliquota zero",
 "IVA sull’importo netto": 0,
 "Paese IVA": "Paesi Bassi",
 "Sconto effettivo nella valuta della transazione": 0,
 "Tipo di transazione": "Acquisto con carta presente, altrimenti vuoto",
 "Indicatore PIN": "“PIN utilizzato”",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
          "Sconto unitario effettivo nella valuta del cliente": 0,
 "Sconto effettivo nella valuta del cliente": 0,
 "IVA sull’importo netto nella valuta del cliente": 0,
 "Tipo di sconto": "2 pence per unità",
          "StatoTransazione": "U",
 "IDArticoloVendita": 18315958002,
 "GruppoPagatore": "stringa",
 "NomeGruppoPagatore": "12119008 - SHELL GROUP OF COMPANIES",
          "FlagRimborso": "stringa",
 "IDArticoloVenditaOriginale": "stringa",
 "NomeDelco": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
          "CodiceDelco": "14",
 "NumeroPagatore": "NL10042616",
 "NomePagatore": "V.M. LE COMTE",
 "PeriodoScadenzaCarta": "1901",
 "CodiceAutorizzazione": "1011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "ConsentiCompensazione": "S",
 "NumeroCRM": "stringa",
 "StatoContestazione": "Nessuna contestazione",
 "TassoSconto": 28,279,
 "TassoDiCambioDelCoToColCo": 1,
          "NetEuroAmount": 0,
 "EuroVATAmount": 0,
 "ParentCustomerNumber": "stringa",
 "ParentCustomerName": "stringa",
 "ParentCustomerId": 0,
          "NumeroSitoIn entrata": "100021",
 "DescrizioneSitoIn entrata": "HN3 INTI_02-82.02",
 "CodiceValutaIn entrata": "GBP",
          "CodiceProdottoIn entrata": "30",
 "CodiceCredito/Debito": "D",
 "FlagCorrezione": "Y",
 "Aggiuntivo1": "stringa",
 "Aggiuntivo2": "stringa",
 "Aggiuntivo3": "stringa",
          "Additional4": "stringa",
 "RebateonNetAmountInCustomerCurrency": -0,735,
          "Sconto sull’importo netto nella valuta della transazione": "AVEE PTUAZONW CUBFAO COSFS",
 "Identificativo transazione": "stringa",
 "Tipo di carta": "stringa",
 "Unità di prezzo di listino Delco (netto)": 30,5,
 "Unità di prezzo al dettaglio Delco (netto)": 1,921,
 "Unità di prezzo al dettaglio Delco (lordo)": 0,
 "Valore totale al dettaglio Delco (netto)": 0,
          "ValoreTotaleAlDettaglioDelcoLordo": 0,
 "UnitàPrezzoAlDettaglioClienteLordo": 0,
 "ValoreTotaleAlDettaglioClienteNetto": 0,
 "NumeroStampatoEV": "3792",
 "ÈRFID": true,
          "TokenTypeDescription": "string"
 }
 ]
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 15
}

Esempio 3: Recupero del riepilogo delle transazioni con prezzo

Richiesta:

POST /transaction-data/v1/pricedtransactionssummary

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

Risposta:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
 "ProductName": "Diesel AGO",
 "ProductGroupId": 1,
 "ProductGroupName": "Carburanti",
 "QuantitàTotaleCarburante": 1250,75,
 "ImportoNettoTotale": 5420,50,
      "TotalGrossAmount": 6504,60,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "ValoreAlDettaglioClienteTotaleNetto": 5420,50,
 "ValoreAlDettaglioClienteTotaleLordo": 6504,60
    }
  ]
}

Esempio 4: Recupera riepilogo prezzi

Richiesta:

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

Risposta:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
            "CustomerRetailValueTotalGross": 114,13,
 "CustomerRetailValueTotalNet": 95,11,
 "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
            "ProductCode": "21",
 "ProductGroupId": 3,
 "ProductGroupName": "Benzina per autotrazione",
 "ProductId": 21,
 "ProductName": "Senza piombo - Alto numero di ottani",
            "SiteGroupId": 104,
 "SiteGroupName": "Stazioni di servizio Shell predefinite in Austria",
 "TotalFuelQuantity": 17,0,
 "TotalGrossAmount": 114,13,
 "TotalNetAmount": 95,11
 }
    ]
}

Esempio 5: Recupero delle transazioni con prezzi per più pagatori

Richiesta:

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
}

Risposta:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
 "Type": "SalesItem"
 }
 ],
 "CardId": 275549,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
 "OraTransazione": "14:30:45",
 "OffsetUTC": "+01:00:00",
 "IDFlottaInserito": "XYZ1234",
      "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
      "SimboloValutaFattura": "£",
 "CodiceValutaTransazione": "GBP",
      "SimboloValutaTransazione": "£",
 "ImportoNettoTransazione": 47,71,
 "ImpostaTransazione": 9,54,
 "ImportoLordoTransazione": 57,25,
 "InvoiceNetAmount": 47,71,
 "InvoiceTax": 9,54,
 "InvoiceGrossAmount": 57,25,
 "PurchasedInCountry": "Germania",
 "ID conto": 29484,
 "Numero conto": "GB99215176",
 "Nome conto": "MATTHEW ALGIE & COMPANY LIMITED",
 "Nome abbreviato conto": "MATTHEW",
      "Quantità": 43,28,
 "ProdottoCarburante": vero,
 "PrezzoUnitarioInValutaTransazione": 1,1074,
 "PrezzoUnitarioInValutaFattura": 1,1024,
 "ScontoUnitarioValutaTransazione": -0,005,
 "ScontoUnitarioValutaFattura": -0,0051,
 "ÈFatturato": true,
 "NumeroFattura": "S04500493",
 "DataFattura": "20250815 09:30:00",
 "CodiceSito": "050001",
      "NomeSito": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "PaeseSito": "Germania",
      "Posizione": {
 "Latitudine": "53.83606",
 "Longitudine": "-1.61854"
 },
      "NomeGruppoCarte": "006240 FIRE BRIGHT SOLUTIONS",
 "NumeroScontrino": "6803",
 "CodiceProdotto": "10",
 "ProductName": "Senza piombo - Alto numero di ottani",
 "ProductGroupId": 2,
 "ProductGroupName": "Tutti i carburanti",
 "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": "Paesi Bassi",
 "Codice di emissione": "8",
 "ID gruppo carta": "40000",
 "Numero di sequenza della carta": "617",
      "CheckDigit": "6",
 "FleetIDDescription": "YG67OUM",
 "VATRate": 0,2,
 "VATCategory": "1-Aliquota standard",
 "VATonNetAmount": 9,54,
 "PaeseIVA": "Paesi Bassi",
 "ScontoEffettivoInValutaTransazione": -0,22,
 "TipoTransazione": "Acquisto",
 "IndicatorePIN": "PIN utilizzato",
      "IVA applicabile": "Sì",
 "Indicatore fattura netta": "No",
      "CodiceValutaCliente": "GBP",
 "SimboloValutaCliente": "£",
 "ScontoUnitarioEffettivoInValutaCliente": -0,0051,
      "Sconto effettivo nella valuta del cliente": -0,22,
 "IVA sull’importo netto nella valuta del cliente": 9,54,
 "Tipo di sconto": "2 pence per unità",
      "StatoTransazione": "I",
 "IDArticoloVendita": 18315958002,
 "GruppoPagatore": "H312066",
 "NomeGruppoPagatore": "12119008 - SHELL GROUP OF COMPANIES",
 "FlagRimborso": "N",
 "IDArticoloVenditaOriginale": null,
 "NomeDelco": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "014",
 "PayerNumber": "GB987654322",
 "PayerName": "V.M. LE COMTE",
      "CardExpiryPeriod": "2504",
 "AuthorisationCode": "011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
      "RigaTransazione": "1",
 "ConsentiCompensazione": "S",
 "NumeroCRM": null,
 "StatoContestazione": "Nessuna contestazione",
 "TassoSconto": 28,279,
      "Tasso di cambio DelCoToColCo": 1,
 "Importo netto in euro": 56,01,
 "Importo IVA in euro": 11,2,
 "Numero cliente principale": "GB12121212",
 "Nome cliente principaleNomeClientePrincipale": "FUEL CARD SERVICES LTD",
 "IDClientePrincipale": 6494,
 "NumeroSedeIn entrata": "100021",
 "DescrizioneSedeIn entrata": "HN3 INTI_02-82.02",
 "CodiceValutaIn entrata": "GBP",
      "CodiceProdottoIn entrata": "30",
 "CodiceCredito/Debito": "D",
 "FlagCorrezione": "N",
 "Aggiuntivo1": "GBALLEGO0002452",
 "Aggiuntivo2": null,
      "Additional3": null,
 "Additional4": null,
 "Sconto sull’importo netto nella valuta del cliente": -0,735,
 "Sconto sull’importo netto nella valuta della transazione": -0,735,
 "Identificativo transazione": "H305908971030",
 "Tipo di carta": "GB STD FLT NAT SINGLE R9",
      "Prezzo di listino Delco unitario netto": 30,5,
 "Prezzo al dettaglio Delco unitario netto": 1,1074,
 "Prezzo al dettaglio Delco unitario lordo": 1,32888,
 "Valore al dettaglio totale netto Delco": 47,93,
 "Valore al dettaglio totale lordo Delco": 57,52,
 "CustomerRetailPriceUnitGross": 1,32888,
 "CustomerRetailValueTotalNet": 47,93,
 "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "Fleet Card"
    }
  ],
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 15,
  "TotalRecords": 300
}

Esempio 6: Recupero delle regole di determinazione dei prezzi in base al volume

Richiesta:

POST /transaction-data/v1/volumebasedpricing

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

Risposta:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
      "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "ABCD1234",
 "PricingAccountFullName": "ABCD1234",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
 "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Pagamento al pagatore",
 "ID conto a cui è stato versato il bonus": 123456,
 "Numero del conto a cui è stato versato il bonus": "GB000000123",
 "Nome abbreviato del conto a cui è stato versato il bonus": "12345",
          "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Settimanale – Lunedì",
 "NextCalculationDate": "20231223",
 "PreviousCalculatedDate": "23/12/2023",
 "BaseRegolaCommissioni": "3-SommaForfettaria",
 "CodiceValutaRegolaCommissioni": "GBP",
 "SimboloValutaRegolaCommissioni": "£",
 "Data di inizio validità della regola sulle commissioni": "20231223",
 "Data di fine validità della regola sulle commissioni": "20231223",
 "Sedi della regola sulle commissioni": [
 {
 "DelcoId": 866,
              "Country": "Regno Unito",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "NomeGruppoSiti": "VALERO ENERGY LTD",
 "CodiceSito": 999493,
 "IdSito": 100007,
 "NomeSito": "VALERO ENERGY LTD"
 }
 ],
 "ProdottiRegolaTariffa": [
 {
              "ProductGroupID": 3,
 "ProductGroupName": "Benzina per autotrazione",
 "ProductCode": "30 per Diesel AGO",
 "ProductId": "30 per Diesel AGO",
 "ProductName": "Diesel AGO"
 }
          ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
              "Value": 1234,12
 }
 ]
 }
 ],
 "CurrentPeriodConsumption": [
 {
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "IDRegolaPrezzi": 100005,
 "DescrizioneRegolaPrezzi": "PL/GAGO/GMOT/UL0.055",
 "TotalVolume": 10000,78,
 "NextFeeCreationDate": "20231223"
 }
 ],
      "Cronologia": [
 {
 "DataInizio": "20231223",
 "DataFine": "20231223",
 "IDRegolaCommissioni": 8081,
 "DescrizioneRegolaCommissioni": "PT/P067/D120/P4.0",
 "TotalVolume": 12356,66
 }
 ],
 "Warnings": [
 {
 "Message": "Il sistema è inattivo per un aggiornamento.",
          "Type": "Interruzione del sistema"
 }
 ]
    }
  ]
}

Esempio 7: Recupero delle regole sui bonus basati sul volume

Richiesta:

POST /transaction-data/v1/volumebasedbonus

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

Risposta:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configurazione": [
 {
 "ID account tariffario": 123456,
          "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "MATTHEW",
 "PricingAccountFullName": "MATTHEW",
 "FeeRuleId": 1,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
          "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Pagamento al pagatore",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Settimanale – Lunedì",
          "DataCalcoloSuccessiva": "20231223",
 "DataCalcoloPrecedente": "20231223",
          "BaseRegolaCommissione": "3-Somma forfettaria",
 "CodiceValutaRegolaCommissione": "GBP",
 "SimboloValutaRegolaCommissione": "£",
 "RegolaCommissioneDisponibileDa": "20231223",
 "FeeRuleAvailableTo": "20231223",
 "FeeRuleLocations": [
 {
 "DelcoId": 866,
 "Country": "Regno Unito",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
              "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": "VALERO ENERGY LTD"
 }
 ],
 "FeeRuleProducts": [
 {
 "ProductGroupID": 3,
 "ProductGroupName": "Benzina per autotrazione",
 "ProductCode": "30 per Diesel AGO",
 "ProductId": "30 per Diesel AGO",
 "ProductName": "Diesel AGO"
 }
 ],
          "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234,12
            }
 ],
 "Conti associati": [
 {
 "ID conto associato": 12345,
 "Numero conto associato": "GB000000123",
              "NomeAbbreviatoContoAssociato": "Nome abbreviato del conto",
 "NomeCompletoContoAssociato": "Nome completo del conto"
 }
 ]
 }
 ],
 "ConsumoPeriodoCorrente": [
 {
 "IDRegolaCommissioni": 12345,
 "DescrizioneRegolaCommissioni": "NL/GAGO/D018/UP0.0120>1",
 "Mese": 1,
 "Anno": 2018,
 "VolumeTotale": 10000,78
        }
 ],
 "BonusStoriciPagati": [
 {
 "IDPagatore": 12345,
 "NumeroPagatore": "GB000000123",
 "NomeAbbreviatoPagatore": "Jorden",
 "PayerFullName": "MATTHEW",
 "IDConto": 123456,
 "NumeroConto": "GB000000123",
 "NomeAbbreviatoConto": "SALT",
 "NomeCompletoConto": "ABCD1234",
          "ID conto fattura": 12345,
 "Numero conto fattura": "GB000000123",
 "Nome abbreviato conto fattura": "DFE1234",
 "Nome completo conto fattura": "AZAD PVT LMT",
 "FeeRuleId": 12345,
          "DescrizioneRegolaCommissione": "NL/GAGO/D018/UP0.0120>1",
 "DataInizio": "20231223",
 "DataFine": "20231223",
 "BonusPagatoA": "5-Pagamento ai clienti associati",
 "FeeItemId": 12345,
 "FeeRuleBasis": "2% dell'incremento",
 "FeeItemCurrencyCode": "GBP",
 "FeeItemCurrencySymbol": "$",
 "ProratedVolume": 123,12,
          "VolumeTotale": 123,12,
 "ProdottoCommissione": "1562-Bonus diesel Shell",
 "ImportoLordoFattura": 123,12,
 "ImportoNettoFattura": 123,12,
          "InvoiceVATAmount": 123,12,
 "IsFeeCancelled": true,
 "FeeItemTierProratedVolume": 123,12,
 "FeeItemTierTotalVolume": 123,12,
 "MinimoFascia": 123,
 "TariffaFascia": 123,12
 }
 ]
    }
  ],
  "Avvisi": [
    {
 "Messaggio": "Il sistema è inattivo per un aggiornamento.",
 "Type": "Interruzione del sistema"
    }
  ]
}

Esempio 8: Ottenere il riepilogo delle commissioni

Richiesta:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Commissioni sulla carta"
}

Risposta:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Dati": [
    {
 "FeeTypeGroup": "Commissioni sulla carta",
 "FeeTypeId": 1,
 "FeeType": "Canone annuale della carta",
 "ProductId": 1234,
 "ProductCode": "FEE",
 "ProductName": "Commissione sulla carta",
 "TotalFeeAmount": 125,00,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

Esempio 9: Recupero delle eccezioni relative alle transazioni

Richiesta:

POST /transaction-data/v1/exceptions

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

Risposta:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Dati": [
    {
 "EccezioniCarte": [
 {
 "IDConto": 29484,
 "IDCarta": 1234,
 "PAN": "ABCD1234",
          "DriverName": "ANDREW GILBERRY",
 "VRN": "34235",
 "PayerId": 123455,
 "PayerNumber": "GB000000123",
          "AccountNumber": "GB99215176",
 "AccountShortName": "MATTHEW",
 "PayerShortName": "MATTHEW",
 "Day": 2,
 "Week": 2,
 "Mese": 5,
 "Anno": 2017,
 "Transazioni totali": 4,
 "Articoli venduti totali": 4,
 "Quantità totale": 261,
          "TotalAmount": 100,21,
 "CurrencyCode": "GBP",
 "CurrencySymbol": "$"
 }
 ],
 "TransactionsExceptions": [
 {
 "SalesItemId": 18315958002,
 "ID_Carta": 1234,
 "ID_Prodotto": 2,
 "GUID_Transazione": "ABCD1234",
 "DataTransazione": "20231223",
 "ValoreTotaleFatturaClienteLordo": 123,12,
 "PANCarta": "7002051006629891000",
 "ScadenzaCarta": "20311223 12:12:12",
 "OraTransazione": "12:12:12",
          "UTCOffset": "+12:12:12",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 1234,
 "DriverName": "SALT",
          "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
 "SimboloValutaTransazione": "£",
 "ImportoNettoTransazione": 123,12,
 "ImpostaTransazione": 123,12,
          "ImportoLordoTransazione": 123,12,
 "ImportoNettoFattura": 123,12,
          "InvoiceTax": 123,12,
 "InvoiceGrossAmount": 123,1,
 "PurchasedInCountry": "Francia",
 "ID conto": 1234,
 "Numero conto": "GB99215176",
 "Nome conto": "MATTHEW ALGIE & COMPANY LIMITED",
          "AccountShortName": "MATTHEW ALGIE & COMPANY LIMITED",
 "Quantity": 123,12,
 "ProdottoCarburante": true,
 "PrezzoUnitarioValutaTransazione": 123,12,
 "PrezzoUnitarioValutaFattura": 123,12,
 "ScontoUnitarioValutaTransazione": 123,12,
          "ScontoUnitarioValutaFattura": 123,12,
 "ÈFatturato": true,
 "NumeroFattura": "S04500493",
          "DataFattura": "20231223",
 "CodiceSede": "50001",
 "NomeSede": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
          "PaeseSede": "Germania",
 "Posizione": {
 "Lat": "37.4224764",
            "Lng": "122.0842499"
 },
 "NomeGruppoCarte": "006240 FIRE BRIGHT SOLUTIONS",
 "NumeroScontrino": "1234",
          "ProductCode": "TMF Charges",
 "ProductName": "Senza piombo - Alto numero di ottani",
 "ProductGroupId": 1234,
 "ProductGroupName": "Gruppo di prodotti principale",
 "DelCoExchangeRate": 123,12,
 "Tasso di cambio ColCo": 123,12,
 "È sito Shell": true,
 "Rete": "Shell PH",
 "ID gruppo di siti": 202,
 "Nome gruppo di siti": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20231223 12:12:12",
 "IssuerCode": "7077 = CRT",
          "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Paesi Bassi",
 "ReleaseCode": "8 per 702188",
 "ID Gruppo Carta": "200",
 "Numero di Sequenza Carta": "2",
 "Cifra di Controllo": "GHE1234",
 "Descrizione ID Flotta": "Descrizione di esempio",
 "Aliquota IVA": 0,2,
 "Categoria IVA": "3 - Esente IVA",
 "IVA sull'importo netto": 12,21,
 "VATCountry": "Paesi Bassi",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Acquisto con carta presente, altrimenti vuoto",
          "IndicatorePIN": "S",
 "IVA applicabile": "S",
 "Indicatore fattura netta": "S",
 "Codice valuta cliente": "GBP",
 "Simbolo valuta cliente": "£",
 "Sconto unitario effettivo nella valuta del cliente": 123,12,
 "Sconto effettivo nella valuta del cliente": 123,12,
 "IVA sull’importo netto nella valuta del cliente": 123,12,
 "Tipo di scontoountType": "3-Percentuale",
 "StatoTransazione": "U",
 "GruppoPagatore": "12119008",
 "FlagRimborso": "N",
          "ID articolo di vendita originale": "1231",
 "Nome Delco": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "Codice Delco": "NL10042616",
          "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
          "Codice di autorizzazione": "11256",
 "ID transazione": "io9KVXk1UkW57XWKyeaHHg",
 "Riga transazione": "1",
 "Consenti compensazione": "Y",
 "Numero CRM": "ABCD1234",
 "StatoContestazione": "6\tAccredito al sito",
 "TassoDiRimborso": 28,279,
          "Tasso di cambio DelCoToColCo": 1,
 "Importo netto in euro": 37,93,
 "EuroRebateAmount": 0,
 "EuroVATAmount": 7,96,
 "ParentCustomerNumber": "DRG1234"
 }
 ]
    }
  ]
}

Esempio 10: Recupera il riepilogo degli utilizzi della carta

Richiesta:

POST /transaction-data/v1/cardusagesummary

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

Risposta:

{
  "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": "Benzina per autotrazione"
 }
 ]
    }
  ]
}

Gestione degli errori

Codici di errore comuni

Stato HTTP Codice di errore Descrizione Soluzione
200 N/A Stato: SUCCESSO N/A
200 E0001 Errore di convalida Verificare i parametri della richiesta
401 E0003 Non autorizzato Verificare che il token OAuth sia valido
403 E0003 Accesso negato Controllare le autorizzazioni dell'utente
404 E0005 Risorsa non trovata Verificare che l’URL dell’endpoint e la risorsa esistano
500 E0002 Errore sconosciuto / Errore interno del server Contattare l’assistenza

Migliori pratiche

1. Adottare l’autenticazione OAuth 2.0

IMPORTANTE: Tutti i clienti dovrebbero migrare all’autenticazione OAuth 2.0. Implementare una corretta gestione dei token:

  • Memorizzare nella cache i token di accesso e riutilizzarli fino alla scadenza
  • Aggiornare i token prima della scadenza (si consiglia 60 secondi prima)
  • Memorizzare le credenziali del client in modo sicuro (utilizzare variabili d’ambiente o un gestore di segreti)
  • Non registrare né esporre mai i token di accesso nel codice lato client

2. Utilizzare gli ID di richiesta

Includere sempre un RequestId univoco (in formato GUID) per garantire la tracciabilità end-to-end

3. Implementare l’impaginazione

Per set di dati di transazioni di grandi dimensioni, utilizzare l’impaginazione per evitare timeout:

  • Impostare una dimensione della pagina (PageSize) adeguata (consigliata: 50-100 record)
  • Elaborare le pagine in modo sequenziale o in parallelo
  • Gestire TotalPages e TotalRecords nelle risposte

4. Utilizzare i filtri di data con giudizio

Quando si effettuano query sui dati delle transazioni:

  • Limitare gli intervalli di date per evitare insiemi di risultati troppo grandi
  • Utilizzare i filtri FromDate e ToDate in modo coerente
  • Valutare l’esecuzione di query per mese o settimana per migliorare le prestazioni

5. Eseguire test nell’ambiente Sandbox

Testare sempre l’integrazione nell’ambiente di test/Sandbox prima di passare alla produzione

6. Memorizzare i dati di riferimento nella cache

Memorizzare nella cache i prezzi basati sul volume e le regole relative ai bonus per ridurre al minimo le chiamate API:

  • Queste regole cambiano raramente
  • Aggiornare periodicamente la cache (ad es. quotidianamente)
  • Utilizzare il parametro IncludeHistory solo quando necessario

SDK ed esempi di codice

Shell fornisce SDK ufficiali ed esempi di codice completi per accelerare l’integrazione con l’API Transaction Data.

Linguaggi SDK disponibili

  • Python - SDK completo con supporto OAuth 2.0
  • TypeScript - SDK con sicurezza dei tipi con definizioni complete dei tipi
  • Java - SDK di livello aziendale
  • C#/.NET - Integrazione completa con .NET
  • PHP - Libreria PHP di facile utilizzo
  • Ruby - Gem Ruby per un'integrazione perfetta

Visualizza gli SDK ufficiali e la documentazione

Assistenza e risorse

Assistenza tecnica

Documentazione

Assistenza

Quando contatti l’assistenza, fornisci:

  1. Il proprio client_id (non condividere mai il proprio client_secret o i token di accesso)
  2. RequestId dalla risposta dell’API
  3. Timestamp della richiesta
  4. Ambiente (Produzione/Test)

Ultimo aggiornamento: 1 luglio 2026
Versione del documento: 1.0
Versione API: 2.3.5

Chi siamo

Il Portale per gli sviluppatori Shell supporta i partner nell'integrazione con le API Shell e nella trasformazione delle idee in soluzioni pronte per la produzione.

Logo Shell

Contatto

Contattaci

Accedere al proprio account

Chiedi all'assistente AI informazioni sulle API e sui prodotti API di Shell