Vyberte svoj jazyk

Strojový preklad (Beta)

B2B Mobility Card Management 3.1.5

Získajte aktualizácie zmien stavu, údržby a verzie tohto API.

Shell B2B Mobility Card Management API – Príručka pre rýchly štart

Verzia API: 3.1.5 | Overovanie: OAuth 2.0 | Stav: Produkčné prostredie

Prehľad

Rozhranie API pre správu kariet Shell je rozhranie založené na REST, ktoré umožňuje vývojárom programovo spravovať palivové karty Shell. Toto rozhranie podporuje vyhľadávanie kariet, objednávanie, aktualizáciu stavu, zrušenie a rôzne ďalšie operácie spojené so správou kariet.

Poznámka: Táto príručka sa týka iba koncových bodov overovaných prostredníctvom OAuth 2.0 (základná cesta: /card-management/v1). Staršie koncové body s overovaním Basic Auth (/fleetmanagement/v1/card) nie sú zahrnuté, pretože sa postupne vyraďujú z prevádzky.

Kľúčové funkcie

  • Vyhľadávanie a filtrovanie palivových kariet pomocou flexibilných kritérií
  • Objednávanie nových kariet a sledovanie stavu objednávky
  • Blokovať, odblokovať a zrušiť karty
  • Aktualizovať doručovacie adresy kariet
  • Spravovať nastavenia automatického obnovenia kariet
  • Presúvanie kariet medzi skupinami kariet a účtami
  • Požiadať o pripomenutie PIN kódu

Dôležité upozornenie – OAuth 2.0

DÔLEŽITÉ: OAuth 2.0 je teraz štandardnou metódou overovania

  • Nové integrácie: Používajte OAuth 2.0 hneď od začiatku
  • Existujúce integrácie: Naplánujte si prechod na OAuth 2.0
  • Staršie metódy: Základné overovanie a kľúč API sa postupne vyraďujú

Obráťte sa na technickú podporu Shell, aby ste získali svoje prihlasovacie údaje pre OAuth 2.0 (client_id a client_secret).

Overovanie

OAuth 2.0 (štandardná metóda overovania)

Rozhranie API pre správu kariet Shell využíva postup overovania prostredníctvom prihlasovacích údajov klienta OAuth 2.0 na zabezpečené overenie.

UPOZORNENIE: Všetci zákazníci by mali zvážiť prechod na overovanie pomocou OAuth 2.0. Ide o odporúčanú a perspektívnu metódu overovania pre rozhranie API pre správu kariet Shell. Staršie metódy overovania sa postupne vyraďujú.

Postup OAuth 2.0

Krok 1: Získanie prístupového tokenu

Požiadajte o prístupový token z koncového bodu tokenov OAuth:

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

grant_type=client_credentials&client_id=vaše-id-klienta&client_secret=vaše-tajné-kľúče

Krok 2: Použitie prístupového tokenu v požiadavkách na API

Autorizácia: Bearer 
Content-Type: application/json

Správa tokenov

Osvedčené postupy pri správe tokenov:

  • Prístupové tokeny majú obmedzenú platnosť (zvyčajne 15 minút)
  • Implementujte ukladanie tokenov do vyrovnávacej pamäte, aby ste sa vyhli zbytočným požiadavkám na tokeny
  • Obnovte tokeny pred uplynutím ich platnosti, aby ste zaistili neprerušovanú prevádzku
  • Nikdy nezverejňujte svoj client_secret ani ho nevkladajte do kódu na strane klienta

Stratégia zavádzania OAuth 2.0

Prečo prejsť na OAuth 2.0?

Výhody v oblasti bezpečnosti:

  • Autentifikačný protokol podľa štandardov v odvetví
  • Časovo obmedzené prístupové tokeny znižujú bezpečnostné riziká
  • Pri každej požiadavke sa neprenášajú žiadne prihlasovacie údaje
  • Lepšia podpora rotácie a zrušenia tokenov

Prevádzkové výhody:

  • Vylepšená škálovateľnosť a výkon
  • Lepšie možnosti monitorovania a auditu
  • Zjednodušená správa prihlasovacích údajov
  • Integrácia pripravená na budúcnosť

Postup migrácie

