Selectați limba dvs.

Traducere automată (Beta)

B2B Mobility Card Management 3.1.5

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

API-ul Shell pentru gestionarea cardurilor de mobilitate B2B – Ghid de pornire rapidă

Versiunea API: 3.1.5 | Autentificare: OAuth 2.0 | Stare: Producție

Prezentare generală

API-ul Shell Card Management este un API bazat pe REST care permite dezvoltatorilor să gestioneze cardurile de combustibil Shell prin programare. API-ul acceptă căutarea cardurilor, comandarea acestora, actualizarea stării, anularea și diverse alte operațiuni de gestionare a cardurilor.

Notă: Acest ghid acoperă doar punctele finale autentificate prin OAuth 2.0 (cale de bază: /card-management/v1). Punctele finale vechi cu autentificare de bază (/fleetmanagement/v1/card) nu sunt incluse, deoarece sunt în curs de eliminare treptată.

Caracteristici cheie

  • Căutarea și filtrarea cardurilor de combustibil cu criterii flexibile
  • Comandarea de carduri noi și urmărirea stării comenzii
  • Blocați, deblocați și anulați cardurile
  • Actualizați adresele de livrare a cardurilor
  • Gestionați setările de reînnoire automată a cardurilor
  • Mută cardurile între grupuri de carduri și conturi
  • Solicitați mementouri pentru codul PIN

Notificare importantă – OAuth 2.0

IMPORTANT: OAuth 2.0 este acum metoda standard de autentificare

  • Noi integrări: Utilizați OAuth 2.0 încă de la început
  • Integrări existente: Planificați-vă migrarea către OAuth 2.0
  • Metode vechi: Autentificarea de bază și cheia API sunt eliminate treptat

Contactați Suportul tehnic Shell pentru a obține datele de autentificare OAuth 2.0 (client_id și client_secret).

Autentificare

OAuth 2.0 (metoda standard de autentificare)

API-ul Shell Card Management utilizează fluxul de acreditări client OAuth 2.0 pentru autentificare securizată.

AVERTISMENT: Toți clienții ar trebui să planifice adoptarea autentificării OAuth 2.0. Aceasta este metoda de autentificare recomandată și adaptată viitorului pentru API-ul Shell Card Management. Metodele de autentificare vechi sunt eliminate treptat.

Fluxul OAuth 2.0

Pasul 1: Obținerea tokenului de acces

Solicitați un token de acces de la punctul final al tokenului OAuth:

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

grant_type=client_credentials&client_id=ID-ul-dumneavoastră-de-client&client_secret=secretul-dumneavoastră-de-client

Pasul 2: Utilizați tokenul de acces în solicitările API

Authorization: Bearer 
Content-Type: application/json

Gestionarea tokenurilor

Cele mai bune practici privind gestionarea tokenurilor:

  • Tokenurile de acces au o durată de viață limitată (de obicei 15 minute)
  • Implementați stocarea în cache a token-urilor pentru a evita solicitările inutile de token-uri
  • Reîmprospătați token-urile înainte de expirare pentru a asigura un serviciu neîntrerupt
  • Nu partajați niciodată client_secret-ul și nu îl încorporați în codul de pe partea clientului

Strategia de adoptare a OAuth 2.0

De ce să migrați la OAuth 2.0?

Avantaje de securitate:

  • Protocol de autentificare conform standardelor din industrie
  • Tokenurile de acces cu durată limitată reduc riscurile de securitate
  • Nu se transmit date de autentificare odată cu fiecare cerere
  • Suport îmbunătățit pentru rotația și revocarea tokenurilor

Beneficii operaționale:

  • Scalabilitate și performanță îmbunătățite
  • Capacități îmbunătățite de monitorizare și audit
  • Gestionare simplificată a datelor de autentificare
  • Integrare adaptată la viitor

Calea de migrare

Dacă utilizați în prezent metode de autentificare învechite, urmați această cale de migrare:

  1. Solicitați credențialele OAuth 2.0 de la Serviciul de asistență tehnică Shell
  2. Implementați gestionarea tokenurilor OAuth în aplicația dvs.
  3. Testați temeinic în mediul de testare/sandbox
  4. Efectuați autentificarea în paralel (OAuth + metoda tradițională) în timpul tranziției
  5. Monitorizați și validați integrarea OAuth
  6. Treceți exclusiv la OAuth odată ce a fost validată
  7. Dezactivați autentificarea veche după migrarea cu succes

