> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.gimpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide

> Initialisez le SDK Flutter GimPay et suivez un parcours d'intégration type.

## Initialisation

À faire **une seule fois**, au démarrage de l'application.

<Tabs>
  <Tab title="Production — tokenProvider (recommandé)">
    Votre application **n'embarque aucun credential GimPay**. Votre backend détient le `clientId`/`clientSecret`, obtient le token auprès de GimPay et le relaie à l'app :

    ```dart theme={null}
    import 'package:gimpay_sdk/gimpay_sdk.dart';

    void main() {
      Gimpay.initializeWithTokenProvider(
        baseUrl: 'https://<environnement>.gimpayapp.com',
        tokenProvider: () async {
          // Appelez VOTRE backend (utilisateur déjà authentifié chez vous).
          final r = await monApiBackend.post('/gimpay/token');
          return r.accessToken;
        },
      );
      runApp(const MyApp());
    }
    ```

    Le `tokenProvider` est appelé au premier appel API puis à chaque expiration du token (réponse `401`), avec garantie **single-flight** : même si plusieurs requêtes expirent en même temps, votre backend ne reçoit qu'un seul appel.

    **Contrat à implémenter côté backend partenaire** (une seule route) :

    <Steps>
      <Step title="Authentifiez l'utilisateur">
        Utilisez votre mécanisme habituel.
      </Step>

      <Step title="Appelez GIMgar Sud">
        `POST {baseUrl}/api/v1/auth/token` en `application/x-www-form-urlencoded` avec `grant_type=client_credentials`, `client_id`, `client_secret` (stockés côté serveur : variables d'environnement, vault...).
      </Step>

      <Step title="Renvoyez le token à l'app">
        Renvoyez l'`access_token` à l'app (TLS obligatoire). Ne le mettez pas en cache plus longtemps qu'`expires_in`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Sandbox / prototypage — credentials embarqués">
    ```dart theme={null}
    Gimpay.initialize(
      baseUrl: 'https://<sandbox>.gimpayapp.com',
      clientId: '<client-id-sandbox>',
      clientSecret: '<client-secret-sandbox>',
      enableLogs: true, // logs internes ; toujours désactivés en release
    );
    ```

    <Warning>
      Tout ce qui est compilé dans un APK/IPA est extractible par rétro-ingénierie. Ce mode est réservé au sandbox ou à des credentials dédiés, supervisés et révocables. Ne publiez **jamais** une application grand public avec des credentials de production embarqués.
    </Warning>
  </Tab>
</Tabs>

## Parcours type

Toutes les fonctionnalités passent par la façade statique `Gimpay`. Chaque méthode est documentée (dartdoc) avec son endpoint.

```dart theme={null}
// Référentiels
final pays = await Gimpay.countries;
final types = await Gimpay.getWalletTypes();
final contributeurs = await Gimpay.getContributors(
  typeInstrument: TypeInstrument.MOBILE_WALLET,
  codeISO: 'CIV',
);

// Enrôler un client avec son premier instrument
final enrolement = await Gimpay.enrollClient(
  client: Client(/* données KYC */),
  wallet: const Wallet(msisdn: '0140919386'),
  terminal: const Terminal(marque: '…', modele: '…', numeroSerie: '…'),
  refContributeurDemandeur: '<ref>',
  refContributeurEmetteur: '<ref>',
);
final refUsager = enrolement.refUsagerGIMpay!;

// Instruments et solde
final wallets = await Gimpay.getUserWallets(refUsager);
final solde = await Gimpay.getBalance(wallets.first.reference!);

// Frais puis opération (avec OTP si requis par le service)
final frais = await Gimpay.calculateFees(
    referenceService: '<ref-service>', amount: 15000);

// Générer un OTP de débit si besoin
await Gimpay.generateDebitOtp('<ref-instrument>');

// ... l'utilisateur saisit l'OTP reçu ...
final operation = await Gimpay.executeOperation(
  libelle: 'Paiement',
  montant: 15000,
  refInstrumentPaiementInitiateur: '<ref-instrument>',
  typeOperation: TypeOperation.P2P,
  refService: '<ref-service>',
  refContributeurBeneficiaire: '<ref-contributeur>',
  authData: '<code-otp>',
);

switch (operation.statutOperation) {
  case StatutOperation.SUCCES: /* … */
  case StatutOperation.ECHOUE: /* operation.raisonEchec */
  default: /* statut intermédiaire ou inconnu */
}
```

Autres domaines disponibles via la façade `Gimpay` : cycle de vie des instruments (verrouillage/déverrouillage/désenrôlement, mouvements, opérations), bénéficiaires et mini-places de marché favorites, vérifications d'existence et d'autorisation, documents d'identité. Voir la [couverture complète des APIs](/sdks/api-coverage).

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Gestion des erreurs" icon="triangle-exclamation" href="/sdks/error-handling">
    Exceptions typées et bonnes pratiques.
  </Card>

  <Card title="Couverture des APIs" icon="list-check" href="/sdks/api-coverage">
    La liste complète des endpoints et énumérations disponibles.
  </Card>
</CardGroup>