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>"
}
'import requests
url = "https://api.oneclickdz.com/v3/mobile/send"
payload = {
"plan_code": "<string>",
"MSSIDN": "<string>",
"amount": 123,
"ref": "<string>"
}
headers = {
"X-Access-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({plan_code: '<string>', MSSIDN: '<string>', amount: 123, ref: '<string>'})
};
fetch('https://api.oneclickdz.com/v3/mobile/send', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.oneclickdz.com/v3/mobile/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'plan_code' => '<string>',
'MSSIDN' => '<string>',
'amount' => 123,
'ref' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.oneclickdz.com/v3/mobile/send"
payload := strings.NewReader("{\n \"plan_code\": \"<string>\",\n \"MSSIDN\": \"<string>\",\n \"amount\": 123,\n \"ref\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Access-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.oneclickdz.com/v3/mobile/send")
.header("X-Access-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"plan_code\": \"<string>\",\n \"MSSIDN\": \"<string>\",\n \"amount\": 123,\n \"ref\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/mobile/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"plan_code\": \"<string>\",\n \"MSSIDN\": \"<string>\",\n \"amount\": 123,\n \"ref\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"topupId": "<string>",
"topupRef": "<string>"
},
"meta": {
"timestamp": "<string>"
}
}Recharges mobiles
Envoyer une Recharge Mobile
Créer et envoyer une demande de recharge mobile
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>"
}
'import requests
url = "https://api.oneclickdz.com/v3/mobile/send"
payload = {
"plan_code": "<string>",
"MSSIDN": "<string>",
"amount": 123,
"ref": "<string>"
}
headers = {
"X-Access-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({plan_code: '<string>', MSSIDN: '<string>', amount: 123, ref: '<string>'})
};
fetch('https://api.oneclickdz.com/v3/mobile/send', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.oneclickdz.com/v3/mobile/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'plan_code' => '<string>',
'MSSIDN' => '<string>',
'amount' => 123,
'ref' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.oneclickdz.com/v3/mobile/send"
payload := strings.NewReader("{\n \"plan_code\": \"<string>\",\n \"MSSIDN\": \"<string>\",\n \"amount\": 123,\n \"ref\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Access-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.oneclickdz.com/v3/mobile/send")
.header("X-Access-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"plan_code\": \"<string>\",\n \"MSSIDN\": \"<string>\",\n \"amount\": 123,\n \"ref\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.oneclickdz.com/v3/mobile/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"plan_code\": \"<string>\",\n \"MSSIDN\": \"<string>\",\n \"amount\": 123,\n \"ref\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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
string
requis
Code de forfait depuis l’endpoint
/mobile/plans (ex. : PREPAID_DJEZZY, PIXX_500)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"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 forfaitstring
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
boolean
requis
Indique si la requête a été soumise avec succès
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"
}'
const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Access-Token": "YOUR_API_KEY",
},
body: JSON.stringify({
plan_code: "PREPAID_DJEZZY",
MSSIDN: "0778037340",
amount: 500,
ref: "order-12345",
}),
});
const data = await response.json();
console.log(data.data.topupId);
import requests
response = requests.post(
'https://api.oneclickdz.com/v3/mobile/send',
headers={
'Content-Type': 'application/json',
'X-Access-Token': 'YOUR_API_KEY'
},
json={
'plan_code': 'PREPAID_DJEZZY',
'MSSIDN': '0778037340',
'amount': 500,
'ref': 'order-12345'
}
)
topup_id = response.json()['data']['topupId']
<?php
$data = [
'plan_code' => 'PREPAID_DJEZZY',
'MSSIDN' => '0778037340',
'amount' => 500,
'ref' => 'order-12345'
];
$ch = curl_init('https://api.oneclickdz.com/v3/mobile/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'X-Access-Token: YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = json_decode(curl_exec($ch), true);
$topupId = $response['data']['topupId'];
?>
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
400 - Erreurs de Validation
Corps ou paramètres de requête invalidesErreurs de validation courantes :
{
"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"
}
plan_codeouMSSIDNmanquant- Format de numéro de téléphone invalide
amountrequis pour les forfaits dynamiquesamounthors plage min/max- MSSIDN ne correspond pas à l’opérateur du forfait
403 - Solde Insuffisant
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
403 - Référence en Double
Référence déjà utiliséeSolution : Vérifiez le statut de la recharge existante en utilisant la même référence
{
"success": false,
"error": {
"code": "DUPLICATED-REF",
"message": "This reference ID is already in use."
},
"requestId": "req_1730160959_ghi789"
}
500 - Erreur Interne
500 - Erreur Interne
Erreur serveur (rare)Action : Contactez le support avec le
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Developer was notified and will check shortly"
},
"requestId": "req_1730160959_jkl012"
}
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.
- ✅
"0778037340"(chaîne avec zéro initial) - ✅
"0665983439" - ✅
"0556121212"
- ❌
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) ⚠️
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) → FULFILLEDRemboursement avec Message
Utilisez :
0600000001 Retourne : REFUNDED avec refund_messageNon-correspondance de Forfait
Utilisez :
0600000002 Retourne : REFUNDED avec suggested_offersErreur Inconnue
Utilisez :
0600000003 Retourne : statut UNKNOWN_ERRORBonnes Pratiques
Utiliser des Références Uniques
Fournissez toujours un
ref unique pour prévenir les doublons et faciliter le suiviValider 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