Ak v súčasnosti používate staršie metódy overovania, postupujte podľa tohto postupu migrácie:

  1. Požiadajte o prihlasovacie údaje OAuth 2.0 od technickej podpory Shell
  2. Implementujte správu tokenov OAuth vo vašej aplikácii
  3. Dôkladne otestujte v testovacom/sandboxovom prostredí
  4. Spustite paralelné overovanie (OAuth + starý systém) počas prechodu
  5. Monitorujte a overte integráciu OAuth
  6. Po overení prejsť výlučne na OAuth
  7. Po úspešnej migrácii vyradte staré overovanie

Prostredia

API je k dispozícii v dvoch prostrediach:

Prostredie Základná URL Účel
Produkčné https://api.shell.com Produkčné prostredie
Test (Sandbox) https://api-test.shell.com/test Testovacie a vývojové prostredie

Tip: Vždy otestujte svoju integráciu v testovacom prostredí, než prejdete do produkčného prostredia.

Rýchly štart

1. Získajte svoje OAuth poverenia

2. Získanie prístupového tokenu

Najskôr si získajte svoj prístupový token OAuth:

Príklad použitia 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=vaše-klientské-ID&client_secret=vaše-klientské-tajomstvo"

Odpoveď:

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

3. Vytvorte svoju prvú požiadavku na API

Príklad: Vyhľadajte aktívne karty

Príklad s 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
}'

Príklad odpovede:

{
    "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,
            "Názov typu karty": "CZ SFA NAT SIN - CHIP",
 "Kód krajiny vydavateľa": "CZ",
 "Dátum vytvorenia": "20220810 23:53:25",
            "DriverName": "SHELL973169581",
 "EffectiveDate": "20220810",
 "ExpiryDate": "20260831",
            "FleetIdInput": true,
 "IsCRT": false,
 "IsFleet": true,
 "IsInternational": 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 – Všetky palivové produkty, automobilové príslušenstvo a TMF",
            "Reason": "Naplánované na odblokovanie",
 "ReissueSetting": "True",
 "StatusDescription": "Aktívne",
 "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"
}

Referencia koncových bodov API

Vyhľadávanie a načítanie kariet

Koncový bod Metóda Popis
/card-management/v1/search POST Vyhľadávanie kariet pomocou flexibilných filtrov (OAuth 2.0)
/card-management/v1/details POST Načítanie podrobností o jednej palivovej karte (OAuth 2.0)

Bežné prípady použitia:

  • Vyhľadávanie podľa stavu karty (AKTÍVNA, ZABLOKOVANÁ, PREKROČENÁ PLATNOSŤ atď.)
  • Filtrovanie podľa mena vodiča alebo evidenčného čísla vozidla
  • Vyhľadávanie podľa PAN (posledné 4 číslice)
  • Nájsť karty, ktorých platnosť vyprší za X dní

Prehľad kariet

Koncový bod Metóda Popis
/card-management/v1/summary POST Získanie súhrnných informácií o palivových kartách (OAuth 2.0)

Vrátené údaje:

  • Celkový počet kariet podľa stavu
  • Súhrnné štatistiky podľa typu karty
  • Rozdelenie na aktívne a neaktívne karty

Objednávanie kariet

Koncový bod Metóda Popis
/card-management/v1/ordercard POST Objednávka jednej alebo viacerých palivových kariet (OAuth 2.0)
/card-management/v1/ordercardenquiry POST Skontrolujte stav objednávky karty (OAuth 2.0)

Požadované informácie na objednávku kariet:

  • ColCoCode (kód inkasnej spoločnosti)
  • Číslo platiteľa alebo ID platiteľa
  • Číslo účtu
  • Typ a konfigurácia karty
  • Údaje o doručovacej adrese

Správa stavu karty

Koncový bod Metóda Popis
/card-management/v1/updatestatus POST Blokovať, odblokovanie alebo zrušenie kariet (OAuth 2.0)
/card-management/v1/schedulecardblock POST Naplánovanie požiadaviek na zablokovanie/odblokovanie kariet (OAuth 2.0)

Akcie so stavom:

  • BLOKOVAŤ – Dočasne zablokovať kartu
  • ODBLOKOVAŤ – Opätovne aktivovať zablokovanú kartu
  • POŠKODENÁ - Nahlásenie poškodenia karty a žiadosť o náhradnú kartu
  • TEMP_BLOCK_CUSTOMER - Dočasné zablokovanie iniciované zákazníkom
  • TEMP_BLOCK_SHELL - Dočasné zablokovanie iniciované spoločnosťou Shell

