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

# Vérifier le Statut par Référence

> Vérifier le statut d'une recharge mobile en utilisant votre référence personnalisée

## Vue d'Ensemble

Suivez le statut d'une recharge mobile en utilisant le paramètre `ref` que vous avez fourni lors de l'envoi de la recharge. Cela est utile lorsque vous souhaitez vérifier le statut en utilisant vos propres identifiants de commande.

Cet endpoint vous permet de suivre les commandes en utilisant la référence que vous avez fournie lors de la création de la recharge. Si vous n'avez pas fourni de référence, utilisez celle générée automatiquement retournée dans la réponse d'envoi.

<Info>
  Consultez la documentation [Vérifier par ID](/fr/api-reference/mobile/check-by-id) pour des descriptions détaillées des statuts et des directives de gestion.
</Info>

## Paramètres de Chemin

<ParamField path="ref" type="string" required>
  Votre référence personnalisée depuis la requête `/mobile/send`
</ParamField>

## Réponse

Le format de réponse est identique à [Vérifier par ID](/fr/api-reference/mobile/check-by-id).

<ResponseField name="success" type="boolean" required>
  Indique si la requête a réussi
</ResponseField>

<ResponseField name="data" type="object" required>
  Objet de recharge avec statut, détails et informations de remboursement (le cas échéant). Consultez [Vérifier par ID](/fr/api-reference/mobile/check-by-id#response) pour les descriptions complètes des champs.
</ResponseField>

<ResponseField name="meta" type="object" required>
  Métadonnées avec horodatage au format ISO 8601
</ResponseField>

## Exemples

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

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

  ```python Python theme={null}
  order_ref = 'order-12345'
  response = requests.get(
      f'https://api.oneclickdz.com/v3/mobile/check-ref/{order_ref}',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  status = response.json()['data']['status']
  ```

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

### Exemple de Réponse

```json theme={null}
{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "FULFILLED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z"
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_xyz789"
}
```

## Quand Utiliser Cet Endpoint

<CardGroup cols={2}>
  <Card title="Demandes des Utilisateurs" icon="user">
    Lorsque les utilisateurs demandent des informations sur leur commande en utilisant votre ID de commande
  </Card>

  <Card title="Gestion des Commandes" icon="list-check">
    Intégrez avec votre système de suivi des commandes existant
  </Card>

  <Card title="Pages de Statut" icon="display">
    Affichez le statut de la commande en utilisant des références orientées client
  </Card>

  <Card title="Support Client" icon="headset">
    Recherchez des commandes par numéros de référence client
  </Card>
</CardGroup>

## Valeurs de Statut et Gestion

Consultez [Vérifier par ID](/fr/api-reference/mobile/check-by-id#status-values) pour des descriptions détaillées des statuts et des instructions de gestion.

## Réponse d'Erreur

**404 - Non Trouvé :**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Top-up with reference 'order-12345' not found"
  },
  "requestId": "req_1730160975_abc123"
}
```

Cela signifie qu'aucune recharge n'existe avec cette référence. Raisons possibles :

* La référence n'a jamais été soumise
* Faute de frappe dans la référence
* La référence appartient à un autre compte

## Bonnes Pratiques

<AccordionGroup>
  <Accordion title="Utiliser des Références Significatives">
    Créez des références qui sont :

    * Uniques dans votre système
    * Faciles à identifier (ex. : `order-{timestamp}-{userId}`)
    * Compatibles avec les URLs (pas de caractères spéciaux)
    * Recherchables dans votre base de données
  </Accordion>

  <Accordion title="Stocker les Deux IDs">
    Sauvegardez votre référence et le topupId de l'API :

    ```javascript theme={null}
    await db.orders.update({
      orderId: 'order-12345',
      apiTopupId: response.data.topupId,
      apiTopupRef: response.data.topupRef
    });
    ```

    Cela vous permet de suivre avec l'un ou l'autre identifiant.
  </Accordion>

  <Accordion title="Gérer les Références Manquantes">
    Si vous oubliez de fournir un `ref`, l'API en génère un. Sauvegardez-le :

    ```javascript theme={null}
    const response = await sendTopup({ 
      plan_code: 'PREPAID_DJEZZY',
      MSSIDN: '0778037340',
      amount: 500
      // No ref provided
    });

    // API returns: { topupRef: "auto-gen-1730160975" }
    await db.orders.update({
      orderId: order.id,
      apiRef: response.data.topupRef
    });
    ```
  </Accordion>
</AccordionGroup>

## Endpoints Associés

<CardGroup cols={2}>
  <Card title="Vérifier par ID" icon="id-card" href="/fr/api-reference/mobile/check-by-id">
    Suivre avec l'ID interne de recharge
  </Card>

  <Card title="Envoyer une Recharge" icon="paper-plane" href="/fr/api-reference/mobile/send-topup">
    Créer une nouvelle recharge
  </Card>

  <Card title="Lister les Recharges" icon="list" href="/fr/api-reference/mobile/list-topups">
    Voir toutes les recharges
  </Card>
</CardGroup>