# Démarrage rapide

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

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](/guides/cles-api).

Rangez-la dans une variable d'environnement, jamais dans votre code. La base de staging est <StagingUrl /> :

```bash title="Environnement local"
export INSTAFUEL_API_KEY="ifp_test_9f2c4a7b1e8d3406af5b2c9d1e0f7a83"
```

<Stepper>

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

   <ApiExample path="/v1/papi/me" />

   <ApiResponse
     status={200}
     body={{
       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 :

   <ApiResponse
     status={401}
     body={{
       error: {
         code: "PAPI_KEY_INVALID",
         message: "Clé d'API inconnue ou révoquée",
       },
     }}
   />

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

   <ApiExample
     method="POST"
     path="/v1/papi/companies"
     idempotency
     body={{
       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",
       },
     }}
   />

   <ApiResponse
     status={201}
     body={{
       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 :

   <ApiResponse
     status={422}
     body={{
       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"],
           },
         ],
       },
     }}
   />

   :::note[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é.
   :::

3. **Vérifiez votre portefeuille**

   <ApiExample
     path="/v1/papi/companies"
     query={{ page: 1, perPage: 20 }}
   />

   <ApiResponse
     status={200}
     body={{
       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.

4. **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](/guides/credit-wallet).

5. **Lisez les transactions**

   Une fois le wallet crédité et un plein passé en station, la transaction est lisible.

   <ApiExample
     path="/v1/papi/transactions"
     query={{ companyId: 4832, from: "2026-08-01", to: "2026-08-31" }}
   />

   <ApiResponse
     status={200}
     body={{
       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.

</Stepper>

## Passer en production

Trois choses changent, et rien d'autre :

1. l'URL de base devient celle de production — voir [Accueil](/accueil) ;
2. la clé devient `ifp_live_*` ;
3. 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

- [Authentification](/guides/authentification) — la forme exacte de l'en-tête et les erreurs associées
- [Erreurs et idempotence](/guides/erreurs) — quoi retenter, quand, avec quelle clé
- [Limites et quotas](/guides/limites-et-quotas) — pagination et limitation de débit
- [Référence API](/api) — la liste des opérations