Vyberte jazyk

Strojově přeloženo (Beta)

B2B Mobility Card Management 3.1.5

Získejte změny stavu, aktualizace údržby a verze tohoto API.

Shell B2B Mobility Card Management API – Průvodce rychlým startem

Verze API: 3.1.5 | Ověřování: OAuth 2.0 | Stav: Produkční

Přehled

API pro správu karet Shell je API založené na REST, které vývojářům umožňuje programově spravovat palivové karty Shell. API podporuje vyhledávání karet, objednávání, aktualizace stavu, zrušení a různé další operace spojené se správou karet.

Poznámka: Tato příručka se zabývá pouze koncovými body ověřovanými pomocí OAuth 2.0 (základní cesta: /card-management/v1). Starší koncové body s ověřováním Basic Auth (/fleetmanagement/v1/card) nejsou zahrnuty, protože jsou postupně vyřazovány z provozu.

Klíčové funkce

  • Vyhledávání a filtrování palivových karet podle flexibilních kritérií
  • Objednání nových karet a sledování stavu objednávky
  • Zablokujte, odblokujte a zrušte karty
  • Aktualizovat doručovací adresy karet
  • Správa nastavení automatického prodloužení platnosti karet
  • Přesun karet mezi skupinami karet a účty
  • Požádat o připomenutí PIN kódu

Důležité upozornění – OAuth 2.0

DŮLEŽITÉ: OAuth 2.0 je nyní standardní metodou ověřování

  • Nové integrace:Používejte OAuth 2.0 od samého začátku
  • Stávající integrace: Naplánujte si přechod na OAuth 2.0
  • Starší metody: Základní ověřování a API klíč budou postupně vyřazeny

Kontaktujte technickou podporu Shell, abyste získali své přihlašovací údaje pro OAuth 2.0 (client_id a client_secret).

Ověřování

OAuth 2.0 (standardní metoda ověřování)

Rozhraní API pro správu karet Shell využívá proces OAuth 2.0 Client Credentials pro bezpečné ověřování.

VAROVÁNÍ: Všichni zákazníci by měli plánovat přechod na ověřování pomocí OAuth 2.0. Jedná se o doporučenou a do budoucna perspektivní metodu ověřování pro rozhraní API pro správu karet Shell. Starší metody ověřování jsou postupně vyřazovány z provozu.

Postup OAuth 2.0

Krok 1: Získejte přístupový token

Požádejte o přístupový token z koncového bodu tokenů 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-tajemství-klienta

Krok 2: Použití přístupového tokenu v požadavcích na API

Authorization: Bearer 
Content-Type: application/json

Správa tokenů

Osvědčené postupy pro správu tokenů:

  • Přístupové tokeny mají omezenou dobu platnosti (obvykle 15 minut)
  • Implementujte ukládání tokenů do mezipaměti, abyste se vyhnuli zbytečným žádostem o tokeny
  • Obnovte tokeny před vypršením platnosti, abyste zajistili nepřerušenou službu
  • Nikdy nesdílejte svůj client_secret ani jej nevkládat do kódu na straně klienta

Strategie zavedení OAuth 2.0

Proč přejít na OAuth 2.0?

Výhody z hlediska bezpečnosti:

  • Autentizační protokol odpovídající průmyslovému standardu
  • Přístupové tokeny s časovým omezením snižují bezpečnostní rizika
  • Při každém požadavku se nepřenášejí žádné přihlašovací údaje
  • Lepší podpora rotace a zrušení tokenů

Provozní výhody:

  • Vylepšená škálovatelnost a výkon
  • Lepší možnosti monitorování a auditu
  • Zjednodušená správa přihlašovacích údajů
  • Integrace připravená na budoucnost

Cesta migrace

