API Shell B2B Mobility per i dati delle transazioni autostradali - Guida rapida

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

Panoramica

L’API Shell B2B Mobility per i dati delle transazioni relative ai pedaggi è un’API basata su REST che fornisce un accesso completo ai registri delle transazioni relative ai pedaggi e ai dati correlati per i clienti della mobilità Shell. Questa API consente agli sviluppatori di recuperare, filtrare e analizzare i dati delle transazioni relative ai pedaggi a livello di programmazione per la riconciliazione dei conti, la verifica della fatturazione, la gestione delle spese e i requisiti di conformità.

Caratteristiche principali

Recupero dei dati delle transazioni relative ai pedaggi in base al numero di conto
Filtrare le transazioni per intervallo di date (date di inizio e fine)
Ricerca in base allo stato della fattura e al VRN (numero di immatricolazione del veicolo)
Funzionalità di ordinamento avanzate su più campi
Supporto dell’impaginazione per set di dati di grandi dimensioni
Filtraggio flessibile dei campi per ottimizzare il payload della risposta
Dettagli completi sui pedaggi, compresi i punti di entrata/uscita
Supporto per più reti e operatori di pedaggio

Autenticazione

OAuth 2.0 (metodo di autenticazione standard)

L’API Shell per i dati delle transazioni di pedaggio utilizza il flusso delle credenziali client OAuth 2.0 per un’autenticazione sicura.

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-client&client_secret=il-tuo-segreto-del-client

Passaggio 2: utilizzare il token di accesso nelle richieste API

Authorization: Bearer 
Content-Type: application/json
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

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 proprio client_secret né incorporarlo nel codice lato client

Ambienti

L’API è disponibile in due ambienti:

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

URL dei token OAuth:

Ambiente	URL del token
Produzione	https://api.shell.com/v2/oauth/token
Test (UAT)	https://api-test.shell.com/v2/oauth/token

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

Guida rapida

1. Ottieni le tue credenziali OAuth

Contatta Supporto tecnico Shell
Richiedi le credenziali OAuth 2.0 (client_id e client_secret)
Consulta condizioni di servizio

2. Ottenere il token di accesso

Per prima cosa, ottieni il tuo 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-cliente&client_secret=il-tuo-segreto-cliente"

Risposta:

{
  "access_token": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Effettua la tua prima richiesta API

Esempio: Ricerca delle transazioni relative ai pedaggi

Esempio con cURL:

curl -X POST https://api-test.shell.com/toll-data/v1/transactions/search \
  -H "Authorization: Bearer eyJhbGci******NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "RequestId: eb621f45-a543-4d9a-a934-2f223b263c42" \
  -d '{
    "Filters": {
 "ColCoCode": 86,
        "PayerNumber": "NL20016398",
 "AccountNumber": "NL20027701",
 "Filter": "All",
 "FromDate": "2026-01-01",
        "ToDate": "2026-01-31"
    },
    "Page": 1,
    "PageSize": 10
}'

Risposta di esempio:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "TotalPages": 15,
  "PageSize": 10,
  "Data": [
    {
 "NetworkDescription": "Società Autostradali",
 "TollChargerCode": "410|610",
 "DelcoCode": "714",
      "NomeDelco": "Shell Fleet Solutions Consorzio",
 "CodiceRete": "TLI",
 "Rete": "euroShell Consortio",
 "PaeseDiAcquisto": "Italia",
 "CodicePaeseDiAcquisto": "IT",
      "CardNumber": "707737*******334272",
 "CardId": 123456789,
 "CardGroupName": "Shell Fleet Solutions Consorzio",
      "TargaVeicolo": "KN 00000",
 "CentroDiCosto": "100",
 "DataInserimentoSistema": "20260123",
 "OraInserimentoSistema": "13:14:25",
      "DataTransazione": "20260120",
 "OraTransazione": "10:30:00",
      "Data di registrazione": "20260123",
 "Ora di registrazione": "00:00:00",
 "Numero del pagatore": "NL20016398",
      "AccountNumber": "NL20027701",
 "AccountName": "Nome conto di prova",
 "StartDate": "20260120",
 "StartTime": "06:47:41",
      "DataFine": "20260120",
 "OraFine": "07:30:15",
 "EntrataCasello": "ROMA NORD",
      "TollGateExit": "BRENNERO",
 "DistanceDriven": "71,6",
 "RouteDescription": "ROMA NORD - BRENNERO",
 "TransactionType": "Pedaggio",
      "CodiceProdotto": "14",
 "DescrizioneProdotto": "Pedaggio",
 "ImportoNettoTransazione": "127,1",
 "ImpostaTransazione": "0,0",
 "ImportoLordoTransazione": "127,1",
 "CodiceValutaTransazione": "EUR",
 "StatoTransazione": "Segnalazione",
      "NumeroFattura": "8600397548",
 "DataFattura": "20260125",
 "StatoFattura": "Fatturata",
      "MetodoDiPagamento": "Pagamento posticipato",
 "NumeroDiSerieOBU": "00049000000836932426",
      "Classe di emissione": "Euro 6",
 "ID contratto": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ID transazione Shell": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "Gestore pedaggio": "Toll4Europe",
      "TollDomain": "Toll4Europe",
 "TariffRelevantInformation": "Classe del veicolo: 2, Numero di assi: 2, Categoria stradale: Autostrada",
      "AdditionalTransactionInfo": "Posizione: 1",
 "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

Riferimento agli endpoint API

Transazioni di pedaggio

Endpoint	Metodo	Descrizione
/toll-data/v1/transactions/search	POST	Recupera i dati delle transazioni di pedaggio con filtri e impaginazione flessibili

Casi d’uso comuni:

Recupero delle transazioni relative ai pedaggi per intervallo di date
Filtro in base allo stato della fattura (Fatturate, Non fatturate, Tutte)
Cerca per numero di immatricolazione del veicolo (VRN)
Filtra per gruppo di carte
Ordina le transazioni in base a più criteri
Seleziona campi specifici per ottimizzare la dimensione della risposta

Casi d'uso comuni

Questa sezione mette in relazione scenari aziendali comuni con i modelli di utilizzo dell’API per aiutarti a identificare rapidamente come utilizzare l’API in base alle tue esigenze specifiche.

Caso d’uso 1: Riconciliazione giornaliera delle transazioni di pedaggio

Scenario: È necessario riconciliare quotidianamente tutte le transazioni relative ai pedaggi della propria flotta a fini contabili.