Shell B2B Mobility kártyakezelő API – Gyors útmutató

API-verzió: 3.1.5 | Hitelesítés: OAuth 2.0 | Állapot: Termelési környezet

Áttekintés

A Shell Card Management API egy REST-alapú API, amely lehetővé teszi a fejlesztők számára a Shell üzemanyagkártyák programozási úton történő kezelését. Az API támogatja a kártyakeresést, a megrendelést, az állapotfrissítéseket, a lemondást és számos egyéb kártyakezelési műveletet.

Megjegyzés: Ez az útmutató kizárólag az OAuth 2.0 hitelesítésű végpontokat tárgyalja (alapútvonal: /card-management/v1). A régi Basic Auth végpontok (/fleetmanagement/v1/card) nem szerepelnek a leírásban, mivel azok fokozatosan kivezetésre kerülnek.

Főbb jellemzők

Üzemanyagkártyák keresése és szűrése rugalmas feltételek alapján
Új kártyák rendelése és a rendelés állapotának nyomon követése
Kártyák letiltása, feloldása, és kártyák törlése
Kártya kézbesítési címek frissítése
Kártya automatikus megújítási beállításainak kezelése
Kártyák áthelyezése kártyacsoportok és számlák között
PIN-kódra vonatkozó emlékeztetők kérése

Fontos tudnivaló – OAuth 2.0

FONTOS: Az OAuth 2.0 mostantól a szabványos hitelesítési módszer

Új integrációk: Használja az OAuth 2.0-t a kezdetektől fogva
Meglévő integrációk: Tervezze meg az OAuth 2.0-ra való áttérést
Régi módszerek: A Basic Auth és az API-kulcs fokozatosan kivezetésre kerül

Vegye fel a kapcsolatot a Shell műszaki támogatással, hogy megkapja az OAuth 2.0 hitelesítő adatait (client_id és client_secret).

Hitelesítés

OAuth 2.0 (szabványos hitelesítési módszer)

A Shell Card Management API a biztonságos hitelesítéshez az OAuth 2.0 kliens hitelesítőadatok folyamatát használja.

FIGYELMEZTETÉS: Minden ügyfélnek érdemes átállnia az OAuth 2.0 hitelesítésre. Ez a Shell Card Management API számára ajánlott és jövőbiztos hitelesítési módszer. A régi hitelesítési módszerek fokozatosan kikerülnek a használatból.

OAuth 2.0 folyamat

1. lépés: Hozzáférési token beszerzése

Kérjen hozzáférési tokent az OAuth token végponttól:

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

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

2. lépés: A hozzáférési token használata az API-kérelmekben

Authorization: Bearer 
Content-Type: application/json

Tokenkezelés

A tokenkezelés bevált gyakorlatai:

Az hozzáférési tokenek élettartama korlátozott (általában 15 perc)
Vezessen be token-gyorsítótárazást a felesleges token-lekérdezések elkerülése érdekében
A szolgáltatás zavartalan működésének biztosítása érdekében frissítse a tokeneket lejáratuk előtt
Soha ne ossza meg a client_secret-jét, és ne ágyazza be azt a kliensoldali kódba

OAuth 2.0 bevezetési stratégia

Miért érdemes áttérni az OAuth 2.0-ra?

Biztonsági előnyök:

Iparági szabványnak megfelelő hitelesítési protokoll
Az időkorlátozott hozzáférési tokenek csökkentik a biztonsági kockázatokat
Minden kérésnél hitelesítő adatok továbbítása nélkül
A tokenek cseréjének és visszavonásának jobb támogatása

Üzemeltetési előnyök:

Jobb skálázhatóság és teljesítmény
Jobb felügyeleti és auditálási képességek
Egyszerűsített hitelesítőadatok kezelése
Jövőbiztos integráció

Áttérési út

Ha jelenleg régebbi hitelesítési módszereket használ, kövesse ezt az áttérési utat:

Kérjen OAuth 2.0 hitelesítő adatokat a Shell műszaki támogatás
Vezesse be az OAuth-tokenkezelést az alkalmazásában
Végezzen alapos tesztelést a teszt-/sandbox-környezetben
Végezzen párhuzamos hitelesítést (OAuth + régi rendszer) az átállás ideje alatt
Figyelje és ellenőrizze az OAuth-integrációt
Váltson át kizárólag OAuth-ra az érvényesítés után
A sikeres áttérés után a régi hitelesítési módszer leállítása

