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

GET

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

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

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

Afficher properties

_id

string

requis

Identifiant de la recharge

ref

string

Votre référence personnalisée (si fournie)

status

string

requis

Statut actuel : PENDING, HANDLING, FULFILLED, REFUNDED, ou UNKNOWN_ERROR

plan_code

string

requis

Code de forfait utilisé

MSSIDN

string

requis

Numéro de téléphone

topup_amount

number

requis

Montant de la recharge en DZD

balance_amount

number

requis

Montant déduit de votre solde

created_at

string

requis

Horodatage de création (ISO 8601)

refund_message

string

Message en arabe pour l’utilisateur final (uniquement si REFUNDED ou UNKNOWN_ERROR)

suggested_offers

array

Forfaits alternatifs en cas de non-correspondance (uniquement si REFUNDED)

Afficher properties

typename

string

Nom d’affichage du forfait suggéré

plan_code

string

Code de forfait à utiliser

amount

number

Montant suggéré

follow_orderid

string

ID de commande de suivi si la commande a été redirigée

retry_orderid

string

ID de commande de nouvelle tentative si la commande a été réessayée

Valeurs de Statut

PENDING

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

HANDLING

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

FULFILLED

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

REFUNDED

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

UNKNOWN_ERROR

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

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);

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');
}

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

Afficher le Message

Affichez refund_message à l’utilisateur expliquant le délai

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.

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);
    }
  }
});

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 :

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.

Tester le Remboursement avec Message

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

Tester le Remboursement avec Suggestions

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

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

Envoyer une Recharge Mobile Vérifier le Statut par Référence

Documentation Index

​Vue d’Ensemble

​Paramètres de Chemin

​Réponse

​Valeurs de Statut

​Exemples

​Réponse FULFILLED

​Réponse REFUNDED

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

​Stratégie de Polling

​Synchroniser Notre API avec Votre Backend

​Exemple de Polling Complet

​Gestion de UNKNOWN_ERROR

​Bonnes Pratiques

Mettre en Cache le Statut

Éviter le Sur-polling

Gérer UNKNOWN_ERROR

Notifier les Utilisateurs

​Gestion des Remboursements

​Mauvais Numéro de Téléphone

​Inadéquation du Plan

​Tableau des Offres Suggérées

​Tests en Sandbox

​Endpoints Associés

Vérifier par Référence

Envoyer une Recharge

Vue d’Ensemble

Paramètres de Chemin

Réponse

Valeurs de Statut

Exemples

Réponse FULFILLED

Réponse REFUNDED

Réponse REFUNDED avec Offres Suggérées

Stratégie de Polling

Synchroniser Notre API avec Votre Backend

Exemple de Polling Complet

Gestion de UNKNOWN_ERROR

Bonnes Pratiques

Gestion des Remboursements

Mauvais Numéro de Téléphone

Inadéquation du Plan

Tableau des Offres Suggérées

Tests en Sandbox

Endpoints Associés