Shell B2B Mobility Card Management API - Snelstartgids

API-versie: 3.1.5 | Authenticatie: OAuth 2.0 | Status: Productie

Overzicht

De Shell Card Management API is een op REST gebaseerde API waarmee ontwikkelaars Shell-tankkaarten programmatisch kunnen beheren. De API ondersteunt het zoeken naar kaarten, het bestellen ervan, statusupdates, annulering en diverse andere beheeracties met betrekking tot kaarten.

Opmerking: Deze handleiding behandelt alleen eindpunten die via OAuth 2.0 worden geauthenticeerd (basispad: /card-management/v1). Oudere Basic Auth-eindpunten (/fleetmanagement/v1/card) zijn niet opgenomen, aangezien deze geleidelijk worden uitgefaseerd.

Belangrijkste functies

• Zoek en filter tankkaarten met flexibele criteria
• Bestel nieuwe kaarten en volg de bestelstatus
• Kaarten blokkeren, deblokkeren en opzeggen
• Leveringsadressen voor kaarten bijwerken
• Instellingen voor automatische verlenging van kaarten beheren
• Kaarten verplaatsen tussen kaartgroepen en accounts
• PIN-herinneringen aanvragen

Belangrijke mededeling - OAuth 2.0

BELANGRIJK: OAuth 2.0 is nu de standaard authenticatiemethode

• Nieuwe integraties: Gebruik OAuth 2.0 vanaf het begin
• Bestaande integraties: Plan je migratie naar OAuth 2.0
• Verouderde methoden: Basic Auth en API-sleutel worden geleidelijk afgeschaft

Neem contact op met Shell Technical Support om uw OAuth 2.0-inloggegevens (client_id en client_secret) te verkrijgen.

Authenticatie

OAuth 2.0 (standaard authenticatiemethode)

De Shell Card Management API maakt gebruik van de OAuth 2.0 Client Credentials-flow voor veilige authenticatie.

WAARSCHUWING: Alle klanten moeten plannen maken om over te stappen op OAuth 2.0-authenticatie. Dit is de aanbevolen en toekomstbestendige authenticatiemethode voor de Shell Card Management API. Oude authenticatiemethoden worden geleidelijk afgeschaft.

OAuth 2.0-stroom

Stap 1: Verkrijg een toegangstoken

Vraag een toegangstoken aan bij het OAuth-token-eindpunt:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=uw-client-id&client_secret=uw-client-secret

Stap 2: Gebruik het toegangstoken in API-verzoeken

Authorization: Bearer 
Content-Type: application/json

Tokenbeheer

Aanbevolen werkwijzen voor tokenbeheer:

• Toegangstokens hebben een beperkte geldigheidsduur (meestal 15 minuten)
• Implementeer token-caching om onnodige tokenverzoeken te voorkomen
• Vernieuw tokens vóór het verstrijken van de geldigheidsduur om een ononderbroken dienstverlening te garanderen
• Deel je client_secret nooit en verwerk het niet in client-side code

OAuth 2.0-implementatiestrategie

Waarom overstappen op OAuth 2.0?

Beveiligingsvoordelen:

• Authenticatieprotocol volgens de industriestandaard
• Toegangstokens met beperkte geldigheidsduur verminderen beveiligingsrisico’s
• Bij elk verzoek worden geen inloggegevens verzonden
• Betere ondersteuning voor het rouleren en intrekken van tokens

Operationele voordelen:

• Verbeterde schaalbaarheid en prestaties
• Betere monitoring- en auditmogelijkheden
• Vereenvoudigd beheer van inloggegevens
• Toekomstbestendige integratie

Migratietraject

Als u momenteel verouderde authenticatiemethoden gebruikt, volg dan dit migratietraject:

1. Vraag OAuth 2.0-inloggegevens aan via de technische ondersteuning van Shell
2. Implementeer OAuth-tokenbeheer in uw applicatie
3. Grondig testen in de test-/sandbox-omgeving
4. Parallelle authenticatie uitvoeren (OAuth + legacy) tijdens de overgang
5. Controleer en valideer de OAuth-integratie
6. Schakel over naar uitsluitend OAuth zodra deze is gevalideerd
7. Verouderde authenticatie buiten gebruik stellen na succesvolle migratie

Omgevingen

De API is beschikbaar in twee omgevingen:

Tip: Test je integratie altijd in de Testomgeving voordat je naar productie overgaat.

Snel aan de slag

1. Verkrijg je OAuth-inloggegevens

• Neem contact op met de technische ondersteuning van Shell
• Vraag OAuth 2.0-inloggegevens aan (client_id en client_secret)
• Bekijk de gebruiksvoorwaarden

2. Verkrijg een toegangstoken

Verkrijg eerst je OAuth-toegangstoken:

cURL-voorbeeld:

curl -X POST https://api-test.shell.com/test/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=je-client-id&client_secret=je-client-secret"

Antwoord:

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

3. Doe je eerste API-verzoek

Voorbeeld: Zoeken naar actieve kaarten

cURL-voorbeeld:

