Objectif : en quinze minutes, valider votre clé, onboarder une entreprise de test et lire une transaction. Tout se fait sur staging , avec une clé ifp_test_*.
Avant de commencer
Il vous faut une clé d'API de test, remise par Instafuel à l'ouverture de votre compte apporteur. Si vous ne l'avez pas, demandez-la à votre interlocuteur Instafuel — voir Clés d'API .
Rangez-la dans une variable d'environnement, jamais dans votre code. La base de staging est https://instafuel-backend-staging.up.railway.app :
export INSTAFUEL_API_KEY = "ifp_test_9f2c4a7b1e8d3406af5b2c9d1e0f7a83"
Vérifiez votre clé
Le premier appel utile renvoie votre profil : il confirme que la clé est valide et vous dit ce qu'elle peut faire.
Terminal
JavaScript
Python
PHPcurl "https://instafuel-backend-staging.up.railway.app/v1/papi/me" \ -H "Authorization: Bearer $INSTAFUEL_API_KEY "
{ "ref" : "APP-7C3D91B0" , "name" : "Ivoire Fleet Partners" , "email" : "contact@ivoirefleet.ci" , "environment" : "test" , "companiesCount" : 0 , "walletCreditEnabled" : true , "scopes" : [ "COMPANIES_READ" , "TRANSACTIONS_READ" , "WALLET_READ" , "COMPANIES_WRITE" , "CREDIT_REQUEST_WRITE" , "REPORTS_READ" ], "caps" : { "perOperationFcfa" : 5000000 , "dailyFcfa" : 20000000 , "dailyRemainingFcfa" : 20000000 } }
environment: "test" confirme que vous êtes bien sur staging. Une clé inconnue, révoquée ou présentée sur le mauvais environnement donne ceci :
{ "error" : { "code" : "PAPI_KEY_INVALID" , "message" : "Clé d'API inconnue ou révoquée" } }
Onboardez une entreprise cliente
Un seul appel crée l'entreprise, la rattache à votre portefeuille, crée son compte gestionnaire de flotte et lui envoie son lien d'activation.
Terminal
JavaScript
Python
PHPcurl -X POST "https://instafuel-backend-staging.up.railway.app/v1/papi/companies" \ -H "Authorization: Bearer $INSTAFUEL_API_KEY " \ -H "X-Idempotency-Key: 8f14e45f-ea0c-4f7e-9a1b-3d2c1e0b9a87" \ -H "Content-Type: application/json" \ -d '{ "name": "Transports Kouassi SARL", "email": "contact@kouassi.ci", "phoneNumber": "+2250700000001", "rccm": "CI-ABJ-2024-B-12345", "nif": "1234567A", "headquartersAddress": "Zone 4, Marcory, Abidjan", "fleetAdministrator": { "firstName": "Awa", "lastName": "Kouassi", "email": "awa.kouassi@kouassi.ci", "phoneNumber": "+2250700000002" } }'
{ "id" : 4832 , "ref" : "ENT-B14E77A3" , "name" : "Transports Kouassi SARL" , "email" : "contact@kouassi.ci" , "phoneNumber" : "+2250700000001" , "rccm" : "CI-ABJ-2024-B-12345" , "nif" : "1234567A" , "headquartersAddress" : "Zone 4, Marcory, Abidjan" , "status" : "ACTIVE" , "walletBalanceFcfa" : 0 , "fleetAdministrator" : { "id" : 9114 , "ref" : "USR-2D80F5C7" , "firstName" : "Awa" , "lastName" : "Kouassi" , "email" : "awa.kouassi@kouassi.ci" , "role" : "FLEET_ADMINISTRATOR" , "status" : "PENDING_ACTIVATION" , "activationExpiresAt" : "2026-09-03T10:22:05.000Z" }, "createdAt" : "2026-08-31T10:22:05.000Z" }
Conservez l'id : il sert pour toutes les opérations sur cette entreprise. Le ref (ENT-B14E77A3) est l'identifiant lisible à citer au support.
Une validation qui échoue renvoie 422, avec le détail champ par champ :
{ "error" : { "code" : "VALIDATION_ERROR" , "message" : "Validation échouée" , "details" : [ { "field" : "phoneNumber" , "messages" : [ "Numéro ivoirien attendu, format +225XXXXXXXXXX" ] }, { "field" : "fleetAdministrator.email" , "messages" : [ "Adresse email obligatoire" , "Format invalide" ] } ] } }
Le rattachement ne se négocie pas depuis le corps
L'entreprise est rattachée au portefeuille de la clé utilisée. Un identifiant d'apporteur envoyé dans le corps est ignoré, pas honoré.
Vérifiez votre portefeuille
Terminal
JavaScript
Python
PHPcurl "https://instafuel-backend-staging.up.railway.app/v1/papi/companies?page=1&perPage=20" \ -H "Authorization: Bearer $INSTAFUEL_API_KEY "
{ "data" : [ { "id" : 4832 , "ref" : "ENT-B14E77A3" , "name" : "Transports Kouassi SARL" , "email" : "contact@kouassi.ci" , "phoneNumber" : "+2250700000001" , "rccm" : "CI-ABJ-2024-B-12345" , "nif" : "1234567A" , "headquartersAddress" : "Zone 4, Marcory, Abidjan" , "status" : "ACTIVE" , "walletBalanceFcfa" : 0 , "createdAt" : "2026-08-31T10:22:05.000Z" } ], "pagination" : { "page" : 1 , "perPage" : 20 , "total" : 1 , "totalPages" : 1 } }
L'entreprise créée à l'étape précédente doit apparaître. Si votre portefeuille est vide alors que la création a répondu 201, c'est que vous interrogez l'autre environnement.
Faites créditer le wallet
Le solde est à 0 : sans crédit, aucun plein n'est possible. Vous ne créditez jamais directement — vous déclarez un versement, Instafuel approuve. Le flux complet, preuve incluse, est décrit dans Crédit wallet .
Lisez les transactions
Une fois le wallet crédité et un plein passé en station, la transaction est lisible.
Terminal
JavaScript
Python
PHPcurl "https://instafuel-backend-staging.up.railway.app/v1/papi/transactions?companyId=4832&from=2026-08-01&to=2026-08-31" \ -H "Authorization: Bearer $INSTAFUEL_API_KEY "
{ "data" : [ { "ref" : "TRX-4B71E0A9" , "companyId" : 4832 , "station" : { "id" : 12 , "name" : "Station Plateau" }, "driver" : { "id" : 3311 , "name" : "Yao N'Guessan" }, "vehicle" : { "id" : 812 , "registration" : "1234 AB 01" }, "fuelType" : "GASOIL" , "liters" : { "estimate" : 42.5 , "actual" : 42.5 }, "selfService" : false , "unitPriceFcfa" : 750 , "amountFcfa" : 31875 , "status" : "CONFIRMED" , "createdAt" : "2026-08-30T07:41:19.000Z" , "confirmedAt" : "2026-08-30T07:41:19.000Z" } ], "pagination" : { "page" : 1 , "perPage" : 20 , "total" : 1 , "totalPages" : 1 } }
amountFcfa est un entier : 31 875 FCFA. Les montants ne transitent jamais en nombre à virgule — seuls les volumes (litres) sont décimaux.
Passer en production
Trois choses changent, et rien d'autre :
l'URL de base devient celle de production — voir Accueil ;
la clé devient ifp_live_* ;
les montants sont réels.
Gardez les deux jeux de variables séparés dans votre configuration, et n'exécutez jamais votre suite de tests contre la production.
La suite
Last modified on September 2, 2026
