Passer au contenu principal

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

Après avoir envoyé une commande de recharge internet, interrogez l’endpoint /check-id pour suivre le statut et récupérer les détails de la carte lors de l’exécution. La plupart des commandes se terminent en 3-45 secondes, mais certaines peuvent être QUEUED pendant 12-48 heures.
Interrogez toutes les 5-10 secondes jusqu’à ce que la commande atteigne un état final : FULFILLED, REFUNDED ou QUEUED.

​
Référence API

GET /v3/internet/check-id/{id}

Documentation complète de l’endpoint

​
Valeurs de Statut de Commande

La commande est en cours de traitement avec l’opérateur. Durée typique : 3-45 secondes. Continuez l’interrogation toutes les 5-10 secondes.
Succès ! Carte livrée. card_code, num_trans et date_traitement disponibles. Livrez immédiatement au client.
Planifié pour plus tard. La commande sera traitée dans les 12-48 heures. Ce n’est pas un échec - planifiez une nouvelle vérification après 24 heures et informez le client.
Échec. La commande a été annulée et remboursée automatiquement. Notifiez le client de l’échec.

​
Vérification de statut de base

async function checkTopupStatus(topupId) {
  const response = await fetch(
    `https://api.oneclickdz.com/v3/internet/check-id/${topupId}`,
    {
      headers: {
        "X-Access-Token": process.env.API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to check status: ${response.status}`);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const topupId = "6901616fe9e88196b4eb64b2";
const order = await checkTopupStatus(topupId);

console.log(`Status: ${order.status}`);
console.log(`Type: ${order.type}`);
console.log(`Number: ${order.number}`);

if (order.card_code) {
  console.log(`Card Code: ${order.card_code}`);
  console.log(`Transaction: ${order.num_trans}`);
}

​
Exemples de réponse

​
En cours de traitement

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "HANDLING",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
Exécuté (Succès)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "FULFILLED",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "card_code": "123456789012",
    "num_trans": "AT-2025-12345",
    "date_traitement": "2025-11-01T12:00:45.000Z",
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
En file d’attente (Planifié)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "QUEUED",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
Implémentation de base de l’interrogation

async function pollTopupUntilComplete(topupId, maxAttempts = 60) {
  const pollInterval = 5000; // 5 seconds
  
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    console.log(`Polling attempt ${attempt}/${maxAttempts}`);
    
    const order = await checkTopupStatus(topupId);
    
    // Check if order reached final state
    const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
    if (finalStates.includes(order.status)) {
      console.log(`Order completed with status: ${order.status}`);
      return order;
    }
    
    // Wait before next poll
    if (attempt < maxAttempts) {
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }
  
  throw new Error('Polling timeout - order still processing');
}

// Usage
try {
  const order = await pollTopupUntilComplete('6901616fe9e88196b4eb64b2');
  
  if (order.status === 'FULFILLED') {
    console.log('✅ Card delivered:', order.card_code);
  } else if (order.status === 'QUEUED') {
    console.log('⏰ Order scheduled for later');
  } else if (order.status === 'REFUNDED') {
    console.log('❌ Order failed and refunded');
  }
} catch (error) {
  console.error('Polling failed:', error.message);
}

​
Stratégie d’interrogation adaptative

Ajustez la fréquence d’interrogation selon le temps écoulé : 
async function pollTopupAdaptive(topupId, maxDuration = 5 * 60 * 1000) {
  const startTime = Date.now();
  let pollInterval = 3000; // Start with 3 seconds
  
  while (Date.now() - startTime < maxDuration) {
    const order = await checkTopupStatus(topupId);
    
    // Check for final state
    const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
    if (finalStates.includes(order.status)) {
      return order;
    }
    
    // Adaptive interval: increase as time passes
    const elapsed = Date.now() - startTime;
    if (elapsed > 60000) {
      pollInterval = 10000; // 10 seconds after 1 minute
    } else if (elapsed > 30000) {
      pollInterval = 5000; // 5 seconds after 30 seconds
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
  
  throw new Error('Order processing timeout');
}

​
Gestion des résultats de commande

async function handleTopupResult(topupId, order) {
  switch (order.status) {
    case 'FULFILLED':
      console.log(`✅ Order fulfilled`);
      console.log(`Card: ${order.card_code}`);
      
      await db.internetOrders.updateOne(
        { topupId },
        { $set: { status: 'FULFILLED', cardCode: order.card_code, fulfilledAt: new Date() } }
      );
      
      await deliverCard(order);
      break;
    
    case 'QUEUED':
      console.log(`⏰ Order scheduled for later delivery`);
      
      await db.internetOrders.updateOne(
        { topupId },
        { $set: { status: 'SCHEDULED', nextCheckAt: new Date(Date.now() + 24 * 60 * 60 * 1000) } }
      );
      
      await scheduleRecheck(topupId, 24 * 60 * 60 * 1000);
      await notifyCustomer(order, 'Your order is scheduled and will be delivered within 48 hours.');
      break;
    
    case 'REFUNDED':
      console.log(`❌ Order failed and refunded`);
      
      await db.internetOrders.updateOne(
        { topupId },
        { $set: { status: 'REFUNDED', refundedAt: new Date() } }
      );
      
      await notifyCustomer(order, 'Your order could not be completed. A full refund has been issued.');
      break;
  }
}

​
Gestion du statut QUEUED

Les commandes QUEUED ne sont pas des échecs ! Elles sont programmées pour être livrées dans les 12 à 48 heures.
async function scheduleRecheck(topupId, delayMs) {
  await recheckQueue.add(
    'recheck-topup',
    { topupId },
    {
      delay: delayMs,
      attempts: 3,
      backoff: { type: 'exponential', delay: 3600000 },
    }
  );
  
  console.log(`Scheduled recheck for ${topupId} in ${delayMs / 1000 / 60 / 60} hours`);
}

recheckQueue.process('recheck-topup', async (job) => {
  const { topupId } = job.data;
  const order = await checkTopupStatus(topupId);
  
  if (order.status === 'QUEUED') {
    await scheduleRecheck(topupId, 12 * 60 * 60 * 1000);
  } else {
    await handleTopupResult(topupId, order);
  }
});

​
Bonnes pratiques

Interroger toutes les 5-10 secondes

Équilibre entre réactivité et charge API

Gérer QUEUED correctement

Ne pas traiter QUEUED comme un échec - planifier des nouvelles vérifications

Définir des limites de délai

Échouer gracieusement après 5 minutes d’interrogation

Mettre à jour la base de données

Stocker les changements de statut et les détails de carte

​
Étapes suivantes

Livrer les cartes

Livrer les codes de carte en toute sécurité aux clients

Envoyer les recharges

Soumettre des commandes avec validation

Référence API

Documentation complète de l’endpoint

Vue d'ensemble

Retour à la vue d’ensemble de l’intégration

Valider les numéros

Vérifier les numéros de téléphone

Charger les produits

Récupérer les cartes disponibles