API di gestione delle carte Shell B2B Mobility - Guida rapida

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

Panoramica

L’API di gestione delle carte Shell è un’API basata su REST che consente agli sviluppatori di gestire le carte carburante Shell a livello di programmazione. L’API supporta la ricerca delle carte, l’ordinazione, gli aggiornamenti di stato, la cancellazione e varie altre operazioni di gestione delle carte.

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

Caratteristiche principali

Ricerca e filtro delle carte carburante con criteri flessibili
Ordina nuove carte e monitora lo stato dell’ordine
Bloccare, sbloccare e annullare le carte
Aggiornare gli indirizzi di consegna delle carte
Gestire le impostazioni di rinnovo automatico delle carte
Sposta le carte tra gruppi di carte e conti
Richiedi promemoria del PIN

Avviso importante - 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 e la chiave API stanno per essere dismesse

Contatta Supporto tecnico Shell per ottenere le credenziali OAuth 2.0 (client_id e client_secret).

Autenticazione

OAuth 2.0 (Metodo di autenticazione standard)

L'API di gestione delle carte Shell 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 di gestione delle carte 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 proprio client_secret né incorporarlo nel codice lato client

Strategia di adozione di OAuth 2.0 Strategia di adozione

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:

Richiedi le credenziali OAuth 2.0 da Supporto tecnico Shell
Implementa la gestione dei token OAuth nella tua applicazione
Esegui test approfonditi nell’ambiente di test/sandbox
Esegui l’autenticazione in parallelo (OAuth + legacy) durante la transizione
Monitorare e convalidare l’integrazione OAuth
Passare esclusivamente a OAuth una volta completata la convalida
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 attivo
Test (Sandbox)	https://api-test.shell.com/test	Ambiente di test e sviluppo

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

Guida rapida

1. Ottieni le tue credenziali OAuth

Contatta il Supporto tecnico di Shell
Richiedi 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-client&client_secret=il-tuo-segreto-client"

Risposta:

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

3. Effettua la tua prima richiesta API

Esempio: Cerca le carte attive

Esempio con cURL:

curl -X POST https://api-test.shell.com/test/card-management/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "PayerNumber": "CZ00000927",
 "AccountNumber": "CZ00000927",
        "ColCoCode": 32,
 "CardStatus": [
 "Active"
 ]
       
    },
    "Page": 1,
    "PageSize": 1
}'

Risposta di esempio:

