Passer au contenu principal
POST
/
v3
/
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>"
  }
}

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 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
meta
object
requis

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

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

PENDING

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

HANDLING

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

É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é

1

Créer la Commande dans Votre BD

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

Déduire le Solde Utilisateur

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

Retourner la Commande à l'Utilisateur

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

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

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