API partenaire Instafuel
API machine des apporteurs d'affaires Instafuel.
Instafuel est une plateforme ivoirienne de paiement carburant : les entreprises règlent les pleins de leur flotte dans n'importe quelle station, quel que soit le marketeur, via un wallet interne appelé Fuelz.
Un apporteur d'affaires gère un portefeuille d'entreprises clientes. Cette API lui permet de piloter ce portefeuille depuis son propre système : lire les transactions et les soldes, enrôler de nouvelles entreprises, provisionner les comptes de ses clients et déclarer les versements qui alimentent leurs wallets.
Authentification
Toutes les requêtes portent une clé API dans l'en-tête Authorization :
Code
Les clés sont créées depuis le portail partenaire. Le secret n'est affiché qu'une seule fois, à la création : il n'est pas stocké en clair et ne peut pas être relu. Perdu, il se remplace par une nouvelle clé.
Deux environnements, distingués par le préfixe : ifp_live_ et ifp_test_.
Portefeuille
Une clé ne voit que les entreprises du portefeuille de son apporteur. Une
entreprise hors portefeuille est introuvable (404), jamais « interdite » —
l'API ne confirme pas l'existence de ressources qui ne vous concernent pas.
Droits
Chaque clé porte une liste de scopes. Une route dont le scope manque répond
403 PAPI_SCOPE_MISSING en nommant le droit requis. Les scopes disponibles pour
votre compte sont plafonnés par Instafuel : GET /v1/papi/me vous dit à tout
moment ce que porte la clé utilisée.
Conventions
- Montants : entiers en FCFA, jamais de flottant. 1 Fuelz = 1 FCFA.
- Dates : chaînes ISO 8601 en UTC (
2026-08-31T14:03:00.000Z). - Succès :
{ "data": … }, plus"pagination"sur les listes. - Erreurs :
{ "error": { "code": "CODE_STABLE", "message": "…" } }. Branchez votre logique surcode, qui est stable ;messageest en français et peut évoluer. - Pagination :
?page=1&perPage=20,perPageplafonné à 100. - Idempotence : toute écriture exige l'en-tête
X-Idempotency-Key. Rejouée à l'identique dans les 24 h, la requête renvoie la première réponse (X-Idempotent-Replay: true) au lieu de créer un doublon. Avec un corps différent,409 IDEMPOTENCY_CONFLICT. - Débit : limite par minute et par clé. Les réponses portent
X-RateLimit-Limit,X-RateLimit-RemainingetX-RateLimit-Reset.
Ce que l'API ne fait pas
- Créer une entreprise directement.
POST /companiesouvre une demande d'approbation et répond202. Un opérateur Instafuel valide. Créer une personne morale ouvre un wallet et une relation contractuelle : ce n'est pas un geste automatisable par un tiers. - Créditer un wallet.
POST /companies/{id}/wallet/creditdéclare un versement et répond202. Le solde ne bouge qu'après vérification de l'encaissement par Instafuel. - Notifier par webhook. Aucun webhook n'existe à ce jour. Interrogez les ressources concernées.