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

# Démarrage rapide

> Initialisez le SDK Java GIMpay et découvrez les services disponibles.

## Initialisation

L'initialisation se fait via la méthode statique `init()`. Le SDK gère ensuite automatiquement l'authentification et le cycle de vie des tokens.

```java theme={null}
import com.gimpaysdk.facade.GIMpaySdk;

// Initialisez le SDK une seule fois dans votre application (voir Bonnes Pratiques)
GIMpaySdk sdk = GIMpaySdk.init(
    "VOTRE_CLIENT_ID",
    "VOTRE_CLIENT_SECRET",
    "https://api.gimpay.com"  // URL de l'API GIMpay
);
```

> [!WARNING]
>
> Ne codez jamais vos identifiants en dur. Utilisez des variables d'environnement ou un gestionnaire de secrets :
>
> ```java theme={null}
> String clientId = System.getenv("GIMPAY_CLIENT_ID");
> String clientSecret = System.getenv("GIMPAY_CLIENT_SECRET");
> String baseUrl = System.getenv("GIMPAY_BASE_URL");
> GIMpaySdk sdk = GIMpaySdk.init(clientId, clientSecret, baseUrl);
> ```

## Services disponibles

Le SDK est organisé en services, chacun accessible via une méthode dédiée sur l'instance `sdk`.

| Service | Méthode d'accès | Description |
| - | - | - |
| `WalletService` | `sdk.wallets()` | Gestion des portefeuilles et instruments de paiement. |
| `OperationService` | `sdk.operations()` | Exécution et annulation d'opérations financières. |
| `UserService` | `sdk.users()` | Enrôlement et gestion des utilisateurs, bénéficiaires... |
| `CatalogService` | `sdk.catalog()` | Consultation des produits, contributeurs, pays... |
| `FeeService` | `sdk.fees()` | Calcul des frais de transaction. |
| `OtpService` | `sdk.otp()` | Génération et validation d'OTP. |
| `ConsentService` | `sdk.consents()` | Gestion des consentements. |
| `DocumentService` | `sdk.documents()` | Gestion des documents KYC. |
| `MmpService` | `sdk.mmp()` | Interaction avec les Mini-Marketplaces. |
| `LoyalityService` | `sdk.loyality()` | Programmes de fidélité. |
| `TerminalService` | `sdk.terminals()` | Gestion des terminaux de paiement. |
| `CountriesService` | `sdk.countries()` | Informations sur les pays. |
| `ContributorsService` | `sdk.contributors()` | Informations sur les contributeurs (banques, opérateurs...). |
| `CheckExistenceService` | `sdk.existence()` | Vérification d'existence d'entités. |
| `ContributorPortalService` | `sdk.contributorPortals()` | Fonctionnalités du portail contributeur. |

## Exemples d'utilisation

### Consulter un solde

```java theme={null}
try {
    Double balance = sdk.wallets().getBalance("REF_WALLET_12345");
    System.out.println("Solde disponible : " + balance);
} catch (ApiException e) {
    System.err.println("Impossible de récupérer le solde : " + e.getMessage());
}
```

### Enrôler un compte Mobile Money

```java theme={null}
import com.gimpaysdk.model.request.EnrollMobileWalletRequest;
import com.gimpaysdk.model.response.EnrollMobileWalletResponse;

EnrollMobileWalletRequest mobileRequest = EnrollMobileWalletRequest.builder()
    .msidn("0121144558")
    .codeIso("CIV")
    .refContributeurDemandeur("REF_OPERATEUR_DEMANDEUR") // Référence de l'opérateur demandeur
    .refContributeurEmetteur("REF_OPERATEUR_EMETTEUR") // Référence de l'opérateur émetteur
    .refUsager("USER_001")
    .build();

try {
    EnrollMobileWalletResponse response = sdk.wallets().enrollMobileWallet(mobileRequest);
    System.out.println("Compte Mobile Money enrôlé avec la référence : " + response.getReference());
} catch (ApiException e) {
    System.err.println("Échec de l'enrôlement : " + e.getResponseBody());
}
```

### Exécuter un paiement (P2P)

```java theme={null}
import com.gimpaysdk.model.request.OperationRequest;
import com.gimpaysdk.model.enumeration.TypeOperation;
import com.gimpaysdk.model.response.OperationResponse;

OperationRequest p2pTransfer = OperationRequest.builder()
    .typeOperation(TypeOperation.P2P)
    .montant(5000.0)
    .libelle("Transfert pour achat de services")
    .refInstrumentPaiementInitiateur("REF_WALLET_SOURCE_123")
    .refInstrumentPaiementBeneficiaire("REF_WALLET_DEST_456")
    .build();

try {
    OperationResponse response = sdk.operations().execute(p2pTransfer);
    System.out.println("Transfert réussi. Référence de l'opération : " + response.getRefOperation());
} catch (ApiException e) {
    System.err.printf("Échec du transfert : Status=%d, Message=%s%n", e.getStatusCode(), e.getResponseBody());
}
```

## Comprendre les modèles de données

Pour construire des requêtes complexes, il est essentiel de savoir quels champs sont disponibles et lesquels sont obligatoires.

* **Explorez les classes de requête** : les objets de requête (par ex. `OperationRequest`, `EnrollRequest`) se trouvent dans le package `com.gimpaysdk.model.request`. Leurs `Builder` respectifs vous montrent tous les champs que vous pouvez définir.
* **Consultez la documentation de l'API** : pour connaître les champs obligatoires pour un cas d'usage spécifique (par ex. un `CASH_IN` vs un `P2P`), référez-vous à la [référence API](https://sandbox.it-centrex.com/api-reference/introduction.md) GIMpay.

## Valeurs et références

Certains appels nécessitent des valeurs spécifiques :

* **Enums** : pour des valeurs comme le type d'une opération, utilisez les enums du package `com.gimpaysdk.model.enumeration` (par exemple `TypeOperation.P2P`).
* **Chaînes standardisées** : pour des valeurs comme le type d'instrument ou les codes pays, référez-vous à la [référence API](https://sandbox.it-centrex.com/api-reference/introduction.md) et au [glossaire](https://sandbox.it-centrex.com/glossary/enumerations.md) pour la liste exhaustive.
* **Références d'entités** : les identifiants uniques (`REF_WALLET_...`, `REF_OPERATEUR_...`) ne sont pas statiques, vous les obtenez via d'autres appels API. Par exemple, appelez `sdk.wallets().getWallets()` pour obtenir la référence d'un portefeuille, ou `sdk.catalog().getContributors(...)` pour celle d'un opérateur.

## Étapes suivantes

> **[Gestion des erreurs](https://sandbox.it-centrex.com/sdks/java/error-handling.md)**
>
> Exceptions typées et bonnes pratiques.

> **[Dépannage](https://sandbox.it-centrex.com/sdks/java/troubleshooting.md)**
>
> Solutions aux problèmes les plus courants.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.