{
    "Page": 1,
    "TotalRecords": 7994,
    "TotalPages": 7994,
    "PageSize": 1,
    "Data": [
 {
 "AccountId": 1227,
            "AccountName": "Dominica1_C_1",
 "AccountNumber": "CZ00000927",
 "AccountShortName": "Dominica1_1",
 "BundleId": null,
            "CardBlockSchedules": null,
 "CardGroupId": null,
 "CardGroupName": null,
 "CardId": 491623,
 "CardTypeCode": "7027329",
            "ID tipo di carta": 11120,
 "Nome tipo di carta": "CZ SFA NAT SIN - CHIP",
 "Codice paese emittente": "CZ",
            "CreationDate": "20220810 23:53:25",
 "DriverName": "SHELL973169581",
            "DataDiValidità": "10/08/2022",
 "DataDiScadenza": "31/08/2026",
 "FleetIdInput": true,
 "IsCRT": false,
            "IsFleet": true,
 "IsInternational": false,
 "IsNational": true,
 "IsPartnerSitesIncluded": false,
 "IsShellSitesOnly": true,
            "Data di emissione": "12/08/2022",
 "È sostituita": false,
 "È carta virtuale": false,
 "Data dell'ultima modifica": "14/06/2023 00:05:16",
            "LastUsedDate": null,
 "LocalCurrencyCode": "CZK",
 "LocalCurrencySymbol": "Kč",
 "OdometerInput": true,
 "PAN": "7027329200001461736",
 "MaskedPAN": "7027329******461736",
 "PANID": 17268839,
            "CodiceCategoriaAcquisto": "2",
 "IDCategoriaAcquisto": 102,
 "NomeCategoriaAcquisto": "2 - Tutti i prodotti relativi ai carburanti, articoli per auto e TMF",
 "Motivo": "In programma per sblocco",
            "ReissueSetting": "True",
 "StatusDescription": "Attivo",
 "StatusId": 1,
 "TokenTypeID": 503742,
            "TokenTypeName": "CZ SFA NAT SIN – CHIP",
 "VRN": "VRN347886994",
            "ClientReferenceId": null,
 "IsEMVContact": true,
 "IsEMVContactless": false,
 "IsRFID": false,
 "RFIDUID": null,
 "EMAID": null,
            "EVPrintedNumber": null,
 "CardMediaCode": "100999",
 "MediumTypeID": 1,
 "MediumType": "Fuel Card"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

Riferimento agli endpoint API

Ricerca e recupero delle carte

Endpoint	Metodo	Descrizione
/card-management/v1/search	POST	Ricerca di carte con filtri flessibili (OAuth 2.0)
/card-management/v1/details	POST	Recupera i dettagli di una singola carta carburante (OAuth 2.0)

Casi d’uso comuni:

Ricerca in base allo stato della carta (ATTIVA, BLOCCATA, SCADUTA, ecc.)
Filtra per nome del conducente o targa del veicolo
Cerca per PAN (ultime 4 cifre)
Trova le carte in scadenza tra X giorni

Riepilogo della carta

Endpoint	Metodo	Descrizione
/card-management/v1/summary	POST	Ottieni un riepilogo di alto livello delle carte carburante (OAuth 2.0)

Restituisce:

Numero totale di carte per stato
Statistiche di riepilogo per tipo di carta
Ripartizione tra carte attive e inattive

Ordinazione delle carte

Endpoint	Metodo	Descrizione
/card-management/v1/ordercard	POST	Ordina una o più carte carburante (OAuth 2.0)
/card-management/v1/ordercardenquiry	POST	Verifica lo stato dell’ordine delle carte (OAuth 2.0)

Informazioni richieste per l’ordine delle carte:

ColCoCode (Codice della società di raccolta)
Numero del pagatore o ID del pagatore
Numero di conto
Tipo e configurazione della carta
Dettagli dell’indirizzo di consegna

Gestione dello stato della carta

Endpoint	Metodo	Descrizione
/card-management/v1/updatestatus	POST	Bloccare, sbloccare, o annullare le carte (OAuth 2.0)
/card-management/v1/schedulecardblock	POST	Pianificare richieste di blocco/sblocco delle carte (OAuth 2.0)

Azioni relative allo stato:

BLOCCO - Bloccare temporaneamente una carta
SBLOCCO - Riattivare una carta bloccata
DANNEGGIATA - Segnalare la carta come danneggiata e richiederne la sostituzione
BLOCCO TEMPORANEO INIZIATO DAL CLIENTE - Blocco temporaneo
TEMP_BLOCK_SHELL - Blocco temporaneo avviato da Shell

ATTENZIONE: La cancellazione della carta è definitiva e non può essere annullata.

Endpoint aggiuntivi

Categoria	Endpoint	Metodo	Descrizione
Annullamento	/card-management/v1/cancel	POST	Cancella una o più carte
Spostamento delle carte	/card-management/v1/move	POST	Sposta le carte in un altro gruppo di carte o conto
Gestione del PIN	/card-management/v1/pinreminder	POST	Richiedi un promemoria del PIN per una carta
Indirizzo di consegna	/card-management/v1/deliveryaddressupdate	POST	Aggiorna l’indirizzo di consegna della carta
Rinnovo automatico	/card-management/v1/autorenew	POST	Aggiorna l’indicatore di riemissione

Esempi di utilizzo

Esempio 1: Ricerca delle carte in scadenza a breve

POST /card-management/v1/search

{
    "Filters": {
 "PayerNumber": "CZ00000927",
 "AccountNumber": "CZ00000927",
        "ColCoCode": 32,
 "CardStatus": [
 "Active"
 ],
 "ExpiringInDays" : 70
 
 },
    "Page": 1,
    "PageSize": 1
}

Esempio 2: Blocco temporaneo di una carta

POST /card-management/v1/updatestatus

{

  "Cards": [
    {
 "CardId": 125,
 "ColCoCode": 86,
      "PayerNumber": "PH50000843",
    },
    "ReasonId": 1236,
    "ReasonText": "Sblocca",
    "TargetStatus": "Sbloccato"

  ]
}

Esempio 3: Annullamento delle carte

POST /card-management/v1/cancel

{
  
  "Cards": [
    {
 "CardId": 125,
 "CardExpiryDate": "20231231",
 "ColCoCode": 86,
 "PayerNumber": "PH50000843",
    }
  ],
  "ReasonText": "Smarrita",
  "RequestId": "1"
}

Gestione degli errori

Codici di errore comuni

Stato HTTP	Codice di errore	Descrizione	Soluzione
200	N/A	Stato: SUCCESS	N/A
400	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 devono migrare all’autenticazione OAuth 2.0. Implementare una corretta gestione dei token:

Memorizzare i token di accesso nella cache e riutilizzarli fino alla scadenza
Aggiornare i token prima che scadano (si consiglia 60 secondi prima)
Conservare 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 grandi dimensioni, utilizzare l’impaginazione per evitare timeout

4. Eseguire i test in ambiente sandbox

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

SDK ed esempi di codice

Shell fornisce SDK ufficiali ed esempi di codice completi per accelerare l’integrazione con l’API di gestione delle carte.

Linguaggi SDK disponibili

Python - SDK completo con supporto OAuth 2.0
TypeScript - SDK con sicurezza dei tipi e 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 SDK e documentazione ufficiali

Supporto e Risorse

Assistenza tecnica

Assistenza: Assistenza tecnica Shell

Documentazione

Assistenza

Quando contatti l’assistenza, fornisci:

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

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