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
Code de forfait depuis l’endpoint /mobile/plans (ex. : PREPAID_DJEZZY, PIXX_500)
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"
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
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
Indique si la requête a été soumise avec succès
Identifiant interne de la recharge pour le suivi du statut
Votre référence (la référence fournie ou générée automatiquement)
Horodatage de la requête au format ISO 8601
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
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
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 ;
}
}
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