UPOZORNENIE: Zrušenie karty je trvalé a nemožno ho vrátiť späť.

Ďalšie koncové body

Kategória Koncový bod Metóda Popis
Zrušenie /card-management/v1/cancel POST Zrušiť jednu alebo viacero kariet
Presun kariet /card-management/v1/move POST Presun kariet do inej skupiny kariet alebo na iný účet
Správa PIN kódu /card-management/v1/pinreminder POST Žiadosť o pripomenutie PIN kódu pre kartu
Doručovacia adresa /card-management/v1/deliveryaddressupdate POST Aktualizovať doručovaciu adresu karty
Automatické obnovenie /card-management/v1/autorenew POST Aktualizácia indikátora opätovného vydania

Príklady použitia

Príklad 1: Vyhľadávanie kariet, ktorých platnosť čoskoro vyprší

POST /card-management/v1/search

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

Príklad 2: Dočasné zablokovanie karty

POST /card-management/v1/updatestatus

{

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

  ]
}

Príklad 3: Zrušenie kariet

POST /card-management/v1/cancel

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

Spracovanie chýb

Bežné kódy chýb

Stav HTTP Kód chyby Popis Riešenie
200 N/A Stav: ÚSPECH N/A
400 E0001 Chyba overenia Skontrolujte parametre požiadavky
401 E0003 Neautorizované Overte platnosť tokenu OAuth
403 E0003 Zakázané Skontrolujte oprávnenia používateľa
404 E0005 Zdroje neboli nájdené Overte, či URL koncového bodu a zdroj existujú
500 E0002 Neznáma chyba / Vnútorná chyba servera Kontaktujte podporu

Osvedčené postupy

1. Prejdite na overovanie pomocou OAuth 2.0

DÔLEŽITÉ: Všetci zákazníci by mali prejsť na overovanie pomocou OAuth 2.0. Zavádzajte správne riadenie tokenov:

  • Ukladajte prístupové tokeny do vyrovnávacej pamäte a opakovane ich používajte až do vypršania platnosti
  • Obnovujte tokeny pred vypršaním ich platnosti (odporúča sa 60 sekúnd predtým)
  • Bezpečne ukladajte prihlasovacie údaje klienta (používajte premenné prostredia alebo správcu tajných kľúčov)
  • Nikdy nezaznamenávajte ani nezverejňujte prístupové tokeny v kóde na strane klienta

2. Používajte identifikátory požiadaviek

Vždy uvádzajte jedinečný identifikátor požiadavky (RequestId vo formáte GUID) na zabezpečenie sledovateľnosti od začiatku do konca

3. Implementujte stránkovanie

Pri veľkých dátových súboroch používajte stránkovanie, aby ste predišli časovým limitom

4. Testujte v prostredí Sandbox

Vždy otestujte integráciu v testovacom/Sandbox prostredí pred prechodom do produkcie

SDK a ukážky kódu

Shell poskytuje oficiálne SDK a komplexné ukážky kódu na urýchlenie vašej integrácie s Card Management API.

Dostupné jazyky SDK

  • Python - Plnofunkčné SDK s podporou OAuth 2.0
  • TypeScript - Typovo bezpečné SDK s úplnými definíciami typov
  • Java - SDK na podnikovej úrovni
  • C#/.NET - Kompletná integrácia s .NET
  • PHP - Jednoduchá knižnica pre PHP
  • Ruby - Ruby gem pre bezproblémovú integráciu

Zobraziť oficiálne SDK a dokumentáciu

Podpora a zdroje

Technická podpora

Dokumentácia

Pomoc

Pri kontaktovaní podpory uveďte:

  1. Vaše client_id (nikdy neposkytujte svoje client_secret ani prístupové tokeny)
  2. RequestId z odpovede API
  3. Časová pečiatka požiadavky
  4. Prostredie (produkčné/testovacie)

Posledná aktualizácia: 1. júla 2026
Verzia dokumentu: 1.0
Verzia API: 3.1.5

O nás

Portál Shell Developer Portal pomáha partnerom pri integrácii s rozhraniami API spoločnosti Shell a pri premene nápadov na riešenia pripravené na nasadenie do prevádzky.

Logo Shell

Kontakt

Kontaktujte nás

Prihláste sa do svojho konta

Opýtajte sa asistenta AI na rozhrania API spoločnosti Shell a produkty API