Selectați limba dvs.

Traducere automată (Beta)

B2B Mobility Customer Data 3.0.5

This API allows querying customer account details and card groups. It allows the fetching of account details, card delivery addresses, international and national pricelists and cardtypes.

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

Ghid rapid pentru datele clienților B2B Mobility

Introducere

API-ul pentru datele clienților B2B Mobility este un serviciu RESTful care vă permite să interogați și să gestionați detaliile conturilor clienților, grupurile de carduri și configurațiile asociate în cadrul platformei Shell Cards. Acest API oferă funcții flexibile de căutare, suportă paginarea și vă permite să preluați informații despre conturi, adrese de livrare a cardurilor, liste de prețuri și tipuri de carduri. De asemenea, suportă operațiuni de creare și actualizare a grupurilor de carduri, precum și mutarea cardurilor între grupuri.

Avantaje Descriere
Gestionare completă a conturilor Acces la informații detaliate despre conturile clienților, inclusiv facturare, rezumate ale cardurilor și stare
Operațiuni cu grupuri de carduri Crearea, actualizarea și închiderea grupurilor de carduri cu funcționalități flexibile de mutare a cardurilor
Acces la liste de prețuri Preluarea listelor de prețuri naționale și internaționale cu reduceri specifice clienților
Căutare flexibilă Interogarea datelor cu criterii multiple de căutare și suport pentru paginare

Autentificare

Această API acceptă atât autentificarea de bază, cât și OAuth 2.0. OAuth 2.0 este metoda de autentificare recomandată pentru o securitate sporită.

Notă privind migrarea

API-ul acceptă acum autentificarea OAuth 2.0. Dacă utilizați în prezent autentificarea de bază, vă recomandăm să migrați la OAuth 2.0 pentru o securitate îmbunătățită. URL-ul de bază a fost actualizat, iar toate punctele finale sunt acum versiunizate sub calea /v1. Vă rugăm să consultați Asistența pentru migrarea la OAuth 2.0 pentru îndrumări detaliate privind migrarea.

Fluxul de autorizare

  1. Solicitați ID-ul clientului și cheia secretă

Contactați echipa API Shell pentru a solicita acces la autentificarea OAuth. Echipa API Shell vă va furniza un ID de client și o cheie secretă.

  1. Solicitați un token Bearer

Odată ce ați obținut datele de autentificare, efectuați o solicitare către punctul final pentru tokenul OAuth al API-ului de autentificare Shell folosind datele de autentificare.

Exemplu de solicitare:

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'

Veți primi un token Bearer în răspuns:

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

Notă: Timpul de expirare al tokenului Bearer este exprimat în secunde.

  1. Autorizarea cererilor API

Când apelați API-urile Shell, includeți următoarele în antetul cererii.

Authorization: Bearer access_token

URL-uri de bază

Mediu URL
Test https://api-test.shell.com/test
Producție https://api.shell.com

Integrare de bază

1. Obține detaliile utilizatorului conectat

Descriere: Acest punct final preia datele utilizatorului, inclusiv plătitorii, conturile și rolurile accesibile. Această operațiune trebuie apelată după autentificarea reușită pentru a obține PayerId-ul necesar pentru apelurile API ulterioare.

Cale: POST /user-management/v1/loggedinuser

Exemplu de cerere
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 de solicitare
Parametru Tip Obligatoriu Descriere
RequestId șir de caractere Da UUID obligatoriu (RFC 4122) pentru urmărirea cererii
IncludePayerGroup boolean Nu Include informații despre grupul de plătitori când valoarea este true (implicit: fals)
IncludeEIDDetails boolean Nu Include datele facturii electronice când valoarea este true (implicit: fals)
Exemplu de răspuns
{
  "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"
 }
 ]
    }
  ]
}
Câmpuri ale răspunsului
Câmp Tip Descriere
UserName string Identificatorul utilizatorului conectat
DisplayName șir de caractere Numele utilizatorului conectat
HasAPIAccess boolean Adevărat dacă utilizatorul are acces la API-ul solicitat
PayerId integer ID-ul plătitorului, pentru utilizare în solicitările ulterioare
PayerNumber string Numărul plătitorului, pentru utilizare în solicitările ulterioare

2. Interogarea conturilor clienților

Descriere: Acest punct final permite interogarea detaliilor conturilor clienților din platforma Shell Cards cu criterii de căutare flexibile și suport pentru paginare. Utilizați PayerId-ul obținut din pasul anterior.

