API de gestion des cartes de mobilité B2B Shell - Guide de démarrage rapide

Version de l'API : 3.1.5 | Authentification : OAuth 2.0 | Statut : Production

Présentation

L’API de gestion des cartes Shell est une API de type REST qui permet aux développeurs de gérer les cartes carburant Shell par programmation. L’API prend en charge la recherche de cartes, la commande, les mises à jour de statut, l’annulation et diverses autres opérations de gestion des cartes.

Remarque : Ce guide ne couvre que les points de terminaison authentifiés via OAuth 2.0 (chemin de base : /card-management/v1). Les points de terminaison hérités utilisant l’authentification de base (/fleetmanagement/v1/card) ne sont pas inclus, car ils sont en cours de suppression.

Principales fonctionnalités

• Rechercher et filtrer les cartes carburant selon des critères flexibles
• Commander de nouvelles cartes et suivre l’état de la commande
• Bloquer, débloquer et résilier des cartes
• Mettre à jour les adresses de livraison des cartes
• Gérer les paramètres de renouvellement automatique des cartes
• Déplacer des cartes entre des groupes de cartes et des comptes
• Demander des rappels de code PIN

Avis important - OAuth 2.0

IMPORTANT : OAuth 2.0 est désormais la méthode d’authentification standard

• Nouvelles intégrations : Utilisez OAuth 2.0 dès le départ
• Intégrations existantes : Planifiez votre migration vers OAuth 2.0
• Méthodes héritées : L’authentification de base et la clé API sont en cours de suppression progressive

Contactez le support technique Shell pour obtenir vos identifiants OAuth 2.0 (client_id et client_secret).

Authentification

OAuth 2.0 (méthode d’authentification standard)

L’API de gestion des cartes Shell utilise le flux d’identifiants client OAuth 2.0 pour une authentification sécurisée.

AVERTISSEMENT : Tous les clients doivent prévoir d’adopter l’authentification OAuth 2.0. Il s’agit de la méthode d’authentification recommandée et évolutive pour l’API de gestion des cartes Shell. Les méthodes d’authentification héritées sont progressivement supprimées.

Flux OAuth 2.0

Étape 1 : Obtenir un jeton d’accès

Demander un jeton d’accès auprès du point de terminaison OAuth :

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

Étape 2 : Utiliser le jeton d’accès dans les requêtes API

Authorization: Bearer <jeton-d’accès>
Content-Type : application/json

Gestion des jetons

Meilleures pratiques en matière de gestion des jetons :

• Les jetons d'accès ont une durée de vie limitée (généralement 15 minutes)
• Mettez en place une mise en cache des jetons pour éviter les demandes de jetons inutiles
• Actualisez les jetons avant leur expiration pour garantir un service ininterrompu
• Ne partagez jamais votre client_secret et ne l’intégrez jamais dans du code côté client

Stratégie d’adoption d’OAuth 2.0

Pourquoi migrer vers OAuth 2.0 ?

Avantages en matière de sécurité :

• Protocole d’authentification conforme aux normes du secteur
• Les jetons d’accès à durée limitée réduisent les risques de sécurité
• Aucun identifiant n’est transmis à chaque requête
• Meilleure prise en charge de la rotation et de la révocation des jetons

Avantages opérationnels :

• Évolutivité et performances améliorées
• Meilleures capacités de surveillance et d’audit
• Gestion simplifiée des identifiants
• Intégration évolutive

Parcours de migration

Si vous utilisez actuellement des méthodes d’authentification héritées, suivez ce parcours de migration :

1. Demandez des identifiants OAuth 2.0 auprès de Support technique Shell
2. Mettez en œuvre la gestion des jetons OAuth dans votre application
3. Effectuez des tests approfondis dans l’environnement de test/sandbox
4. Effectuez une authentification parallèle (OAuth + méthode héritée) pendant la transition
5. Surveiller et valider l’intégration OAuth
6. Passer à l’authentification exclusivement via OAuth une fois la validation effectuée
7. Mettez hors service l’authentification héritée une fois la migration réussie

Environnements

L’API est disponible dans deux environnements :

Conseil : Testez toujours votre intégration dans l’environnement de test avant de passer en production.

Démarrage rapide

1. Obtenez vos identifiants OAuth

• Contactez support technique de Shell
• Demandez des identifiants OAuth 2.0 (client_id et client_secret)
• Consultez les conditions d’utilisation

2. Obtenir un jeton d’accès

Commencez par obtenir votre jeton d’accès OAuth :

Exemple avec cURL :

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

Réponse :

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

3. Effectuez votre première requête API

Exemple : recherche de cartes actives

Exemple 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": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"]
},
"Page": "1",
"PageSize": "50"
}'

