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

# Démarrage rapide

> Envoyez votre première recharge en moins de 5 minutes

## Obtenir votre clé API

<Steps>
  <Step title="Créer un compte">
    Créez un compte gratuit sur [app.oneclickdz.com](https://app.oneclickdz.com/)
  </Step>

  <Step title="Générer des clés API">
    Accédez à [Paramètres](https://enterprise.oneclickdz.com/api-keys) → Section API → Générer une clé API

    Vous recevrez deux clés :

    * **Sandbox** : Tests sans transactions réelles
    * **Production** : Transactions en direct
  </Step>

  <Step title="Sécuriser vos clés">
    Stockez les clés de manière sécurisée dans des variables d'environnement. Ne les exposez jamais dans du code côté client ni dans un système de contrôle de version.
  </Step>
</Steps>

<Warning>
  Commencez toujours par le mode **Sandbox** pour tester votre intégration en toute sécurité.
</Warning>

## Vérifier votre clé API

Testez votre clé API avec l'endpoint de validation :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/validate \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/validate", {
    headers: { "X-Access-Token": "YOUR_API_KEY" },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.oneclickdz.com/v3/validate",
      headers={"X-Access-Token": "YOUR_API_KEY"}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/validate");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Réponse :**

```json theme={null}
{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "type": "SANDBOX",
      "scope": "READ-WRITE",
      "isEnabled": true
    }
  }
}
```

<Check>Si vous voyez `"success": true`, votre clé API fonctionne correctement !</Check>

## Étape 1 : Envoyer une recharge mobile

Envoyez une recharge de 500 DZD vers un numéro Djezzy :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/mobile/send \
    -X POST \
    -H "Content-Type: application/json" \
    -H "X-Access-Token: YOUR_API_KEY" \
    -d '{
      "plan_code": "PREPAID_DJEZZY",
      "MSSIDN": "0778037340",
      "amount": 500,
      "ref": "order-001"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      plan_code: "PREPAID_DJEZZY",
      MSSIDN: "0778037340",
      amount: 500,
      ref: "order-001",
    }),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.oneclickdz.com/v3/mobile/send',
      headers={
          'Content-Type': 'application/json',
          'X-Access-Token': 'YOUR_API_KEY'
      },
      json={
          'plan_code': 'PREPAID_DJEZZY',
          'MSSIDN': '0778037340',
          'amount': 500,
          'ref': 'order-001'
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/mobile/send");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "X-Access-Token: YOUR_API_KEY"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'plan_code' => 'PREPAID_DJEZZY',
      'MSSIDN' => '0778037340',
      'amount' => 500,
      'ref' => 'order-001'
  ]));
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Réponse :**

```json theme={null}
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "order-001"
  }
}
```

## Étape 2 : Vérifier le statut de la recharge

Vérifiez le statut de votre recharge à l'aide de la référence :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/mobile/check-ref/order-001 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/mobile/check-ref/order-001",
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.oneclickdz.com/v3/mobile/check-ref/order-001',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/mobile/check-ref/order-001");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Réponse :**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "MSSIDN": "0778037340",
    "topup_amount": 500
  }
}
```

<Check>Flux de statut : `PENDING` (5s) → `HANDLING` (15s) → `FULFILLED` ✅</Check>

## Étape 3 : Envoyer une recharge internet

Rechargez une ligne ADSL avec une carte de 1000 DZD :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/internet/send \
    -X POST \
    -H "Content-Type: application/json" \
    -H "X-Access-Token: YOUR_API_KEY" \
    -d '{
      "type": "ADSL",
      "number": "036362608",
      "value": 1000,
      "ref": "internet-001"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/internet/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      type: "ADSL",
      number: "036362608",
      value: 1000,
      ref: "internet-001",
    }),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.oneclickdz.com/v3/internet/send',
      headers={
          'Content-Type': 'application/json',
          'X-Access-Token': 'YOUR_API_KEY'
      },
      json={
          'type': 'ADSL',
          'number': '036362608',
          'value': 1000,
          'ref': 'internet-001'
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/internet/send");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "X-Access-Token: YOUR_API_KEY"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'type' => 'ADSL',
      'number' => '036362608',
      'value' => 1000,
      'ref' => 'internet-001'
  ]));
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Réponse :**

```json theme={null}
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b1",
    "topupRef": "internet-001"
  }
}
```

Vérifiez le statut de la recharge internet :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/internet/check-ref/internet-001 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/internet/check-ref/internet-001",
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.oneclickdz.com/v3/internet/check-ref/internet-001',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/internet/check-ref/internet-001");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Réponse :**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "card_code": "123456789012",
    "num_trans": "AT-2025-001"
  }
}
```

## Étape 4 : Explorer les cartes cadeaux

Récupérez le catalogue de produits pour voir les cartes cadeaux disponibles :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/gift-cards/catalog \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/gift-cards/catalog",
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.oneclickdz.com/v3/gift-cards/catalog',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/catalog");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

