Envoyer une Recharge Mobile

curl --request POST \
  --url https://api.oneclickdz.com/v3/mobile/send \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Token: <api-key>' \
  --data '
{
  "plan_code": "<string>",
  "MSSIDN": "<string>",
  "amount": 123,
  "ref": "<string>"
}
'

{
  "success": true,
  "data": {
    "topupId": "<string>",
    "topupRef": "<string>"
  },
  "meta": {
    "timestamp": "<string>"
  }
}

POST

mobile

send

Envoyer une Recharge Mobile

curl --request POST \
  --url https://api.oneclickdz.com/v3/mobile/send \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Token: <api-key>' \
  --data '
{
  "plan_code": "<string>",
  "MSSIDN": "<string>",
  "amount": 123,
  "ref": "<string>"
}
'

{
  "success": true,
  "data": {
    "topupId": "<string>",
    "topupRef": "<string>"
  },
  "meta": {
    "timestamp": "<string>"
  }
}

Vue d’Ensemble

Envoyez des recharges mobiles instantanées aux opérateurs algériens (Mobilis, Djezzy, Ooredoo, Pixx) avec suivi du statut en temps réel.

Recommandé : Utilisez le paramètre ref unique pour prévenir les commandes en double et faciliter le suivi.

Corps de la Requête

plan_code

string

requis

Code de forfait depuis l’endpoint /mobile/plans (ex. : PREPAID_DJEZZY, PIXX_500)

MSSIDN

string

requis

Numéro de téléphone au format 0[567][0-9]{8} (doit être une chaîne, pas un nombre) Exemples : "0778037340", "0665983439", "0556121212"

amount

integer

Montant de recharge en DZD (requis pour les forfaits dynamiques, ignoré pour les forfaits fixes) Doit être compris entre min_amount et max_amount des détails du forfait

ref

string

Votre référence de commande unique pour le suivi (générée automatiquement si non fournie) Important : Prévient les requêtes en double si la même référence est soumise deux fois

Réponse

success

boolean

requis

Indique si la requête a été soumise avec succès

data

object

requis

Afficher properties

topupId

string

Identifiant interne de la recharge pour le suivi du statut

topupRef

string

Votre référence (la référence fournie ou générée automatiquement)

Exemples

curl https://api.oneclickdz.com/v3/mobile/send \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "amount": 500,
    "ref": "order-12345"
  }'

Réponse de Succès

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "API-+213665983439-test-1761698159224-success"
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:59.454Z"
  }
}

Réponses d’Erreur

400 - Erreurs de Validation

Corps ou paramètres de requête invalides

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "body/MSSIDN must match pattern \"^0[567][0-9]{8}$\"",
    "details": {
      "field": "MSSIDN",
      "value": "778037340"
    }
  },
  "requestId": "req_1730160959_xyz789"
}

Erreurs de validation courantes :

plan_code ou MSSIDN manquant
Format de numéro de téléphone invalide
amount requis pour les forfaits dynamiques
amount hors plage min/max
MSSIDN ne correspond pas à l’opérateur du forfait

403 - Solde Insuffisant

Solde insuffisant pour l’opération

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your balance is insufficient for this operation",
    "details": {
      "required": 500,
      "available": 250
    }
  },
  "requestId": "req_1730160959_def456"
}

403 - Référence en Double

Référence déjà utilisée

{
  "success": false,
  "error": {
    "code": "DUPLICATED-REF",
    "message": "This reference ID is already in use."
  },
  "requestId": "req_1730160959_ghi789"
}

Solution : Vérifiez le statut de la recharge existante en utilisant la même référence

500 - Erreur Interne

Erreur serveur (rare)

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Developer was notified and will check shortly"
  },
  "requestId": "req_1730160959_jkl012"
}

Action : Contactez le support avec le requestId. Ne remboursez PAS avant investigation.

Prévention des Requêtes Dupliquées

Le champ ref garantit que la recharge est traitée une seule fois, même en cas de problèmes réseau.

async function sendTopUpSafe(planCode, phone, amount, orderId) {
  // Use orderId as the ref for idempotency
  const ref = `topup-${orderId}`;

  try {
    const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
      method: "POST",
      headers: {
        "X-Access-Token": API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        plan_code: planCode,
        MSSIDN: phone,
        amount,
        ref,
      }),
    });

    const data = await response.json();

    if (data.success) {
      return { success: true, topupId: data.data.topupId };
    }

    // Handle duplicate ref - order already exists
    if (data.error.code === "DUPLICATED-REF") {
      const status = await checkTopUpByRef(ref);
      return { success: true, topupId: status.data._id, fromExisting: true };
    }

    throw new Error(`${data.error.code}: ${data.error.message}`);
  } catch (networkError) {
    // Network error - check if order was created
    const status = await checkTopUpByRef(ref);
    if (status.success) {
      return { success: true, topupId: status.data._id, fromExisting: true };
    }
    throw networkError;
  }
}

