Glossaire
Argent
Fuelz — l'unité de compte du wallet Instafuel. Un Fuelz correspond à un FCFA de carburant à régler en station partenaire.
C'est une unité de compte interne, pas un moyen de paiement : les Fuelz ne sont ni remboursables en espèces, ni transférables entre entreprises, ni utilisables pour autre chose que du carburant. Instafuel n'émet pas de monnaie électronique et ne tient pas de compte de dépôt — le wallet enregistre un droit d'achat de carburant déjà payé.
Dans l'API, cette unité s'exprime toujours en entiers de FCFA (amountFcfa) : 500000, jamais 500000.0. Les nombres à virgule ne sont pas pris en charge sur les montants : un décimal est rejeté (400 WALLET_INVALID_AMOUNT), jamais arrondi. Les volumes de carburant (litres), eux, sont bien décimaux.
Wallet — le compteur du crédit d'achat de carburant d'une entreprise. Alimenté par un crédit approuvé après versement constaté, débité à chaque plein validé. Il ne peut pas être vidé autrement qu'en carburant. Une entreprise a un wallet ; il n'y en a pas au niveau du portefeuille.
Grand livre (ledger) — journal immuable des mouvements du wallet. Une écriture n'est jamais modifiée ni supprimée ; une correction est une nouvelle écriture. Le solde affiché est un cache dont la valeur autoritaire reste la somme des écritures.
Hold — réservation temporaire de fonds. Posée à l'ouverture d'un plein pour garantir que le montant sera disponible à la validation ; libérée si la transaction est annulée, capturée sinon. Une transaction PENDING correspond à un hold en cours : les fonds sont engagés mais pas encore débités.
Solde disponible — le solde du wallet moins les holds en cours. C'est ce qu'un chauffeur peut réellement dépenser.
Plafond (cap) — limite de dépense ou de crédit. Côté entreprise, elle borne les dépenses journalières ou mensuelles ; côté apporteur, le montant que vous pouvez déclarer par opération et par jour.
Preuve de versement — pièce justificative (virement, reçu mobile money, chèque) rattachée à une demande de crédit. Une preuve ne peut être rattachée qu'à une seule écriture. Obligatoire quelle que soit la source.
Acteurs
Entreprise (Company) — le client final. Possède un wallet, des véhicules, des chauffeurs.
Apporteur d'affaires — partenaire qui apporte et gère un portefeuille d'entreprises clientes. C'est vous, et c'est ce que votre clé ifp_* représente.
Portefeuille — l'ensemble des entreprises rattachées à un apporteur. Une entreprise appartient à un seul apporteur à un instant donné.
Chauffeur (Driver) — l'employé d'une entreprise cliente qui paie les pleins. Rattaché à une entreprise, jamais à un apporteur.
Marketeur — la marque de carburant : Total, Shell, Petroci… Détient le réseau de stations et fixe les prix de référence. Vous n'interagissez pas avec les marketeurs : l'intérêt d'Instafuel est justement que vos clients paient dans toutes les stations, quelle que soit la marque.
Opérations
Périmètre (scope) — l'ensemble des données visibles par une clé. Toujours dérivé de la clé, jamais de la requête. Voir Périmètre.
Droit (scope de clé) — capacité attachée à une clé d'API : COMPANIES_READ, COMPANIES_WRITE, CREDIT_REQUEST_WRITE, REPORTS_READ. Voir Clés d'API.
Idempotence — garantie qu'un rejeu ne produit pas une seconde opération. Portée par l'en-tête X-Idempotency-Key. Voir Erreurs et idempotence.
Demande d'approbation — opération sensible initiée par vous et validée par Instafuel. L'initiateur n'approuve jamais sa propre demande. Une demande de crédit expire au bout de 7 jours sans approbation.
Feature flag — interrupteur d'activation d'une fonctionnalité. Désactivée, elle répond 404 FEATURE_DISABLED, jamais 403 : elle reste invisible.
Identifiants
Code de référence (ref) — identifiant lisible et stable exposé sur les entités principales, destiné au support et aux litiges : ENT-B14E77A3 pour une entreprise, TRX-4B71E0A9 pour une transaction, APP-7C3D91B0 pour un apporteur. Distinct de l'identifiant technique (id), qui reste l'identifiant à utiliser dans les URL.
RCCM — registre du commerce et du crédit mobilier ivoirien, identifiant légal d'une entreprise. Format CI-ABJ-2024-B-12345.
NIF — numéro d'identification fiscale.
Numéro de téléphone — toujours au format international ivoirien : +225 suivi de 10 chiffres.