Passer au contenu principal
GET
/
v3
/
mobile
/
check-id
/
{id}
Vérifier le Statut par ID
curl --request GET \
  --url https://api.oneclickdz.com/v3/mobile/check-id/{id} \
  --header 'X-Access-Token: <api-key>'
{
  "success": true,
  "data": {
    "_id": "<string>",
    "ref": "<string>",
    "status": "<string>",
    "plan_code": "<string>",
    "MSSIDN": "<string>",
    "topup_amount": 123,
    "balance_amount": 123,
    "created_at": "<string>",
    "refund_message": "<string>",
    "suggested_offers": [
      {
        "typename": "<string>",
        "plan_code": "<string>",
        "amount": 123
      }
    ],
    "follow_orderid": "<string>",
    "retry_orderid": "<string>"
  },
  "meta": {
    "timestamp": "<string>"
  }
}

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

Suivez le statut d’une recharge mobile en utilisant le topupId retourné depuis l’endpoint d’envoi. En général, nos serveurs traiteront votre requête en environ 5 à 30 secondes.
Important : Il est obligatoire de comprendre tous les statuts possibles pour gérer correctement la mise à jour et la notification de vos utilisateurs.

​
Paramètres de Chemin

​
id
string
requis
ID interne de la recharge depuis la réponse /mobile/send

​
Réponse

​
success
boolean
requis
Indique si la requête a réussi
​
data
object
requis
​
meta
object
requis

​
Valeurs de Statut

Le statut PENDING indique que la commande a été créée et est actuellement en file d’attente, en attente de traitement par l’un de nos serveurs. Elle sera traitée dès que possible.Durée typique : 2 à 15 secondesAction : Continuez à interroger toutes les 5 à 10 secondes
Le statut HANDLING indique que la commande est actuellement en cours de traitement par l’un de nos serveurs.Durée typique : 3 à 8 secondesAction : Continuez à interroger toutes les 5 à 10 secondes
Le statut FULFILLED indique que la recharge mobile a été envoyée avec succès. ✅Action : Mettez à jour le statut de la commande comme terminée, notifiez l’utilisateur
Le statut REFUNDED indique que la recharge mobile a été remboursée. ❌Champs disponibles :
  • refund_message : Affichez ceci à l’utilisateur (en arabe)
  • suggested_offers : Forfaits alternatifs (en cas de non-correspondance)
Action : Remboursez l’utilisateur, affichez le message, proposez des alternatives
Le statut UNKNOWN_ERROR indique que la recharge mobile peut avoir réussi ou échoué. Le statut se mettra à jour dans 1 à 12 heures en FULFILLED ou REFUNDED après vérification manuelle par notre équipe de support. Nous serons immédiatement notifiés et aucune action de votre part n’est requise. ⚠️De telles erreurs surviennent en raison de la nature des commandes AT et des comportements inattendus des opérateurs (nouveaux messages, problèmes réseau, etc.).
VOUS NE DEVEZ PAS REMBOURSER LE MONTANT à votre utilisateur à ce statut !
Action :
  • Affichez refund_message à l’utilisateur
  • NE remboursez PAS immédiatement
  • Configurez une tâche cron quotidienne pour vérifier les commandes UNKNOWN_ERROR et les mettre à jour en FULFILLED ou REFUNDED
  • Vérifiez à nouveau après 24 heures
  • Gérez ensuite les remboursements si le statut devient REFUNDED

​
Exemples

curl https://api.oneclickdz.com/v3/mobile/check-id/6901616fe9e88196b4eb64b0 \
  -H "X-Access-Token: YOUR_API_KEY"

​
Réponse FULFILLED

{
  "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_abc123"
}

​
Réponse REFUNDED

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "REFUNDED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z",
    "refund_message": "الرصيد المطلوب غير متوفر لهذا الرقم"
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_def456"
}

​
Réponse REFUNDED avec Offres Suggérées