Mediile

API-ul este disponibil în două medii:

Mediu URL de bază Scop
Producție https://api.shell.com Mediu de producție live
Test (Sandbox) https://api-test.shell.com/test Mediu de testare și dezvoltare

Sfat: Testați întotdeauna integrarea în mediul de testare înainte de a trece la producție.

Începere rapidă

1. Obțineți datele de autentificare OAuth

2. Obțineți tokenul de acces

Mai întâi, obțineți tokenul de acces OAuth:

Exemplu 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=ID-ul-tău-de-client&client_secret=secretul-tău-de-client"

Răspuns:

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

3. Efectuați prima solicitare API

Exemplu: Căutarea cardurilor active

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

Exemplu de răspuns:

{
    "Page": 1,
    "TotalRecords": 7994,
    "TotalPages": 7994,
    "PageSize": 1,
    "Data": [
 {
            "AccountId": 1227,
 "AccountName": "Dominica1_C_1",
 "AccountNumber": "CZ00000927",
 "AccountShortName": "Dominica1_1",
            "ID pachet": null,
 "Programări blocare card": null,
 "ID grup carduri": null,
 "Denumire grup carduri": null,
 "ID card": 491623,
            "CardTypeCode": "7027329",
 "CardTypeId": 11120,
 "CardTypeName": "CZ SFA NAT SIN - CHIP",
 "ColCoCountryCode": "CZ",
            "CreationDate": "20220810 23:53:25",
 "DriverName": "SHELL973169581",
 "EffectiveDate": "20220810",
 "ExpiryDate": "20260831",
 "FleetIdInput": true,
            "IsCRT": false,
 "IsFleet": true,
 "IsInternational": false,
 "IsNational": true,
 "IsPartnerSitesIncluded": false,
 "IsShellSitesOnly": true,
            "DataEmitere": "20220812",
 "EsteÎnlocuit": false,
 "EsteCardVirtual": false,
 "DataUltimeiModificări": "20230614 00:05:16",
            "LastUsedDate": null,
 "LocalCurrencyCode": "CZK",
 "LocalCurrencySymbol": "Kč",
 "OdometerInput": true,
            "PAN": "7027329200001461736",
 "MaskedPAN": "7027329******461736",
 "PANID": 17268839,
            "PurchaseCategoryCode": "2",
 "PurchaseCategoryId": 102,
            "PurchaseCategoryName": "2 - Toate produsele din categoria combustibili, articole auto și TMF",
 "Reason": "Programat pentru deblocare",
 "ReissueSetting": "True",
 "StatusDescription": "Activ",
            "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": "Card de combustibil"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

Referință pentru punctele finale API

Căutare și recuperare carduri

Punct final Metodă Descriere
/card-management/v1/search POST Căutare de carduri cu filtre flexibile (OAuth 2.0)
/card-management/v1/details POST Obține detalii despre un singur card de combustibil (OAuth 2.0)

Cazuri de utilizare frecvente:

  • Căutare după starea cardului (ACTIV, BLOCAT, EXPIRAT etc.)
  • Filtrare după numele șoferului sau numărul de înmatriculare al vehiculului
  • Căutare după PAN (ultimele 4 cifre)
  • Găsiți cardurile care expiră în X zile

Rezumat card

Punct de interfață Metodă Descriere
/card-management/v1/summary POST Obține un rezumat general al cardurilor de combustibil (OAuth 2.0)

Returnează:

  • Numărul total de carduri pe stări
  • Statistici sumare pe tip de card
  • Defalcare active vs inactive

Comandarea cardurilor

Punct de interfață Metodă Descriere
/card-management/v1/ordercard POST Comandă una sau mai multe carduri de combustibil (OAuth 2.0)
/card-management/v1/ordercardenquiry POST Verifică starea comenzii de carduri (OAuth 2.0)

Informații necesare pentru comandarea cardurilor:

  • ColCoCode (Codul companiei de colectare)
  • Numărul plătitorului sau ID-ul plătitorului
  • Numărul contului
  • Tipul și configurația cardului
  • Detalii adresă de livrare

Gestionarea stării cardului

Punct de interfață Metodă Descriere
/card-management/v1/updatestatus POST Blocare, deblocare sau anulare carduri (OAuth 2.0)
/card-management/v1/schedulecardblock POST Programarea cererilor de blocare/deblocare a cardurilor (OAuth 2.0)

Acțiuni privind starea:

  • BLOCARE - Blocare temporară a unui card
  • DEBLOCARE - Reactivarea unui card blocat
  • DETERIORAT - Raportarea unui card ca fiind deteriorat și solicitarea înlocuirii acestuia
  • TEMP_BLOCK_CUSTOMER - Blocare temporară inițiată de client
  • TEMP_BLOCK_SHELL - Blocare temporară inițiată de sistemul de operare

ATENȚIE: Anularea cardului este definitivă și nu poate fi anulată.

Puncte de contact suplimentare

Categorie Punct de contact Metodă Descriere
Anulare /card-management/v1/cancel POST Anulează unul sau mai multe carduri
Mutarea cardurilor /card-management/v1/move POST Mutarea cardurilor într-un alt grup de carduri sau cont
Gestionarea codului PIN /card-management/v1/pinreminder POST Solicită reamintirea codului PIN pentru un card
Adresă de livrare /card-management/v1/deliveryaddressupdate POST Actualizare adresă de livrare a cardului
Reînnoire automată /card-management/v1/autorenew POST Actualizare indicator de reemitere

Exemple de utilizare

Exemplul 1: Căutarea cardurilor care expiră în curând

POST /card-management/v1/search

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

Exemplul 2: Blocarea temporară a unui card

POST /card-management/v1/updatestatus

{

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

  ]
}

Exemplul 3: Anularea cardurilor

POST /card-management/v1/cancel

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

Gestionarea erorilor

Coduri de eroare comune

Stare HTTP Cod de eroare Descriere Soluție
200 N/A Stare: SUCCES N/A
400 E0001 Eroare de validare Verificați parametrii cererii
401 E0003 Neautorizat Verificați dacă tokenul OAuth este valid
403 E0003 Acces interzis Verificați permisiunile utilizatorului
404 E0005 Resursă neidentificată Verificați dacă URL-ul punctului final și resursa există
500 E0002 Eroare necunoscută / Eroare internă a serverului Contactați serviciul de asistență

Cele mai bune practici

1. Adoptați autentificarea OAuth 2.0

IMPORTANT: Toți clienții ar trebui să migreze la autentificarea OAuth 2.0. Implementați o gestionare corespunzătoare a tokenurilor:

  • Stocați în cache tokenurile de acces și reutilizați-le până la expirare
  • Reîmprospătați tokenurile înainte ca acestea să expire (se recomandă cu 60 de secunde înainte)
  • Stocați în siguranță datele de autentificare ale clientului (utilizați variabile de mediu sau un manager de secrete)
  • Nu înregistrați și nu expuneți niciodată tokenurile de acces în codul de pe partea clientului

2. Utilizați ID-urile de solicitare

Includeți întotdeauna un RequestId unic (în format GUID) pentru trasabilitate de la un capăt la altul

3. Implementați paginarea

Pentru seturi mari de date, utilizați paginarea pentru a evita expirarea timpului de așteptare

4. Testați în mediul Sandbox

Testați întotdeauna integrarea în mediul de testare/Sandbox înainte de a trece la producție

SDK și exemple de cod

Shell oferă SDK-uri oficiale și exemple de cod cuprinzătoare pentru a accelera integrarea dvs. cu API-ul de gestionare a cardurilor.

Limbaje SDK disponibile

  • Python - SDK cu funcționalități complete și suport pentru OAuth 2.0
  • TypeScript - SDK cu siguranță de tip, cu definiții complete de tipuri
  • Java - SDK de nivel enterprise
  • C#/.NET - Integrare completă cu .NET
  • PHP - Bibliotecă PHP ușor de utilizat
  • Ruby - Gem Ruby pentru integrare perfectă

Vizualizați SDK-urile oficiale și documentația

Asistență și resurse

Asistență tehnică

Documentație

Asistență

Când contactați serviciul de asistență, furnizați:

  1. ID-ul dvs. de client (nu divulgați niciodată secretul de client sau tokenurile de acces)
  2. RequestId din răspunsul API-ului
  3. Data și ora solicitării
  4. Mediu (Producție/Testare)

Ultima actualizare: 1 iulie 2026
Versiunea documentului: 1.0
Versiunea API: 3.1.5

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