Format du Numéro de Téléphone

Le numéro de téléphone doit être une chaîne, pas un nombre. Le zéro initial est obligatoire.

Formats valides :

✅ "0778037340" (chaîne avec zéro initial)
✅ "0665983439"
✅ "0556121212"

Formats invalides :

❌ 778037340 (zéro initial manquant)
❌ 0778037340 (type nombre au lieu de chaîne)
❌ "+213778037340" (format international)
❌ "0778 037 340" (contient des espaces)

Cycle de Vie du Statut

Après l’envoi d’une recharge, elle passe par ces états :

PENDING

Commande créée et mise en file d’attente pour traitement Durée : 2 à 15 secondes (typique)

HANDLING

Actuellement en cours de traitement par l’opérateur Durée : 3 à 8 secondes (typique)

État Final

FULFILLED : Complété avec succès ✅ REFUNDED : Échoué et remboursé ❌ UNKNOWN_ERROR : État incertain (se résout en 24h) ⚠️

En savoir plus sur le Suivi du Statut →

Flux d’Intégration Recommandé

Créer la Commande dans Votre BD

const order = await db.orders.create({
  id: generateOrderId(),
  userId: user.id,
  phone: '0778037340',
  amount: 500,
  status: 'PROCESSING'
});

Déduire le Solde Utilisateur

await db.users.update({
  id: user.id,
  balance: user.balance - 500
});

Retourner la Commande à l'Utilisateur

res.json({
  orderId: order.id,
  status: 'PROCESSING',
  message: 'Top-up is being processed'
});

Async : Envoyer à l'API

// In background job
const response = await sendTopup({
  plan_code: 'PREPAID_DJEZZY',
  MSSIDN: order.phone,
  amount: order.amount,
  ref: order.id
});

await db.orders.update({
  id: order.id,
  apiTopupId: response.data.topupId
});

Interroger le Statut et Mettre à Jour

const status = await checkTopupStatus(order.id);

await db.orders.update({
  id: order.id,
  status: status.data.status
});

if (status.data.status === 'REFUNDED') {
  await refundUserBalance(user.id, order.amount);
}

Tests en Sandbox

Activez le mode sandbox pour tester sans transactions réelles :

Flux Normal

Utilisez n’importe quel numéro normal (ex. : 0778037340) Flux : PENDING (5s) → HANDLING (15s) → FULFILLED

Remboursement avec Message

Utilisez : 0600000001 Retourne : REFUNDED avec refund_message

Non-correspondance de Forfait

Utilisez : 0600000002 Retourne : REFUNDED avec suggested_offers

Erreur Inconnue

Utilisez : 0600000003 Retourne : statut UNKNOWN_ERROR

Bonnes Pratiques

Utiliser des Références Uniques

Fournissez toujours un ref unique pour prévenir les doublons et faciliter le suivi

Valider Avant Soumission

Vérifiez le forfait, le format du téléphone et le solde côté client pour réduire les erreurs

Gérer de Manière Asynchrone

Traitez les appels API de manière asynchrone pour éviter de bloquer les requêtes utilisateur

Implémenter une Logique de Nouvelle Tentative

Réessayez les requêtes échouées avec un backoff exponentiel pour les erreurs réseau

Endpoints Associés

Lister les Forfaits

Obtenir les forfaits disponibles

Vérifier par Référence

Suivre avec votre référence

Vérifier par ID

Suivre avec l’ID de recharge

Lister les Forfaits Mobile Vérifier le Statut par ID

Documentation Index

​Vue d’Ensemble

​Corps de la Requête

​Réponse

​Exemples

​Réponse de Succès

​Réponses d’Erreur

​Prévention des Requêtes Dupliquées

​Format du Numéro de Téléphone

​Cycle de Vie du Statut

​Flux d’Intégration Recommandé

​Tests en Sandbox

Flux Normal

Remboursement avec Message

Non-correspondance de Forfait

Erreur Inconnue

​Bonnes Pratiques

Utiliser des Références Uniques

Valider Avant Soumission

Gérer de Manière Asynchrone

Implémenter une Logique de Nouvelle Tentative

​Endpoints Associés

Lister les Forfaits

Vérifier par Référence

Vérifier par ID

Vue d’Ensemble

Corps de la Requête

Réponse

Exemples

Réponse de Succès

Réponses d’Erreur

Prévention des Requêtes Dupliquées

Format du Numéro de Téléphone

Cycle de Vie du Statut

Flux d’Intégration Recommandé

Tests en Sandbox

Bonnes Pratiques

Endpoints Associés