Környezetek

Az API két környezetben érhető el:

Környezet	Alap-URL	Cél
Termelési környezet	https://api.shell.com	Élő termelési környezet
Teszt (Sandbox)	https://api-test.shell.com/test	Teszt- és fejlesztési környezet

Tipp: Mindig tesztelje az integrációt a tesztkörnyezetben, mielőtt átállna a termelésre.

Gyors útmutató

1. Szerezze be OAuth-hitelesítő adatait

Vegye fel a kapcsolatot a Shell műszaki támogatásával
OAuth 2.0 hitelesítő adatok (client_id és client_secret) igénylése
Olvassa át a szolgáltatási feltételeket

2. Hozzáférési token beszerzése

Először szerezze be az OAuth hozzáférési tokenjét:

cURL példa:

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=your-client-id&client_secret=your-client-secret"

Válasz:

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

3. Az első API-lekérdezés elvégzése

Példa: Aktív kártyák keresése

cURL-példa:

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

Példa a válaszra:

{
    "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",
 "CardTypeId": 11120,
            "CardTypeName": "CZ SFA NAT SIN - CHIP",
 "ColCoCountryCode": "CZ",
 "CreationDate": "20220810 23:53:25",
            "DriverName": "SHELL973169581",
 "EffectiveDate": "20220810",
            "Lejárati dátum": "20260831",
 "Flottaazonosító bevitele": true,
 "CRT-kártya": false,
 "Flotta": true,
 "Nemzetközi": false,
            "IsNational": true,
 "IsPartnerSitesIncluded": false,
 "IsShellSitesOnly": true,
 "IssueDate": "20220812",
            "IsSuperseded": false,
 "IsVirtualCard": false,
 "LastModifiedDate": "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 – Minden üzemanyag-termék, autóhoz kapcsolódó cikkek és TMF",
            "Reason": "Feloldásra ütemezve",
 "ReissueSetting": "True",
 "StatusDescription": "Aktív",
 "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": "Üzemanyagkártya"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

API végpontok referencia

Kártyakeresés és -lekérés

Végpont	Módszer	Leírás
/card-management/v1/search	POST	Kártyakeresés rugalmas szűrőkkel (OAuth 2.0)
/card-management/v1/details	POST	Egyetlen üzemanyagkártya adatainak lekérése (OAuth 2.0)

Gyakori felhasználási esetek:

Keresés kártyaállapot szerint (AKTÍV, LETILTOTT, LEJÁRT stb.)
Szűrés vezető neve vagy jármű rendszáma alapján
Keresés PAN-szám alapján (utolsó 4 számjegy)
X nap múlva lejáró kártyák keresése

Kártyaösszefoglaló

Végpont	Módszer	Leírás
/card-management/v1/summary	POST	Üzemanyag-kártyák átfogó összefoglalásának lekérése (OAuth 2.0)

Visszatérési érték:

Kártyák összlétszáma állapot szerint
Összefoglaló statisztikák kártyatípusok szerint
Aktív és inaktív kártyák megoszlása

Kártyarendelés

Végpont	Módszer	Leírás
/card-management/v1/ordercard	POST	Egy vagy több üzemanyag-kártya megrendelése (OAuth 2.0)
/card-management/v1/ordercardenquiry	POST	Kártyarendelés állapotának ellenőrzése (OAuth 2.0)

A kártyarendeléshez szükséges információk:

ColCoCode (beszedő vállalat kódja)
Fizetőszám vagy Fizetőazonosító
Számlaszám
Kártyatípus és konfiguráció
Szállítási cím adatai

Kártyaállapot-kezelés

Végpont	Módszer	Leírás
/card-management/v1/updatestatus	POST	Kártyák letiltása, kártyák feloldása vagy törlése (OAuth 2.0)
/card-management/v1/schedulecardblock	POST	Kártya-blokkolási/feloldási kérelmek ütemezése (OAuth 2.0)

Állapotműveletek:

BLOCK - Kártya ideiglenes letiltása
BLOKKOLÁS FELOLDÁSA - A blokkolt kártya újraaktiválása
SÉRÜLT - Jelentsd be a kártya sérülését, és kérj pótkártyát
TEMP_BLOCK_CUSTOMER - Ügyfél által kezdeményezett ideiglenes letiltás
TEMP_BLOCK_SHELL - A Shell által kezdeményezett ideiglenes blokkolás

FIGYELEM: A kártya törlése végleges és visszafordíthatatlan.

További végpontok

Kategória	Végpont	Módszer	Leírás
Törlés	/card-management/v1/cancel	POST	Egy vagy több kártya törlése
Kártyák áthelyezése	/card-management/v1/move	POST	Kártyák áthelyezése egy másik kártyacsoportba vagy számlára
PIN-kód kezelése	/card-management/v1/pinreminder	POST	PIN-emlékeztető kérése egy kártyához
Szállítási cím	/card-management/v1/deliveryaddressupdate	POST	A kártya szállítási címének frissítése
Automatikus megújítás	/card-management/v1/autorenew	POST	Újrakibocsátási jelző frissítése

Használati példák

1. példa: Hamarosan lejáró kártyák keresése

POST /card-management/v1/search

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

2. példa: Kártya ideiglenes letiltása

POST /card-management/v1/updatestatus

{

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

  ]
}

