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

Envoyez des commandes de recharge internet après avoir validé les numéros de téléphone et vérifié la disponibilité des produits. Les commandes sont traitées avec l’opérateur et se complètent généralement en 3-45 secondes.
Validez toujours les numéros en premier avec /check-number pour minimiser les échecs et les remboursements.

Référence API

POST /v3/internet/send

Documentation complète de l’endpoint

Soumission de base d’une commande

async function sendInternetTopup(orderData) {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/internet/send",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": process.env.API_KEY,
      },
      body: JSON.stringify({
        type: orderData.type,      // 'ADSL' or '4G'
        number: orderData.number,   // Phone number
        value: orderData.value,     // Card value
        ref: orderData.ref,         // Your unique reference
      }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || `HTTP ${response.status}`);
  }

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

// Usage
const order = await sendInternetTopup({
  type: 'ADSL',
  number: '036362608',
  value: 1000,
  ref: `order-${Date.now()}`
});

console.log('Top-up sent:', order.topupId);

Réponse en cas de succès

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b2",
    "topupRef": "order-123456"
  },
  "meta": {
    "timestamp": "2025-11-01T12:00:00.000Z"
  }
}

Validation avant commande

Validez toujours avant d’envoyer des commandes :
async function validateAndSend(orderData) {
  // Étape 1 : Valider le numéro de téléphone
  try {
    await validateInternetNumber(orderData.type, orderData.number);
  } catch (error) {
    throw new Error(`Invalid phone number: ${error.message}`);
  }

  // Step 2: Check product availability
  const products = await loadInternetProducts(orderData.type);
  const product = products.find(
    p => p.value === orderData.value && p.available
  );
  
  if (!product) {
    throw new Error(`Product ${orderData.value} DA not available for ${orderData.type}`);
  }

  // Step 3: Check balance
  const balance = await getBalance();
  if (balance < product.cost) {
    throw new Error(
      `Insufficient balance. Required: ${product.cost} DA, Available: ${balance} DA`
    );
  }

  // Étape 4 : Envoyer la commande
  console.log(`Sending ${orderData.type} ${orderData.value} DA to ${orderData.number}`);
  const result = await sendInternetTopup(orderData);
  
  return {
    topupId: result.topupId,
    topupRef: result.topupRef,
    cost: product.cost,
    type: orderData.type,
    number: orderData.number,
    value: orderData.value
  };
}

async function getBalance() {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/account/balance",
    {
      headers: { "X-Access-Token": process.env.API_KEY },
    }
  );
  const result = await response.json();
  return result.data.balance;
}

// Usage
try {
  const result = await validateAndSend({
    type: 'ADSL',
    number: '036362608',
    value: 1000,
    ref: `order-${Date.now()}`
  });
  
  console.log('✅ Order placed successfully');
  console.log(`  Top-up ID: ${result.topupId}`);
  console.log(`  Cost: ${result.cost} DA`);
} catch (error) {
  console.error('❌ Order failed:', error.message);
}

Suivi des Transactions

Stockez les détails de la commande dans votre base de données :
async function createOrderTransaction(userId, orderDetails) {
  const transaction = {
    userId,
    topupId: orderDetails.topupId,
    ref: orderDetails.topupRef,
    type: orderDetails.type,
    number: orderDetails.number,
    value: orderDetails.value,
    cost: orderDetails.cost,
    status: 'HANDLING',
    createdAt: new Date(),
    updatedAt: new Date()
  };
  
  await db.internetOrders.insertOne(transaction);
  
  console.log('Transaction enregistrée :', transaction.topupId);
  return transaction;
}

// Utilisation
const orderResult = await validateAndSend(orderData);
await createOrderTransaction(userId, orderResult);

Génération de Références Uniques

Assurez-vous que chaque commande possède une référence unique :
function generateOrderReference(userId, type) {
  const timestamp = Date.now();
  const random = Math.random().toString(36).substring(2, 8);
  return `${type.toLowerCase()}-${userId}-${timestamp}-${random}`;
}

// Utilisation
const ref = generateOrderReference(123, 'ADSL');
// Exemple : 'adsl-123-1730448000000-x7k2m9'

Gestion des erreurs

async function sendTopupSafely(orderData) {
  try {
    const result = await sendInternetTopup(orderData);
    return { success: true, data: result };
  } catch (error) {
    console.error('Order failed:', error);
    
    const message = error.message.toLowerCase();
    
    if (message.includes('err_phone')) {
      return {
        success: false,
        error: 'INVALID_PHONE',
        message: 'Invalid phone number for this service type'
      };
    }
    
    if (message.includes('err_stock')) {
      return {
        success: false,
        error: 'OUT_OF_STOCK',
        message: 'This card value is currently out of stock'
      };
    }
    
    if (message.includes('insufficient_balance')) {
      return {
        success: false,
        error: 'LOW_BALANCE',
        message: 'Insufficient account balance'
      };
    }
    
    if (message.includes('duplicated_ref')) {
      return {
        success: false,
        error: 'DUPLICATE_REF',
        message: 'This reference has already been used'
      };
    }
    
    return {
      success: false,
      error: 'UNKNOWN',
      message: 'Failed to process order. Please try again.'
    };
  }
}

Bonnes pratiques

Valider en premier

Toujours utiliser /check-number avant d’envoyer

Vérifier le stock

Vérifier la disponibilité du produit avant la commande

Références uniques

Générer un ref unique pour chaque commande

Stocker immédiatement

Sauvegarder topupId dès la soumission réussie

Après la soumission de la commande

1

Stocker l'ID de recharge

Sauvegarder topupId dans votre base de données immédiatement
2

Démarrer l'interrogation

Commencer à vérifier le statut toutes les 5-10 secondes
3

Mettre à jour l'interface

Afficher le message « Traitement de la commande… » à l’utilisateur
4

Attendre l'état final

Continuer l’interrogation jusqu’à FULFILLED, REFUNDED ou QUEUED

Étapes suivantes

Suivre le statut

Interroger le statut de la commande jusqu’à son achèvement

Livrer les cartes

Livrer les codes de carte aux clients

Référence API

Documentation complète de l’endpoint

Valider les numéros

Vérifier les numéros de téléphone d’abord

Vue d'ensemble

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

Vérifier le solde

Obtenir le solde du compte