Lorsque le code de forfait ne correspond pas au type de numéro de téléphone, vous recevrez des alternatives suggérées : 
{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "REFUNDED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z",
    "refund_message": "هذا العرض غير متوافق مع هذا الرقم جرب فاتورة",
    "suggested_offers": [
      {
        "typename": "📋 FACTURE | فاتورة",
        "plan_code": "FACTURE_DJEZZY",
        "amount": 500
      }
    ]
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_ghi789"
}
VEUILLEZ NOTER : suggested_offers est un tableau et peut contenir plusieurs éléments, par exemple lorsque vous envoyez des forfaits GETMENU.

​
Stratégie de Polling

​
Synchroniser Notre API avec Votre Backend

1

Démarrer le Polling

Commencez à vérifier le statut immédiatement après l’envoi de la recharge. Une approche simple consiste à définir un intervalle de 5 à 10 secondes sur votre frontend pour vérifier le statut. Une fois le statut FULFILLED, REFUNDED ou UNKNOWN_ERROR, effacez l’intervalle et arrêtez d’envoyer des requêtes.
const topupId = response.data.topupId;
const status = await pollStatus(topupId);
2

Intervalle de Polling

Vérifiez toutes les 5 à 10 secondes tant que PENDING ou HANDLING. Cette approche maintiendra les requêtes au minimum (5 à 10 par transaction).Pour chaque requête GET de vos utilisateurs, vous pouvez lire le statut dans votre base de données. Seulement si le statut n’est pas FULFILLED, REFUNDED ou UNKNOWN_ERROR, envoyez une requête de vérification à notre API, mettez à jour votre base de données, puis répondez à votre utilisateur.
async function pollStatus(topupId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const { data } = await checkTopupStatus(topupId);
    
    if (['FULFILLED', 'REFUNDED', 'UNKNOWN_ERROR'].includes(data.status)) {
      return data;
    }
    
    await sleep(5000); // Wait 5 seconds
  }
  throw new Error('Timeout');
}
3

Gérer le Résultat

Mettez à jour la commande en fonction du statut final
if (status === 'FULFILLED') {
  await markOrderComplete(orderId);
} else if (status === 'REFUNDED') {
  await refundUser(orderId);
  await notifyUser(refund_message);
} else if (status === 'UNKNOWN_ERROR') {
  await markForReview(orderId);
  // DO NOT refund yet - wait for daily cronjob
}

​
Exemple de Polling Complet

async function pollTopupStatus(topupId) {
  const maxAttempts = 60; // 5 minutes max
  const pollInterval = 5000; // 5 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.oneclickdz.com/v3/mobile/check-id/${topupId}`,
      { headers: { "X-Access-Token": process.env.API_KEY } }
    );

    const { data } = await response.json();

    // Final states
    if (["FULFILLED", "REFUNDED", "UNKNOWN_ERROR"].includes(data.status)) {
      return data;
    }

    // Still processing
    console.log(`Attempt ${i + 1}: Status is ${data.status}`);
    await new Promise((resolve) => setTimeout(resolve, pollInterval));
  }

  throw new Error("Polling timeout after 5 minutes");
}

// Usage
try {
  const result = await pollTopupStatus("6901616fe9e88196b4eb64b0");
  console.log("Final status:", result.status);
} catch (error) {
  console.error("Polling failed:", error.message);
}

​
Gestion de UNKNOWN_ERROR

NE remboursez PAS immédiatement lorsque le statut est UNKNOWN_ERROR !
Le statut UNKNOWN_ERROR indique une incertitude quant au succès ou à l’échec de la recharge. Cela se produit en raison de la nature des commandes AT et des comportements inattendus des opérateurs (nouveaux messages, problèmes réseau, etc.).
1

Afficher le Message

Affichez refund_message à l’utilisateur expliquant le délai
2

Marquer pour Révision