Cale: POST /customer-management/v1/accounts

Exemplu de cerere
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 ai cererii
Parametru Tip Obligatoriu Descriere
ColCoCode număr întreg Da Codul companiei colectoare (cod Shell)
PayerNumber șir de caractere Da Numărul plătitorului clientului
Stare șir de caractere Nu Filtru pentru starea contului (ACTIV, BLOCAT, ANULAT, etc.)
IncludeCardSummary boolean Nu Include detaliile rezumatului cardului (implicit: true)
Pagină număr întreg Nu Numărul paginii (implicit: 1)
PageSize integer Nu Înregistrări pe pagină (implicit: 50)
Exemplu de răspuns
{
  "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
}
Câmpuri ale răspunsului
Câmp Tip Descriere
AccountId integer Identificator cont
AccountNumber string Număr de cont
AccountFullName șir de caractere Numele complet al contului
Status șir de caractere Starea curentă a contului
CurrencyCode șir de caractere Codul ISO al monedei
TotalCards număr întreg Numărul total de carduri asociate contului
TotalActiveCards număr întreg Numărul de carduri active

3. Interogare grupuri de carduri

Descriere: Acest punct final preia detaliile grupurilor de carduri din platforma Shell Cards, cu criterii de căutare flexibile și paginare. Grupurile de carduri ajută la organizarea cardurilor în cadrul unui cont.

Cale: POST /customer-management/v1/cardgroups

Exemplu de cerere
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 de solicitare
Parametru Tip Obligatoriu Descriere
ColCoCode număr întreg Da Codul companiei de colectare
PayerNumber șir de caractere Da Numărul de plată al clientului
Status șir de caractere Da Starea grupului de carduri (ACTIVE, TERMINATED, ALL)
CardGroupName șir de caractere Nu Filtrare după numele grupului de carduri (min. 2 caractere)
Răspuns de exemplu
{
  "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
}
Câmpuri de răspuns
Câmp Tip Descriere
CardGroupId număr întreg Identificatorul grupului de carduri
CardGroupName șir de caractere Numele grupului de carduri
Status șir de caractere Starea grupului de carduri
TotalCards număr întreg Numărul total de carduri din grup
ActiveCards număr întreg Numărul de carduri active din grup

4. Creare grup de carduri

Descriere: Acest punct final creează un nou grup de carduri în platforma Shell Cards și, opțional, mută până la 500 de carduri în grupul nou creat. Cererile de mutare a cardurilor sunt puse în coadă după validare.

Cale: POST /customer-management/v1/createcardgroup

Exemplu de cerere
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 de solicitare
Parametru Tip Obligatoriu Descriere
ColCoCode număr întreg Da Codul companiei de colectare
PayerNumber șir de caractere Da Numărul plătitorului clientului
AccountNumber șir de caractere Da Numărul de cont al clientului
CardGroupName șir de caractere Da Numele noului grup de carduri (1-40 de caractere)
PrintOnCard boolean Da Dacă se imprimă în relief numele grupului de carduri pe carduri
Cards array Nu Lista cardurilor de mutat (max. 500)
Exemplu de răspuns
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "MainReference": 1234,
 "NewCardGroupReference": 5672,
 "SuccessfulRequests": [
        {
 "PAN": "7002051123456789145",
 "Reference": 12345
 }
 ],
 "ErrorCards": []
    }
  ]
}
Câmpuri ale răspunsului
Câmp Tip Descriere
MainReference număr întreg Număr de referință pentru urmărirea cererii generale
NewCardGroupReference număr întreg Număr de referință pentru crearea grupului de carduri
SuccessfulRequests matrice Lista cererilor de mutare a cardurilor plasate cu succes în coadă
ErrorCards array Lista cardurilor a căror validare a eșuat

Gestionarea erorilor

API-ul utilizează coduri de stare HTTP standard. În cazul unei erori, detalii suplimentare vor fi furnizate în corpul răspunsului.

Cod de eroare Descriere Soluție
E0001 Eroare de validare Verificați parametrii cererii pentru valori lipsă sau nevalide
E0003 Neautorizat Verificați datele de autentificare și asigurați-vă că utilizatorul are acces la operațiune
E0005 Resursă neidentificată Confirmați că resursa solicitată există și este accesibilă
9015 Nume duplicat al grupului de carduri Utilizați un nume unic al grupului de carduri pentru client

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