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

# Vue d'ensemble de l'intégration Recharge Mobile

> Apprenez à intégrer la recharge mobile pour les opérateurs algériens

## Introduction

Intégrez la fonctionnalité de recharge mobile pour les opérateurs algériens (Mobilis, Djezzy, Ooredoo, Pixx) en 4 étapes simples. Cette vue d'ensemble explique le flux d'intégration - les implémentations détaillées avec des exemples de code en Node.js, Python, PHP et cURL sont dans les guides étape par étape ci-dessous.

## Comment ça fonctionne

```mermaid theme={null}
sequenceDiagram
    participant User
    participant YourApp
    participant API as OneClickDz API

    YourApp->>API: 1. Load available plans
    API-->>YourApp: Plans with pricing
    
    User->>YourApp: Select plan & enter phone
    YourApp->>YourApp: 2. Validate input
    
    YourApp->>API: 3. Send top-up request
    API-->>YourApp: Order ID
    
    loop Until Complete
        YourApp->>API: 4. Check status
        API-->>YourApp: Status update
    end
    
    YourApp->>User: Notify success/failure
```

## Processus d'intégration en 4 étapes

<Steps>
  <Step title="Charger les forfaits">
    Récupérez les forfaits de recharge disponibles avec la tarification et mettez-les en cache localement.

    → [Voir Étape 1 : Chargement des forfaits](/fr/mobile-topup-guides/1-loading-plans)
  </Step>

  <Step title="Valider les entrées">
    Vérifiez les numéros de téléphone (10 chiffres, préfixe opérateur correct) et les montants avant d'envoyer.

    → [Voir Étape 2 : Validation](/fr/mobile-topup-guides/2-validation)
  </Step>

  <Step title="Envoyer la recharge">
    Soumettez la demande de recharge avec une référence unique pour le suivi.

    → [Voir Étape 3 : Envoi de recharges](/fr/mobile-topup-guides/3-sending-topups)
  </Step>

  <Step title="Suivre le statut">
    Vérifiez le statut de la commande toutes les 5 à 10 secondes jusqu'à complétion (FULFILLED, REFUNDED ou UNKNOWN\_ERROR).

    → [Voir Étape 4 : Suivi du statut](/fr/mobile-topup-guides/4-status-polling)
  </Step>
</Steps>

## Ce que vous devez savoir

### Types de forfaits

L'API prend en charge **3 types** de forfaits :

* **Forfaits dynamiques** : Montants flexibles (ex. 50–5000 DA pour Djezzy Prépayé)
* **Forfaits fixes** : Montants spécifiques (ex. Pixx 500 DA)
* **Forfaits GetMenu** : Récupère des offres personnalisées pour un numéro de téléphone

→ [En savoir plus à l'Étape 1](/fr/mobile-topup-guides/1-loading-plans)

### Statuts de commande

Les commandes progressent à travers ces états :

* `PENDING` / `HANDLING` → Continuez à vérifier
* `FULFILLED` → Succès ! ✅
* `REFUNDED` → Échec, remboursement effectué ❌
* `UNKNOWN_ERROR` → **Attendez 24h avant de rembourser** ⚠️

→ [Gestion détaillée des statuts à l'Étape 4](/fr/mobile-topup-guides/4-status-polling)

### Format de numéro de téléphone

Les numéros de téléphone doivent comporter **10 chiffres** : `0[567][0-9]{8}`

* Mobilis : `06...`
* Djezzy : `07...`
* Ooredoo : `05...`

→ [Code de validation à l'Étape 2](/fr/mobile-topup-guides/2-validation)

### Tarification

L'API renvoie les **prix en gros**. Appliquez votre marge avant de les afficher aux clients.

Exemple : `cost: 0.98` pour 1000 DA → Vous payez 980 DA → Vendez à 1029 DA (5% de marge) → Profit : 49 DA

→ [Stratégies de tarification à l'Étape 1](/fr/mobile-topup-guides/1-loading-plans)

## Points clés

<AccordionGroup>
  <Accordion title="Toujours utiliser des références uniques" icon="fingerprint">
    Générez un `ref` unique pour chaque requête pour éviter les doublons et activer le suivi.

    → [Implémentation à l'Étape 3](/fr/mobile-topup-guides/3-sending-topups)
  </Accordion>

  <Accordion title="Mettre les forfaits en cache localement" icon="database">
    Les forfaits changent rarement. Mettez-les en cache pour réduire les appels API et améliorer la vitesse.

    → [Stratégie de cache à l'Étape 1](/fr/mobile-topup-guides/1-loading-plans)
  </Accordion>

  <Accordion title="Gérer UNKNOWN_ERROR avec précaution" icon="triangle-exclamation">
    **Ne remboursez jamais immédiatement !** Attendez jusqu'à 24 heures que le statut se résolve.

    → [Gestion des erreurs à l'Étape 4](/fr/mobile-topup-guides/4-status-polling)
  </Accordion>

  <Accordion title="Afficher les messages d'erreur en arabe" icon="language">
    Affichez le champ `refund_message` (en arabe) aux clients - il explique ce qui s'est passé.

    → [Gestion des messages à l'Étape 4](/fr/mobile-topup-guides/4-status-polling)
  </Accordion>
</AccordionGroup>

## Référence API

Pour les spécifications complètes des endpoints :

<CardGroup cols={2}>
  <Card title="Lister les forfaits mobiles" icon="list" href="/fr/api-reference/mobile/list-plans">
    GET /v3/mobile/plans
  </Card>

  <Card title="Envoyer une recharge" icon="paper-plane" href="/fr/api-reference/mobile/send-topup">
    POST /v3/mobile/send
  </Card>

  <Card title="Vérifier par référence" icon="tag" href="/fr/api-reference/mobile/check-by-ref">
    GET /v3/mobile/check-ref/:ref
  </Card>

  <Card title="Vérifier par ID" icon="id-card" href="/fr/api-reference/mobile/check-by-id">
    GET /v3/mobile/check-id/:id
  </Card>
</CardGroup>

## Tests

Utilisez le **mode sandbox** pour tester sans argent réel. Testez avec ces numéros spéciaux :

* Numéros normaux → Flux de succès
* `0600000001` → Scénario de remboursement
* `0600000002` → Offres suggérées
* `0600000003` → Erreur inconnue

Activez le sandbox dans les [paramètres du tableau de bord](https://app.oneclickdz.com/#/settings).

## Démarrer l'intégration

<Card title="Commencer par l'Étape 1 : Chargement des forfaits" icon="play" href="/fr/mobile-topup-guides/1-loading-plans" color="#0D9373">
  Démarrez en chargeant et mettant en cache les forfaits mobiles avec des exemples de code
</Card>

## Ressources supplémentaires

<CardGroup cols={2}>
  <Card title="Guide de démarrage rapide" icon="rocket" href="/fr/quickstart">
    Démarrez en 5 minutes
  </Card>

  <Card title="Authentification" icon="key" href="/fr/authentication">
    Apprenez à authentifier les requêtes
  </Card>

  <Card title="Bonnes pratiques de sécurité" icon="shield" href="/fr/security-best-practices">
    Sécurisez votre intégration
  </Card>

  <Card title="Stratégies de polling" icon="chart-line" href="/fr/polling-strategies">
    Optimisez la vérification du statut
  </Card>

  <Card title="Webhooks" icon="webhook" href="/fr/webhooks">
    Notifications de statut en temps réel
  </Card>

  <Card title="Contacter le support" icon="headset" href="/fr/contact">
    Obtenez l'aide de notre équipe
  </Card>
</CardGroup>