Pokud v současné době používáte starší metody ověřování, postupujte podle této cesty migrace:

  1. Vyžádejte si přihlašovací údaje OAuth 2.0 od technické podpory Shell
  2. Implementujte správu tokenů OAuth ve vaší aplikaci
  3. Důkladně otestujte v testovacím/sandboxovém prostředí
  4. Během přechodu provádějte paralelní ověřování (OAuth + starší způsob) během přechodu
  5. Sledujte a ověřte integraci OAuth
  6. Po ověření přejít výhradně na OAuth
  7. Po úspěšné migraci vyřaďte staré ověřování

Prostředí

API je k dispozici ve dvou prostředích:

Prostředí Základní URL Účel
Produkční https://api.shell.com Provozní prostředí
Testovací (Sandbox) https://api-test.shell.com/test Testovací a vývojové prostředí

Tip: Vždy otestujte svou integraci v testovacím prostředí, než přejdete do produkčního prostředí.

Rychlý start

1. Získejte své přihlašovací údaje OAuth

2. Získejte přístupový token

Nejprve si získejte svůj přístupový token OAuth:

Příklad 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-id-klienta&client_secret=vaše-tajemství-klienta"

Odpověď:

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

3. Proveďte svůj první požadavek na API

Příklad: Vyhledání aktivních karet

Pří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
}'

Příklad odpovědi:

{
    "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",
 "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šechny palivové produkty, automobilové doplňky a TMF",
 "Reason": "Naplánováno k odblokování",
            "ReissueSetting": "True",
 "StatusDescription": "Aktivní",
 "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": "Palivová karta"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

Referenční příručka k koncovým bodům API

Vyhledávání a načítání karet

Koncový bod Metoda Popis
/card-management/v1/search POST Vyhledávání karet pomocí flexibilních filtrů (OAuth 2.0)
/card-management/v1/details POST Načtení podrobností o jedné palivové kartě (OAuth 2.0)

Běžné případy použití:

  • Vyhledávání podle stavu karty (AKTIVNÍ, BLOKOVÁNA, PROŠLÁ, atd.)
  • Filtrovat podle jména řidiče nebo registračního čísla vozidla
  • Vyhledávání podle PAN (poslední 4 číslice)
  • Najít karty, jejichž platnost vyprší za X dní

Přehled karet

Koncový bod Metoda Popis
/card-management/v1/summary POST Získání souhrnných informací o palivových kartách (OAuth 2.0)

Vrací:

  • Celkový počet karet podle stavu
  • Souhrnné statistiky podle typu karty
  • Rozdělení na aktivní a neaktivní

Objednávání karet

Koncový bod Metoda Popis
/card-management/v1/ordercard POST Objednání jedné nebo více palivových karet (OAuth 2.0)
/card-management/v1/ordercardenquiry POST Kontrola stavu objednávky karet (OAuth 2.0)

Požadované informace pro objednání karet:

  • ColCoCode (kód inkasní společnosti)
  • Číslo plátce nebo ID plátce
  • Číslo účtu
  • Typ a konfigurace karty
  • Údaje o doručovací adrese

Správa stavu karty

Koncový bod Metoda Popis
/card-management/v1/updatestatus POST Zablokování, odblokování nebo zrušení karet (OAuth 2.0)
/card-management/v1/schedulecardblock POST Naplánování požadavků na zablokování/odblokování karet (OAuth 2.0)

Akce se stavem:

  • BLOKOVAT – Dočasně zablokovat kartu
  • ODBLOKOVAT – Znovu aktivovat zablokovanou kartu
  • POŠKOZENÁ - Nahlásit poškození karty a požádat o náhradní
  • DOČASNÉ ZABLOKOVÁNÍ ZÁKAZNÍKEM - Dočasné zablokování z podnětu zákazníka
  • TEMP_BLOCK_SHELL – Dočasné zablokování iniciované shell

UPOZORNĚNÍ: Zrušení karty je trvalé a nelze jej vrátit zpět.

Další koncové body

Kategorie Koncový bod Metoda Popis
Zrušení /card-management/v1/cancel POST Zrušit jednu nebo více karet
Přesun karet /card-management/v1/move POST Přesun karet do jiné skupiny karet nebo na jiný účet
Správa PIN kódu /card-management/v1/pinreminder POST Žádost o připomenutí PIN kódu pro kartu
Doručovací adresa /card-management/v1/deliveryaddressupdate POST Aktualizace doručovací adresy karty
Automatické prodloužení /card-management/v1/autorenew POST Aktualizace indikátoru opětovného vydání

Příklady použití

Příklad 1: Vyhledání karet s blížícím se datem platnosti

POST /card-management/v1/search

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

Příklad 2: Dočasné zablokování karty

POST /card-management/v1/updatestatus

{

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

  ]
}