3. példa: Kártyák törlése

POST /card-management/v1/cancel

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

Hibakezelés

Gyakori hibakódok

HTTP-állapot	Hibakód	Leírás	Megoldás
200	N/A	Állapot: SIKERES	N/A
400	E0001	Érvényesítési hiba	Ellenőrizze a kérés paramétereit
401	E0003	Jogosulatlan	Ellenőrizze, hogy az OAuth-token érvényes-e
403	E0003	Tiltva	Ellenőrizze a felhasználói jogosultságokat
404	E0005	Az erőforrás nem található	Ellenőrizze, hogy a végpont URL-je és az erőforrás létezik-e
500	E0002	Ismeretlen hiba / Belső szerverhiba	Vegye fel a kapcsolatot az ügyfélszolgálattal

Bevált gyakorlatok

1. Vezesse be az OAuth 2.0 hitelesítést

FONTOS: Minden ügyfélnek át kell állnia az OAuth 2.0 hitelesítésre. Vezessen be megfelelő tokenkezelést:

A hozzáférési tokeneket tárolja a gyorsítótárban, és használja újra azok lejáratáig
Frissítse a tokeneket lejáratuk előtt (ajánlott: 60 másodperccel korábban)
Az ügyfél hitelesítő adatait biztonságosan tárolja (használjon környezeti változókat vagy titkosítókezelőt)
Soha ne naplózza és ne tegye közzé a hozzáférési tokeneket az ügyféloldali kódban

2. Használjon Request ID-ket

Mindig adjon meg egy egyedi RequestId-t (GUID formátumban) a végpontok közötti nyomonkövethetőség érdekében

3. Végrehajtás: Oldalszámozás

Nagy adatkészletek esetén használjon oldalszámozást az időtúllépések elkerülése érdekében

4. Tesztelés a Sandbox környezetben

Mindig tesztelje az integrációt a Test/Sandbox környezetben, mielőtt éles üzembe helyezné

SDK és kódpéldák

A Shell hivatalos SDK-kat és átfogó kódpéldákat biztosít a Card Management API-val való integráció felgyorsításához.

Elérhető SDK-nyelvek

Python - Teljes funkcionalitású SDK OAuth 2.0 támogatással
TypeScript - Típusbiztos SDK teljes típusdefiníciókkal
Java – Vállalati szintű SDK
C#/.NET – Teljes .NET-integráció
PHP - Könnyen használható PHP-könyvtár
Ruby - Ruby gem a zökkenőmentes integrációhoz

Hivatalos SDK-k és dokumentáció megtekintése

Támogatás és források

Technikai támogatás

Támogatás: Shell műszaki támogatás

Dokumentáció

Segítség

Ha kapcsolatba lép az ügyfélszolgálattal, adja meg a következőket:

A client_id azonosítóját (soha ne adja meg a client_secret-jét vagy az hozzáférési tokenjeit)
RequestId az API-válaszból
A kérés időbélyege
Környezet (Termelés/Teszt)

Utolsó frissítés: 2026. július 1.
Dokumentum verzió: 1.0
API verzió: 3.1.5