B2B Mobility Customer Data v3.0.5 | Guida rapida ai dati dei clienti di B2B Mobility

Guida rapida ai dati dei clienti di B2B Mobility

Introduzione

L'API dei dati dei clienti di B2B Mobility è un servizio RESTful che consente di interrogare e gestire i dettagli degli account dei clienti, i gruppi di carte, e le relative configurazioni all’interno della piattaforma Shell Cards. Questa API offre funzionalità di ricerca flessibili, supporta l’impaginazione e consente di recuperare informazioni sugli account, indirizzi di consegna delle carte, listini prezzi e tipi di carte. Supporta inoltre operazioni per la creazione e l’aggiornamento dei gruppi di carte, nonché lo spostamento delle carte tra i gruppi.

Vantaggi	Descrizione
Gestione completa degli account	Accedi alle informazioni dettagliate sugli account dei clienti, inclusi dati di fatturazione, riepiloghi delle carte e stato
Operazioni sui gruppi di carte	Crea, aggiorna e chiudi gruppi di carte con funzionalità flessibili di spostamento delle carte
Accesso ai listini prezzi	Recupero di listini prezzi nazionali e internazionali con sconti specifici per cliente
Ricerca flessibile	Interrogazione dei dati con criteri di ricerca multipli e supporto alla paginazione

Autenticazione

Questa API supporta sia l’autenticazione di base (Basic Authentication) che OAuth 2.0. OAuth 2.0 è il metodo di autenticazione consigliato per una maggiore sicurezza.

Nota sulla migrazione

L’API ora supporta l’autenticazione OAuth 2.0. Se attualmente utilizzi l’autenticazione di base, ti consigliamo di migrare a OAuth 2.0 per una maggiore sicurezza. L’URL di base è stato aggiornato e tutti gli endpoint sono ora versionati sotto il percorso /v1. Per indicazioni dettagliate sulla migrazione, consultare la Guida alla migrazione a OAuth 2.0.

Flusso di autorizzazione

Richiesta di ID cliente e chiave segreta

Contattare il team dell’API Shell per richiedere l’accesso all’autenticazione OAuth. Il team dell’API Shell fornirà un ID cliente e una chiave segreta.

Richiedere il token Bearer

Una volta ottenute le credenziali, invia una richiesta all’endpoint del token OAuth dell’API di autenticazione Shell utilizzando le tue credenziali.

Esempio di richiesta:

curl --location --request POST 'https://api-test.shell.com/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

Nella risposta riceverai un token Bearer:

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}

Nota: il tempo di scadenza del token Bearer è indicato in secondi.

Autorizza le richieste API

Quando chiami le API di Shell, includi quanto segue nell’intestazione della richiesta.

Authorization: Bearer access_token

URL di base

Ambiente	URL
Test	https://api-test.shell.com/test
Produzione	https://api.shell.com

Integrazione di base

1. Recupera i dettagli dell’utente connesso

Descrizione: Questo endpoint recupera i dati dell’utente che ha effettuato l’accesso, inclusi i pagatori, i conti e i ruoli a cui ha accesso. Questa operazione deve essere eseguita dopo l’autenticazione riuscita per ottenere il PayerId necessario per le successive chiamate API.

Percorso: POST /user-management/v1/loggedinuser

Richiesta di esempio

curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard"
  }
}'

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
RequestId	stringa	Sì	UUID obbligatorio (RFC 4122) per il tracciamento della richiesta
IncludePayerGroup	booleano	No	Includi le informazioni sul gruppo di pagatori quando è vero (impostazione predefinita: false)
IncludeEIDDetails	booleano	No	Include i dati della fattura elettronica quando il valore è true (impostazione predefinita: false)

Risposta di esempio

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "UserName": "John123",
 "DisplayName": "John A.",
 "HasAPIAccess": true,
      "Payers": [
 {
 "IsDefault": true,
 "ColcoId": 1,
 "ColcoCode": 86,
 "PayerId": 1234,
          "PayerNumber": "GB000000123",
 "PayerName": "MATTHEW ALGIE & COMPANY LIMITED"
 }
 ]
    }
  ]
}

Campi della risposta

Campo	Tipo	Descrizione
UserName	stringa	Identificativo dell’utente connesso
DisplayName	stringa	Nome dell’utente connesso
HasAPIAccess	booleano	Vero se l’utente ha accesso all’API richiesta
PayerId	intero	ID del pagatore da utilizzare nelle richieste successive
PayerNumber	stringa	Numero del pagatore da utilizzare nelle richieste successive

2. Interrogazione dei conti dei clienti

Descrizione: Questo endpoint consente di interrogare i dettagli dei conti dei clienti dalla piattaforma Shell Cards con criteri di ricerca flessibili e supporto alla paginazione. Utilizzare l’ID pagatore (PayerId) ottenuto nel passaggio precedente.

Percorso: POST /customer-management/v1/accounts

Richiesta di esempio

curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
ColCoCode	intero	Sì	Codice della società di incasso (Codice Shell)
PayerNumber	stringa	Sì	Numero pagatore del cliente
Status	stringa	No	Filtro stato conto (ATTIVO, BLOCCATO, ANNULLATO, ecc.)
IncludeCardSummary	booleano	No	Includi dettagli del riepilogo della carta (impostazione predefinita: vero)
Pagina	numero intero	No	Numero di pagina (impostazione predefinita: 1)
PageSize	intero	No	Record per pagina (impostazione predefinita: 50)

