API partenaire Instafuel
Instafuel est une plateforme de paiement carburant. Une entreprise alimente un wallet Fuelz — son crédit d'achat de carburant prépayé — puis ses chauffeurs paient leurs pleins dans n'importe quelle station partenaire — quel que soit le marketeur — et chaque transaction est tracée, plafonnée et rapprochée.
Cette documentation s'adresse aux apporteurs d'affaires : les partenaires qui apportent et gèrent un portefeuille d'entreprises clientes sur Instafuel. Vous construisez votre propre interface, Instafuel fournit l'API.
Une seule surface publique
L'API partenaire, c'est /v1/papi/*. Elle s'authentifie par clé d'API ifp_live_* ou ifp_test_*. Tout ce qui est documenté ici est accessible avec cette clé, et rien d'autre ne l'est.
Ce que vous pouvez faire
| Domaine | Capacité |
|---|---|
| Portefeuille | lister vos entreprises clientes, consulter et modifier leur fiche, en onboarder de nouvelles |
| Comptes clients | créer et gérer les comptes gestionnaire de flotte et directeur financier de vos clients |
| Argent | lire les wallets et le grand livre, demander un crédit avec preuve de versement |
| Exploitation | lire les transactions, les chauffeurs, les alertes |
| Rapports | déclencher un export et récupérer le fichier quand il est prêt |
Ce que vous ne pouvez pas faire : créditer un wallet sans approbation Instafuel, débiter, bloquer un wallet, voir une entreprise hors de votre portefeuille, toucher aux stations ou aux marketeurs.
Par où commencer
| Vous voulez | Allez à |
|---|---|
| Faire votre premier appel maintenant | Démarrage rapide |
| Comprendre le modèle du portefeuille | Apporteur d'affaires |
| Gérer vos clés et vos environnements | Clés d'API |
| Faire créditer le wallet d'un client | Crédit wallet |
| Voir la liste des opérations | Référence API |
Environnements
| Environnement | URL de base | Clés | Usage |
|---|---|---|---|
| Staging | https://instafuel-backend-staging.up.railway.app | ifp_test_* | intégration, données de test |
| Production | communiquée avec votre clé ifp_live_* | ifp_live_* | argent réel |
Les deux environnements sont strictement séparés : bases de données distinctes, clés non interchangeables. Une clé ifp_test_* présentée en production est rejetée, et l'inverse aussi.
L'adresse de production n'est pas publique
Elle vous est communiquée avec votre clé ifp_live_*, à l'ouverture du compte. Toute la documentation — exemples compris — est écrite sur staging : passer en production revient à changer deux variables d'environnement, l'URL de base et la clé.
Ces adresses ne sont pas définitives : ce sont les déploiements actuels. Les exemples sont générés depuis la configuration du site, ils suivront le changement de domaine sans réécriture.
Argent réel
Les demandes de crédit approuvées en production déplacent de l'argent réel. Validez toujours votre intégration sur staging, et vérifiez que vous envoyez un X-Idempotency-Key distinct par opération métier — pas par tentative réseau.
Ce sur quoi vous pouvez compter
Montants entiers. Le solde d'un wallet est un crédit d'achat de carburant prépayé, libellé en FCFA et utilisable uniquement pour régler des pleins dans les stations partenaires. Ce n'est ni un dépôt, ni de la monnaie électronique : il n'est ni remboursable en espèces, ni transférable entre entreprises, ni utilisable ailleurs que pour du carburant.
Techniquement, tous les montants transitent en entiers de FCFA dans le champ amountFcfa : 500000, jamais 500000.0. Les nombres à virgule ne sont pas pris en charge — un montant décimal est rejeté en 400 WALLET_INVALID_AMOUNT, il n'est ni arrondi ni tronqué. Seuls les volumes (litres) sont décimaux.
Codes d'erreur stables. error.code est un contrat, error.message est du texte d'affichage qui peut changer. Voir Erreurs et idempotence.
Périmètre dérivé de la clé. Aucun paramètre de requête n'élargit ce que vous voyez. Voir Périmètre.
Idempotence. Toute mutation financière exige X-Idempotency-Key. Un rejeu ne produit jamais une seconde opération.
Grand livre immuable. Une écriture n'est jamais modifiée ni supprimée. Une correction est une nouvelle écriture.