# API partenaire Instafuel

import { StagingUrl } from "../src/ApiExample";

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.

<Callout type="info" title="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.
</Callout>

## 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](/guides/demarrage-rapide) |
| Comprendre le modèle du portefeuille | [Apporteur d'affaires](/guides/apporteur-affaires) |
| Gérer vos clés et vos environnements | [Clés d'API](/guides/cles-api) |
| Faire créditer le wallet d'un client | [Crédit wallet](/guides/credit-wallet) |
| Voir la liste des opérations | [Référence API](/api) |

## Environnements

| Environnement | URL de base | Clés | Usage |
|---|---|---|---|
| Staging | <StagingUrl /> | `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.

<Callout type="caution" title="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.
</Callout>

<Callout type="danger" title="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.
</Callout>

## 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](/guides/erreurs).

**Périmètre dérivé de la clé.** Aucun paramètre de requête n'élargit ce que vous voyez. Voir [Périmètre](/guides/perimetre).

**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.