Passez une commande de carte cadeau :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/gift-cards/placeOrder \
    -X POST \
    -H "Content-Type: application/json" \
    -H "X-Access-Token: YOUR_API_KEY" \
    -d '{
      "productId": "PRODUCT_ID",
      "typeId": "TYPE_ID",
      "quantity": 1
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/gift-cards/placeOrder",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        productId: "PRODUCT_ID",
        typeId: "TYPE_ID",
        quantity: 1,
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.oneclickdz.com/v3/gift-cards/placeOrder',
      headers={
          'Content-Type': 'application/json',
          'X-Access-Token': 'YOUR_API_KEY'
      },
      json={
          'productId': 'PRODUCT_ID',
          'typeId': 'TYPE_ID',
          'quantity': 1
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/placeOrder");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "X-Access-Token: YOUR_API_KEY"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'productId' => 'PRODUCT_ID',
      'typeId' => 'TYPE_ID',
      'quantity' => 1
  ]));
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Réponse :**

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "6901616fe9e88196b4eb64c0"
  }
}
```

Récupérez les codes de cartes cadeaux en vérifiant le statut de la commande :

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64c0 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  // Poll order status until fulfilled
  async function getGiftCardCodes(orderId) {
    let status = 'HANDLING';
    
    while (status === 'HANDLING') {
      const response = await fetch(
        `https://api.oneclickdz.com/v3/gift-cards/checkOrder/${orderId}`,
        { headers: { "X-Access-Token": "YOUR_API_KEY" } }
      );
      const { data } = await response.json();
      status = data.status;
      
      if (status === 'FULFILLED') {
        return data.cards; // Array of {value, serial}
      }
      
      await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds
    }
  }

  const cards = await getGiftCardCodes('6901616fe9e88196b4eb64c0');
  console.log('Card codes:', cards);
  ```

  ```python Python theme={null}
  import time
  import requests

  def get_gift_card_codes(order_id):
      status = 'HANDLING'
      
      while status == 'HANDLING':
          response = requests.get(
              f'https://api.oneclickdz.com/v3/gift-cards/checkOrder/{order_id}',
              headers={'X-Access-Token': 'YOUR_API_KEY'}
          )
          data = response.json()['data']
          status = data['status']
          
          if status == 'FULFILLED':
              return data['cards']  # Liste de {'value': ..., 'serial': ...}
          
          time.sleep(5)  # Wait 5 seconds

  cards = get_gift_card_codes('6901616fe9e88196b4eb64c0')
  print('Card codes:', cards)
  ```

  ```php PHP theme={null}
  <?php
  function getGiftCardCodes($orderId, $apiKey) {
      $status = 'HANDLING';
      
      while ($status === 'HANDLING') {
          $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/checkOrder/{$orderId}");
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: {$apiKey}"]);
          $response = json_decode(curl_exec($ch), true);
          $status = $response['data']['status'];
          
          if ($status === 'FULFILLED') {
              return $response['data']['cards'];
          }
          
          sleep(5); // Wait 5 seconds
      }
  }

  $cards = getGiftCardCodes('6901616fe9e88196b4eb64c0', 'YOUR_API_KEY');
  print_r($cards);
  ?>
  ```
</CodeGroup>

**Réponse lorsque la commande est finalisée :**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      }
    ]
  }
}
```

<Check>Les codes de cartes sont récupérés depuis le tableau `cards` lorsque le statut est `FULFILLED`</Check>

## Tests en sandbox

En mode sandbox, testez ces scénarios spéciaux avec les recharges mobiles :

| Numéro de téléphone                   | Comportement                                      | Objectif                               |
| ------------------------------------- | ------------------------------------------------- | -------------------------------------- |
| Tout numéro normal (ex. `0778037340`) | Succès : PENDING → HANDLING → FULFILLED           | Tester les transactions réussies       |
| `0600000001`                          | REFUNDED avec message d'erreur                    | Tester la gestion des remboursements   |
| `0600000002`                          | REFUNDED avec suggestions de forfaits alternatifs | Tester le désaccord de forfait         |
| `0600000003`                          | Statut UNKNOWN\_ERROR                             | Tester la gestion des états incertains |

<Tip>
  Chaque guide de flux inclut des instructions de test en sandbox complètes avec des exemples.
</Tip>

## Comprendre le format de réponse

Toutes les réponses de l'API suivent cette structure :

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "...",
    "pagination": { ... }
  },
  "requestId": "..."
}
```

[En savoir plus sur le format de réponse →](/fr/api-reference/response-format)

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Guide recharge mobile" icon="mobile" href="/fr/mobile-topup-guides/overview">
    Flux d'intégration complet
  </Card>

  <Card title="Guide recharge internet" icon="wifi" href="/fr/internet-topup-guides/overview">
    ADSL et 4G avec tests sandbox
  </Card>

  <Card title="Guide cartes cadeaux" icon="gift" href="/fr/gift-card-guides/overview">
    Livraison de produits numériques
  </Card>

  <Card title="Gestion des erreurs" icon="shield" href="/fr/api-reference/error-handling">
    Gérer les erreurs correctement
  </Card>

  <Card title="Authentification" icon="key" href="/fr/authentication">
    Modèles d'accès sécurisé à l'API
  </Card>

  <Card title="Bonnes pratiques" icon="lightbulb" href="/fr/security-best-practices">
    Sécurité prête pour la production
  </Card>
</CardGroup>

<Note>
  **Besoin d'aide ?** Consultez notre page [Contact et support](/fr/contact) ou écrivez à
  [support@oneclickdz.com](mailto:support@oneclickdz.com)
</Note>