API za upravljanje kartic Shell B2B Mobility – Priročnik za hiter začetek
Različica API-ja: 3.1.5 | Preverjanje pristnosti: OAuth 2.0 | Stanje: Produkcijska različica
Pregled
API za upravljanje kartic Shell je API na podlagi REST, ki razvijalcem omogoča programsko upravljanje kartic za gorivo Shell. API podpira iskanje kartic, naročanje, posodobitve stanja, preklic in različne druge operacije upravljanja kartic.
Opomba: Ta vodnik obravnava le končne točke, avtentificirane prek OAuth 2.0 (osnovna pot: /card-management/v1). Stare končne točke z avtentifikacijo Basic Auth (/fleetmanagement/v1/card) niso vključene, saj se postopno umikajo iz uporabe.
Ključne funkcije
- Iskanje in filtriranje kartic za gorivo s prilagodljivimi merili
- Naročanje novih kartic in spremljanje stanja naročila
- Blokiranje, odblokirajte in prekličite kartice
- Posodobi naslove za dostavo kartic
- Upravljaj nastavitve samodejnega podaljševanja kartic
- Premikanje kartic med skupinami kartic in računi
- Zahteva za opomnike o PIN-kodi
Pomembno obvestilo – OAuth 2.0
POMEMBNO: OAuth 2.0 je zdaj standardna metoda avtentifikacije
- Nove integracije: Uporabljajte OAuth 2.0 že od samega začetka
- Obstoječe integracije: Načrtujte prehod na OAuth 2.0
- Starejše metode: Osnovno avtentificiranje in API-ključ se postopno ukinjata
Obrnite se na tehnično podporo Shell, da pridobite svoje poverilnice OAuth 2.0 (client_id in client_secret).
Preverjanje pristnosti
OAuth 2.0 (standardna metoda preverjanja pristnosti)
API za upravljanje kartic Shell uporablja postopek OAuth 2.0 Client Credentials za varno preverjanje pristnosti.
OPOZORILO: Vsi uporabniki naj načrtujejo prehod na avtentifikacijo OAuth 2.0. To je priporočena in prihodnosti odporna metoda avtentifikacije za API za upravljanje kartic Shell. Stare metode avtentifikacije se postopno opuščajo.
Postopek OAuth 2.0
Korak 1: Pridobite dostopni žeton
Zahtevajte dostopni žeton pri končni točki za žetone OAuth:
POST /oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=vaša-ID-stranke&client_secret=vaša-skrivnost-stranke
Korak 2: Uporaba dostopnega žetona v zahtevkih API
Authorization: Bearer Content-Type: application/json
Upravljanje žetonov
Najboljše prakse za upravljanje žetonov:
- Dostopni žetoni imajo omejeno veljavnost (običajno 15 minut)
- Vzpostavite shranjevanje žetonov v predpomnilniku, da se izognete nepotrebnim zahtevkom za žetone
- Osvežite žetone pred iztekom veljavnosti, da zagotovite neprekinjeno delovanje storitve
- Nikoli ne delite svojega client_secret ali ga vstavljajte v kodo na strani odjemalca
Strategija uvedbe OAuth 2.0
Zakaj preiti na OAuth 2.0?
Varnostne prednosti:
- Protokol za avtentifikacijo po industrijskih standardih
- Časovno omejeni dostopni žetoni zmanjšujejo varnostna tveganja
- Pri vsakem zahtevku se ne prenašajo nobena pooblastila
- Boljša podpora za menjavo in preklic žetonov
Operativne prednosti:
- Izboljšana skalabilnost in zmogljivost
- Boljše možnosti spremljanja in revizije
- Poenostavljeno upravljanje poverilnic
- Integracija, pripravljena na prihodnost
Pot migracije
Če trenutno uporabljate zastarele metode avtentifikacije, sledite tej poti migracije:
- Zahtevajte poverilnice OAuth 2.0 na tehnične podpore Shell
- V svoji aplikaciji implementirajte upravljanje OAuth-tokenov
- Temeljito preizkusite v testnem/sandbox okolju
- Med prehodom izvajajte vzporedno avtentifikacijo (OAuth + stari način) med prehodom
- Spremljajte in preverite integracijo OAuth
- Preklopite na izključno OAuth po potrditvi
- Po uspešni migraciji razveljavite staro avtentifikacijo
Okolja
API je na voljo v dveh okoljih:
| Okolje | Osnovni URL | Namen |
|---|---|---|
| Proizvodno | https://api.shell.com | Proizvodno okolje v živo |
| Testno (Sandbox) | https://api-test.shell.com/test | Testno in razvojno okolje |
Nasvet: Svojo integracijo vedno preizkusite v testnem okolju, preden preidete v produkcijo.
Hiter začetek
1. Pridobite svoje OAuth-pooblastila
- Obrnite se na tehnične podpore Shell
- Zahtevajte poverilnice OAuth 2.0 (client_id in client_secret)
- Preberite pogoje uporabe
2. Pridobite dostopni žeton
Najprej pridobite svoj OAuth dostopni žeton:
Primer 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ša-ID-odjemalca&client_secret=vaša-skrivnost-odjemalca"
Odgovor:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 899
}3. Pošljite svojo prvo zahtevo API
Primer: Iskanje aktivnih kartic
Primer 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
}'Primer odgovora:
{
"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",
"Datum poteka veljavnosti": "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 – Vsi izdelki na področju goriv, avtomobilski izdelki in TMF",
"Reason": "Načrtovano za odblokiranje",
"ReissueSetting": "True",
"StatusDescription": "Aktivno",
"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"
}Referenca končnih točk API-ja
Iskanje in pridobivanje kartic
| Končna točka | Metoda | Opis |
|---|---|---|
| /card-management/v1/search | POST | Iskanje kartic s prilagodljivimi filtri (OAuth 2.0) |
| /card-management/v1/details | POST | Pridobivanje podrobnosti o posamezni kartici za gorivo (OAuth 2.0) |
Pogosti primeri uporabe:
- Iskanje po statusu kartice (AKTIVNA, BLOKIRANA, POTEKLA, itd.)
- Filtriranje po imenu voznika ali registrski številki vozila
- Iskanje po PAN (zadnje 4 številke)
- Poišči kartice, ki potečejo čez X dni
Povzetek kartice
| Končna točka | Metoda | Opis |
|---|---|---|
| /card-management/v1/summary | POST | Pridobi splošni povzetek kartic za gorivo (OAuth 2.0) |
Vrne:
- Skupno število kartic po statusu
- Povzetek statističnih podatkov po vrsti kartice
- Razčlenitev po aktivnih in neaktivnih karticah
Naročanje kartic
| Končna točka | Metoda | Opis |
|---|---|---|
| /card-management/v1/ordercard | POST | Naročanje ene ali več kartic za gorivo (OAuth 2.0) |
| /card-management/v1/ordercardenquiry | POST | Preverjanje stanja naročila kartice (OAuth 2.0) |
Potrebne informacije za naročanje kartic:
- ColCoCode (koda podjetja za zbiranje)
- Številka plačnika ali ID plačnika
- Številka računa
- Vrsta kartice in konfiguracija
- Podrobnosti o naslovu za dostavo
Upravljanje stanja kartice
| Končna točka | Metoda | Opis |
|---|---|---|
| /card-management/v1/updatestatus | POST | Blokiranje, odblokiranje ali preklic kartic (OAuth 2.0) |
| /card-management/v1/schedulecardblock | POST | Načrtovanje zahtevkov za blokiranje/odblokiranje kartic (OAuth 2.0) |
Ukrepi glede stanja:
- BLOKIRAJ – Začasno blokiraj kartico
- ODBLOKIRAJ – Ponovno aktiviraj blokirano kartico
- POŠKODOVANA - Prijava poškodovane kartice in zahteva za zamenjavo
- TEMP_BLOCK_CUSTOMER – Začasna blokada na pobudo stranke
- TEMP_BLOCK_SHELL – Začasna blokada, ki jo sproži Shell
OPOZORILO: Preklic kartice je trajen in ga ni mogoče preklicati.
Dodatne končne točke
| Kategorija | Končna točka | Metoda | Opis |
|---|---|---|---|
| Preklic | /card-management/v1/cancel | POST | Preklic ene ali več kartic |
| Premestitev kartic | /card-management/v1/move | POST | Premestitev kartic v drugo skupino kartic ali na drug račun |
| Upravljanje PIN-kode | /card-management/v1/pinreminder | POST | Zahteva za opomnik PIN-kode za kartico |
| Naslov za dostavo | /card-management/v1/deliveryaddressupdate | POST | Posodobitev naslova za dostavo kartice |
| Samodejno podaljšanje | /card-management/v1/autorenew | POST | Posodobi indikator ponovne izdaje |
Primeri uporabe
Primer 1: Iskanje kartic, ki kmalu potečejo
POST /card-management/v1/search
{
"Filters": {
"PayerNumber": "CZ00000927",
"AccountNumber": "CZ00000927",
"ColCoCode": 32,
"CardStatus": [
"Active"
],
"ExpiringInDays" : 70
},
"Page": 1,
"PageSize": 1
}Primer 2: Začasna blokada kartice
POST /card-management/v1/updatestatus
{
"Cards": [
{
"CardId": 125,
"ColCoCode": 86,
"PayerNumber": "PH50000843",
},
"ReasonId": 1236,
"ReasonText": "Odblokiraj",
"TargetStatus": "Odblokiraj"
]
}Primer 3: Preklic kartic
POST /card-management/v1/cancel
{
"Cards": [
{
"CardId": 125,
"CardExpiryDate": "20231231",
"ColCoCode": 86,
"PayerNumber": "PH50000843",
}
],
"ReasonText": "Izgubljena",
"RequestId": "1"
}Obravnavanje napak
Pogoste kode napak
| HTTP-stanje | Koda napake | Opis | Rešitev |
|---|---|---|---|
| 200 | N/A | Stanje: USPEŠNO | N/A |
| 400 | E0001 | Napaka pri preverjanju veljavnosti | Preverite parametre zahtevka |
| 401 | E0003 | Neavtorizirano | Preverite, ali je OAuth-žeton veljaven |
| 403 | E0003 | Prepovedano | Preverite uporabniška dovoljenja |
| 404 | E0005 | Vire ni mogoče najti | Preverite, ali URL končne točke in vir obstajata |
| 500 | E0002 | Neznana napaka / Notranja napaka strežnika | Obrnite se na podporo |
Najboljše prakse
1. Uvedite avtentifikacijo OAuth 2.0
POMEMBNO: Vsi uporabniki morajo preiti na avtentifikacijo OAuth 2.0. Uvedite ustrezno upravljanje žetonov:
- Shranjujte dostopne žetone v predpomnilniku in jih ponovno uporabite do izteka veljavnosti
- Osvežite žetone, preden potečejo (priporočljivo 60 sekund pred iztekom)
- Varno shranjujte poverilnice odjemalca (uporabite spremenljivke okolja ali upravitelja skrivnosti)
- Nikoli ne beležite ali razkrivajte dostopnih žetonov v kodi na strani odjemalca
2. Uporabite ID-je zahtevkov
Vedno vključite edinstven ID zahtevka (v formatu GUID) za sledljivost od začetka do konca
3. Izvedite stranjenje
Pri velikih naborih podatkov uporabite stranjenje, da se izognete časovnim omejitvam
4. Testirajte v okolju Sandbox
Integracijo vedno preizkusite v testnem/Sandbox okolju, preden preidete v produkcijo
Primeri SDK-jev in kode
Shell ponuja uradne SDK-je in izčrpne primere kode za pospešitev vaše integracije z API-jem za upravljanje kartic.
Razpoložljivi jeziki SDK
- Python - SDK s polno funkcionalnostjo in podporo za OAuth 2.0
- TypeScript - Tipsko varen SDK s popolnimi definicijami tipov
- Java - SDK za podjetja
- C#/.NET - Popolna integracija z .NET
- PHP - Enostavna knjižnica za PHP
- Ruby - Ruby gem za nemoteno integracijo
Oglejte si uradne SDK-je in dokumentacijo
Podpora in viri
Tehnična podpora
- Podpora: Tehnična podpora Shell
Dokumentacija
Pomoč
Ko se obrnete na podporo, navedite:
- Vaš client_id (nikoli ne delite svojega client_secret ali dostopnih žetonov)
- RequestId iz odgovora API-ja
- Časovni žig zahtevka
- Okolje (Proizvodnja/Testiranje)
Zadnja posodobitev: 1. julij 2026
Različica dokumenta: 1.0
Različica API-ja: 3.1.5