curl -X POST https://api-test.shell.com/test/card-management/v1/search \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"Filters": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"]
},
"Page": "1",
"PageSize": "50"
}'

Voorbeeld van een antwoord:

{
"RequestId": "233e4567-e89b-12d3-a456-426614174000",
"Status": "SUCCESS",
"Data": [
{
"CardId": 125,
"PAN": "7002861007636000020",
"MaskedPAN": "7002861**000020",
"DriverName": "ROBERT SMITH",
"VehicleRegistrationNumber": "MV65YLH",
"Statusbeschrijving": "Actief",
"Vervaldatum": "20250531",
"Kaarttypecode": "7077861",
"Kaarttypenaam": "Shell-kaart"
}
],
"Pagina": 1,
"Paginagrootte": 50,
"Totaal aantal pagina's": 1,
"TotalRecords": 1
}

Referentie API-eindpunten

Kaarten zoeken en ophalen

Veelvoorkomende gebruiksscenario’s:

• Zoeken op kaartstatus (ACTIEF, GEBLOKKEERD, VERLOPEN, enz.)
• Filteren op bestuurdersnaam of kenteken
• Zoeken op PAN (laatste 4 cijfers)
• Kaarten zoeken die over X dagen verlopen

Kaartoverzicht

Retourneert:

• Totaal aantal kaarten per status
• Overzichtstatistieken per kaarttype
• Uitsplitsing actief versus inactief

Kaarten bestellen

Vereiste informatie voor het bestellen van kaarten:

• ColCoCode (code van het incassobedrijf)
• Betalingsnummer of Betaler-ID
• Rekeningnummer
• Kaarttype en configuratie
• Gegevens afleveradres

Beheer kaartstatus

Statusacties:

• BLOKKEREN - Een kaart tijdelijk blokkeren
• DEBLOKKEREN - Een geblokkeerde kaart weer activeren
• BESCHADIGD - Een kaart als beschadigd melden en vervanging aanvragen
• TEMP_BLOCK_CUSTOMER - Door de klant geïnitieerde tijdelijke blokkering
• TEMP_BLOCK_SHELL - Door Shell-geïnitieerde tijdelijke blokkering

LET OP: Het annuleren van een kaart is definitief en kan niet ongedaan worden gemaakt.

Extra eindpunten

Gebruiksvoorbeelden

Voorbeeld 1: Zoeken naar kaarten die binnenkort verlopen

POST /card-management/v1/search

{
"Filters": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"],
"ExpiringInDays": 30
},
"Page": "1",
"PageSize": "100"
}

Voorbeeld 2: Een kaart tijdelijk blokkeren

POST /card-management/v1/updatestatus

{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"Action": "TEMP_BLOCK_CUSTOMER",
"Reason": "Kaart tijdelijk zoekgeraakt"
}
]
}

Voorbeeld 3: Kaarten annuleren

POST /card-management/v1/cancel

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

Foutafhandeling

Veelvoorkomende foutcodes

Aanbevolen werkwijzen

1. Gebruik OAuth 2.0-authenticatie

BELANGRIJK: Alle klanten moeten overstappen op OAuth 2.0-authenticatie. Implementeer goed tokenbeheer:

• Sla toegangstokens op in de cache en hergebruik ze totdat ze verlopen
• Vernieuw tokens voordat ze verlopen (aanbevolen: 60 seconden van tevoren)
• Sla clientgegevens veilig op (gebruik omgevingsvariabelen of een geheimenbeheerder)
• Log nooit toegangstokens in en maak ze nooit openbaar in client-side code

2. Gebruik verzoek-ID’s

Voeg altijd een uniek RequestId (GUID-formaat) toe voor traceerbaarheid van begin tot eind

3. Implementeer paginering

Gebruik bij grote datasets paginering om time-outs te voorkomen

4. Test in de sandbox-omgeving

Test de integratie altijd in de test-/sandbox-omgeving voordat u naar productie overgaat

SDK en codevoorbeelden

Shell biedt officiële SDK’s en uitgebreide codevoorbeelden om uw integratie met de Card Management API te versnellen.

Beschikbare SDK-talen

• Python - Volledig uitgeruste SDK met ondersteuning voor OAuth 2.0
• TypeScript - Typeveilige SDK met volledige typedefinities
• Java - SDK op enterprise-niveau
• C#/.NET - Volledige .NET-integratie
• PHP - Gebruiksvriendelijke PHP-bibliotheek
• Ruby - Ruby-gem voor naadloze integratie

Bekijk officiële SDK's en documentatie

Ondersteuning en bronnen

Technische ondersteuning

• Ondersteuning: Technische ondersteuning van Shell

Documentatie

• Servicevoorwaarden
• API-referentie

Hulp krijgen

Geef het volgende op wanneer u contact opneemt met de ondersteuning:

1. Uw client_id (deel nooit uw client_secret of toegangstokens)
2. RequestId uit het API-antwoord
3. Tijdstempel van het verzoek
4. Omgeving (Productie/Test)

Laatst bijgewerkt: 15 juni 2026
Documentversie: 1.0
API-versie: 3.1.5