Exemple de réponse :

{
"RequestId": "233e4567-e89b-12d3-a456-426614174000",
"Status": "SUCCESS",
"Data": [
{
"CardId": 125,
"PAN": "7002861007636000020",
"MaskedPAN": "7002861**000020",
"DriverName": "ROBERT SMITH",
"Numéro d'immatriculation du véhicule" : "MV65YLH",
"Description du statut" : "Actif",
"Date d'expiration" : "20250531",
"Code du type de carte" : "7077861",
"Nom du type de carte" : "Carte Shell"
}
],
"Page" : 1,
"PageSize" : 50,
"TotalPages" : 1,
"TotalRecords" : 1
}

Référence des points de terminaison API

Recherche et récupération de cartes

Cas d’utilisation courants :

• Recherche par statut de la carte (ACTIVE, BLOQUÉE, EXPIRÉE, etc.)
• Filtrer par nom du conducteur ou numéro d'immatriculation du véhicule
• Recherche par PAN (4 derniers chiffres)
• Rechercher les cartes expirant dans X jours

Résumé de la carte

Renvoie :

• Nombre total de cartes par statut
• Statistiques récapitulatives par type de carte
• Répartition entre cartes actives et inactives

Commande de cartes

Informations requises pour la commande de cartes :

• ColCoCode (code de l’organisme de collecte)
• Numéro de payeur ou identifiant du payeur
• Numéro de compte
• Type et configuration de la carte
• Coordonnées de livraison

Gestion du statut de la carte

Actions sur le statut :

• BLOQUER - Bloquer temporairement une carte
• DÉBLOQUER - Réactiver une carte bloquée
• ENDOMMAGÉE - Signaler une carte endommagée et demander un remplacement
• BLOCAGE TEMPORAIRE PAR LE CLIENT - Blocage temporaire demandé par le client
• TEMP_BLOCK_SHELL - Blocage temporaire initié par Shell

ATTENTION : L'annulation de la carte est définitive et ne peut être annulée.

Points de terminaison supplémentaires

Exemples d’utilisation

Exemple 1 : Recherche de cartes arrivant bientôt à expiration

POST /card-management/v1/search

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

Exemple 2 : bloquer temporairement une carte

POST /card-management/v1/updatestatus

{
"ColCoCode" : 86,
"PayerNumber" : "PH50000843",
"Cards" : [
{
"CardId" : 125,
"Action" : "TEMP_BLOCK_CUSTOMER",
"Reason" : "Carte égarée temporairement"
}
]
}

Exemple 3 : Annuler des cartes

POST /card-management/v1/cancel

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

Gestion des erreurs

Codes d'erreur courants

Bonnes pratiques

1. Adopter l’authentification OAuth 2.0

IMPORTANT : Tous les clients doivent migrer vers l’authentification OAuth 2.0. Mettez en place une gestion appropriée des jetons :

• Mettez en cache les jetons d’accès et réutilisez-les jusqu’à leur expiration
• Actualisez les jetons avant leur expiration (de préférence 60 secondes avant)
• Stockez les identifiants du client en toute sécurité (utilisez des variables d’environnement ou un gestionnaire de secrets)
• Ne jamais enregistrer ni exposer les jetons d’accès dans le code côté client

2. Utilisez des identifiants de requête

Incluez toujours un identifiant de requête unique (au format GUID) pour assurer la traçabilité de bout en bout

3. Mettez en place la pagination

Pour les grands ensembles de données, utilisez la pagination afin d’éviter les délais d’expiration

4. Testez dans un environnement de test/sandbox

Testez toujours l’intégration dans l’environnement de test/sandbox avant de passer en production

SDK et exemples de code

Shell fournit des SDK officiels et des exemples de code complets pour accélérer votre intégration avec l’API de gestion des cartes.

Langages de SDK disponibles

• Python - SDK complet avec prise en charge d’OAuth 2.0
• TypeScript - SDK à sécurité de types avec définitions de types complètes
• Java - SDK de niveau entreprise
• C#/.NET - Intégration .NET complète
• PHP - Bibliothèque PHP facile à utiliser
• Ruby - Gem Ruby pour une intégration transparente

Consultez les SDK officiels et la documentation

Assistance et ressources

Assistance technique

• Assistance : Assistance technique Shell

Documentation

• Conditions d’utilisation
• Référence de l'API

Obtenir de l'aide

Lorsque vous contactez le support, veuillez fournir :

1. Votre client_id (ne communiquez jamais votre client_secret ni vos jetons d’accès)
2. RequestId issu de la réponse de l’API
3. Horodatage de la requête
4. Environnement (Production/Test)

Dernière mise à jour : 15 juin 2026
Version du document : 1.0
Version de l'API : 3.1.5