Signalez la commande pour révision manuelle ou revérification automatisée. Nous serons immédiatement notifiés et aucune action de votre part n’est requise.
3

Revérification Automatisée

Configurez une tâche cron quotidienne pour vérifier les commandes incertaines. Le statut se mettra à jour dans 1 à 12 heures (jusqu’à 24h) en FULFILLED ou REFUNDED après vérification manuelle par notre équipe de support.
// Daily at midnight
cron.schedule('0 0 * * *', async () => {
  const uncertainOrders = await db.orders.find({
    status: 'UNKNOWN_ERROR',
    createdAt: { $lt: new Date(Date.now() - 24*60*60*1000) }
  });
  
  for (const order of uncertainOrders) {
    const status = await checkTopupStatus(order.apiTopupId);
    await updateOrderStatus(order.id, status.data.status);
    
    // Now handle refund if status is REFUNDED
    if (status.data.status === 'REFUNDED') {
      await processRefund(order);
    }
  }
});
4

Résolution Finale

Le statut se mettra à jour en FULFILLED ou REFUNDED dans les 24 heures. C’est seulement à ce moment que vous devrez traiter les remboursements si le statut final est REFUNDED.

​
Bonnes Pratiques

Mettre en Cache le Statut

Stockez le statut dans votre base de données et ne vérifiez l’API que pour les commandes en attente

Éviter le Sur-polling

Ne vérifiez pas plus fréquemment que toutes les 5 secondes pour les commandes actives

Gérer UNKNOWN_ERROR

Ne remboursez jamais immédiatement - attendez la résolution dans les 24 heures

Notifier les Utilisateurs

Envoyez des notifications push ou e-mail lorsque le statut change en état final

​
Gestion des Remboursements

Un refund_message (message en arabe) sera ajouté à l’opération de recharge, et vous devez l’afficher tel quel à votre client. Exemples de scénarios :

​
Mauvais Numéro de Téléphone

Si votre client saisit un mauvais numéro de téléphone : 
refund_message: "رقم الهاتف خاطئ، يرجى التأكد مع العميل"

​
Inadéquation du Plan

Si vous essayez d’envoyer PREPAID_DJEZZY vers un numéro facture (postpayé) : 
{
  "refund_message": "هذا العرض غير متوافق مع هذا الرقم جرب فاتورة",
  "suggested_offers": [
    {
      "typename": "📋 FACTURE | فاتورة",
      "plan_code": "FACTURE_DJEZZY",
      "amount": 500
    }
  ]
}

​
Tableau des Offres Suggérées

Le tableau suggested_offers affiche les plans corrects pour le numéro de téléphone. Mettez à jour l’interface de votre application pour représenter ces nouveaux plans au lieu d’afficher tous les plans.
suggested_offers est un tableau et peut contenir plusieurs éléments, surtout lorsque vous envoyez des requêtes GETMENU.

​
Tests en Sandbox

Activez le sandbox sur votre page de paramètres pour tester les requêtes sans affecter votre solde. Toutes les opérations simuleront une opération réelle :
1

Flux Normal

N’importe quel numéro de téléphone normal :
  • 5 premières secondes : statut PENDING
  • 15 premières secondes : statut HANDLING
  • Ensuite : statut FULFILLED
Après avoir intégré le flux fulfilled, passez à tester les autres statuts.
2

Tester le Remboursement avec Message

Téléphone : 0600000001Tester le statut REFUNDED avec refund_message à afficher au client
3

Tester le Remboursement avec Suggestions

Téléphone : 0600000002Tester le statut REFUNDED avec refund_message et suggested_offers
4

Tester l'Erreur Inconnue

Téléphone : 0600000003Tester le statut UNKNOWN_ERROR pour s’assurer que votre logique de tâche quotidienne fonctionne correctement

​
Endpoints Associés

Vérifier par Référence

Suivre avec votre référence personnalisée

Envoyer une Recharge

Créer une nouvelle recharge