Risposta di esempio

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "AccountId": 1,
 "AccountNumber": "GB000000124",
 "AccountFullName": "Acme Corporation",
 "Status": "Active",
 "CurrencyCode": "EUR",
      "TotalCards": 1000,
 "TotalActiveCards": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Campi della risposta

Campo	Tipo	Descrizione
AccountId	intero	Identificativo dell’account
AccountNumber	stringa	Numero dell’account
AccountFullName	stringa	Nome completo del conto
Status	stringa	Stato attuale del conto
CurrencyCode	stringa	Codice valuta ISO
TotalCards	numero intero	Numero totale di carte associate all’account
TotalActiveCards	numero intero	Numero di carte attive

3. Interrogazione dei gruppi di carte

Descrizione: Questo endpoint recupera i dettagli dei gruppi di carte dalla piattaforma Shell Cards con criteri di ricerca flessibili e impaginazione. I gruppi di carte aiutano a organizzare le carte all’interno di un conto.

Percorso: POST /customer-management/v1/cardgroups

Richiesta di esempio

curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE"
  },
  "Page": 1,
  "PageSize": 50
}'

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
ColCoCode	numero intero	Sì	Codice della società di incasso
PayerNumber	stringa	Sì	Numero pagatore del cliente
Stato	stringa	Sì	Stato del gruppo di carte (ATTIVO, CHIUSO, TUTTI)
CardGroupName	stringa	No	Filtro per nome del gruppo di carte (minimo 2 caratteri)

Risposta di esempio

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "Status": "ACTIVE",
 "PrintOnCard": true,
      "CardTypeId": 1234,
 "TotalCards": 1234,
 "ActiveCards": 999
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Campi della risposta

Campo	Tipo	Descrizione
CardGroupId	intero	Identificatore del gruppo di carte
CardGroupName	stringa	Nome del gruppo di carte
Status	stringa	Stato del gruppo di carte
TotalCards	numero intero	Numero totale di carte nel gruppo
ActiveCards	numero intero	Numero di carte attive nel gruppo

4. Crea gruppo di carte

Descrizione: Questo endpoint crea un nuovo gruppo di carte nella piattaforma Shell Cards e, facoltativamente, sposta fino a 500 carte nel gruppo appena creato. Le richieste di spostamento delle carte vengono messe in coda dopo la convalida.

Percorso: POST /customer-management/v1/createcardgroup

Richiesta di esempio

curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ColCoCode": 86,
  "PayerNumber": "GB000000123",
  "AccountNumber": "GB000000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": true,
  "Cards": [
    {
 "AccountNumber": "GB99215176",
 "PAN": "7002051006629890645"
    }
  ]
}'

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
ColCoCode	intero	Sì	Codice della società di incasso
PayerNumber	stringa	Sì	Numero pagatore del cliente
AccountNumber	stringa	Sì	Numero di conto del cliente
CardGroupName	stringa	Sì	Nome del nuovo gruppo di carte (1-40 caratteri)
PrintOnCard	booleano	Sì	Se imprimere a rilievo il nome del gruppo di carte sulle carte
Cards	array	No	Elenco delle carte da spostare (max 500)

Risposta di esempio

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "MainReference": 1234,
 "NewCardGroupReference": 5672,
 "SuccessfulRequests": [
 {
 "PAN": "7002051123456789145",
          "Riferimento": 12345
 }
 ],
 "Schede con errore": []
    }
  ]
}

Campi della risposta

Gestione degli errori

L’API utilizza i codici di stato HTTP standard. In caso di errore, ulteriori dettagli saranno forniti nel corpo della risposta.

Campo	Tipo	Descrizione
MainReference	intero	Numero di riferimento per il tracciamento della richiesta complessiva
NewCardGroupReference	intero	Numero di riferimento per la creazione del gruppo di carte
SuccessfulRequests	array	Elenco delle richieste di spostamento delle carte messe in coda con esito positivo
ErrorCards	array	Elenco delle carte la cui convalida non è andata a buon fine

Codice di errore	Descrizione	Soluzione
E0001	Errore di convalida	Verificare che i parametri della richiesta non contengano valori mancanti o non validi
E0003	Non autorizzato	Verificare le credenziali e assicurarsi che l’utente abbia accesso all’operazione
E0005	Risorsa non trovata	Verificare che la risorsa richiesta esista e sia accessibile
9015	Nome del gruppo di carte duplicato	Utilizzare un nome univoco per il gruppo di carte del cliente

Selezionare la lingua

B2B Mobility Customer Data 3.0.5

Guida rapida ai dati dei clienti di B2B Mobility

Introduzione

Autenticazione

Nota sulla migrazione

Flusso di autorizzazione

URL di base

Integrazione di base

1. Recupera i dettagli dell’utente connesso

Richiesta di esempio

Parametri della richiesta

Risposta di esempio

Campi della risposta

2. Interrogazione dei conti dei clienti

Richiesta di esempio

Parametri della richiesta

Risposta di esempio

Campi della risposta

3. Interrogazione dei gruppi di carte

Richiesta di esempio

Parametri della richiesta

Risposta di esempio

Campi della risposta

4. Crea gruppo di carte

Richiesta di esempio

Parametri della richiesta

Risposta di esempio

Campi della risposta

Gestione degli errori

Chi siamo

Contatto

Accedere al proprio account