Příklad 3: Zrušení karet

POST /card-management/v1/cancel

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

Zpracování chyb

Běžné kódy chyb

Stav HTTP Kód chyby Popis Řešení
200 N/A Stav: ÚSPĚCH N/A
400 E0001 Chyba ověření Zkontrolujte parametry požadavku
401 E0003 Neoprávněný přístup Ověřte platnost tokenu OAuth
403 E0003 Přístup zakázán Zkontrolujte oprávnění uživatele
404 E0005 Zdroj nebyl nalezen Ověřte, zda existuje URL koncového bodu a zda zdroj existuje
500 E0002 Neznámá chyba / Vnitřní chyba serveru Kontaktujte podporu

Osvědčené postupy

1. Přechod na ověřování OAuth 2.0

DŮLEŽITÉ: Všichni zákazníci by měli přejít na ověřování OAuth 2.0. Zaveďte správnou správu tokenů:

  • Ukládejte přístupové tokeny do mezipaměti a opakovaně je používejte až do vypršení platnosti
  • Obnovujte tokeny před vypršením jejich platnosti (doporučeno 60 sekund předem)
  • Ukládejte přihlašovací údaje klienta bezpečně (používejte proměnné prostředí nebo správce tajných klíčů)
  • Nikdy nezaznamenávejte ani nezveřejňujte přístupové tokeny v kódu na straně klienta

2. Používejte ID požadavků

Vždy uvádějte jedinečné ID požadavku (ve formátu GUID) pro sledovatelnost od začátku do konce

3. Implementujte stránkování

U velkých datových sad používejte stránkování, abyste předešli vypršení časového limitu

4. Testujte v prostředí Sandbox

Integraci vždy otestujte v testovacím/Sandboxovém prostředí před přesunem do produkčního prostředí

SDK a příklady kódu

Shell poskytuje oficiální SDK a komplexní příklady kódu, které urychlí vaši integraci s rozhraním API pro správu karet.

Dostupné jazyky SDK

  • Python - Plně funkční SDK s podporou OAuth 2.0
  • TypeScript – Typově bezpečné SDK s úplnými definicemi typů
  • Java - SDK na podnikové úrovni
  • C#/.NET - Kompletní integrace s .NET
  • PHP - Snadno použitelná knihovna pro PHP
  • Ruby - Ruby gem pro hladkou integraci

Zobrazit oficiální SDK a dokumentaci

Podpora a zdroje

Technická podpora

Dokumentace

Pomoc

Při kontaktování podpory uveďte:

  1. Vaše client_id (nikdy nesdílejte své client_secret ani přístupové tokeny)
  2. RequestId z odpovědi API
  3. Časové razítko požadavku
  4. Prostředí (Produkční/Testovací)

Poslední aktualizace: 1. července 2026
Verze dokumentu: 1.0
Verze API: 3.1.5

O nás

Portál Shell Developer Portal pomáhá partnerům se zapojením do API společnosti Shell a s přeměnou nápadů na řešení připravená k nasazení do produkčního prostředí.

Logo Shell

Kontakt

Kontaktujte nás

Přihlášení k účtu

Zeptejte se asistenta AI na API a API produkty společnosti Shell