البدء السريع - OneClickDz Flexy API

الحصول على مفتاح API

إنشاء حساب

أنشئ حساباً مجانياً على app.oneclickdz.com

إنشاء مفاتيح API

انتقل إلى الإعدادات ← قسم API ← إنشاء مفتاح APIستحصل على مفتاحين:

Sandbox: للاختبار دون معاملات حقيقية
Production: للمعاملات الفعلية

تأمين مفاتيحك

خزّن المفاتيح بشكل آمن في متغيرات البيئة. لا تعرضها أبداً في الكود من جانب العميل أو في نظام إدارة الإصدارات.

ابدأ دائماً بوضع Sandbox لاختبار التكامل بأمان.

التحقق من مفتاح API

اختبر مفتاح API باستخدام endpoint التحقق:

curl https://api.oneclickdz.com/v3/validate \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch("https://api.oneclickdz.com/v3/validate", {
  headers: { "X-Access-Token": "YOUR_API_KEY" },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.oneclickdz.com/v3/validate",
    headers={"X-Access-Token": "YOUR_API_KEY"}
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/validate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
$response = curl_exec($ch);
echo $response;
?>

الاستجابة:

{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "type": "SANDBOX",
      "scope": "READ-WRITE",
      "isEnabled": true
    }
  }
}

إذا رأيت "success": true، فمفتاح API الخاص بك يعمل بشكل صحيح!

الخطوة 1: إرسال شحن هاتف

أرسل شحنة بقيمة 500 دج إلى رقم Djezzy:

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-001"
  }'

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-001",
  }),
});
const data = await response.json();

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-001'
    }
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/mobile/send");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Access-Token: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'plan_code' => 'PREPAID_DJEZZY',
    'MSSIDN' => '0778037340',
    'amount' => 500,
    'ref' => 'order-001'
]));
$response = curl_exec($ch);
echo $response;
?>

الاستجابة:

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "order-001"
  }
}

الخطوة 2: التحقق من حالة الشحن

تحقق من حالة الشحن باستخدام المرجع:

curl https://api.oneclickdz.com/v3/mobile/check-ref/order-001 \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch(
  "https://api.oneclickdz.com/v3/mobile/check-ref/order-001",
  { headers: { "X-Access-Token": "YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.oneclickdz.com/v3/mobile/check-ref/order-001',
    headers={'X-Access-Token': 'YOUR_API_KEY'}
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/mobile/check-ref/order-001");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
$response = curl_exec($ch);
echo $response;
?>

الاستجابة:

{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "MSSIDN": "0778037340",
    "topup_amount": 500
  }
}

تسلسل الحالة: PENDING (5 ثواني) → HANDLING (15 ثانية) → FULFILLED ✅

الخطوة 3: إرسال شحن إنترنت

اشحن خطاً ADSL ببطاقة 1000 دينار:

curl https://api.oneclickdz.com/v3/internet/send \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "type": "ADSL",
    "number": "036362608",
    "value": 1000,
    "ref": "internet-001"
  }'

const response = await fetch("https://api.oneclickdz.com/v3/internet/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Access-Token": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    type: "ADSL",
    number: "036362608",
    value: 1000,
    ref: "internet-001",
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.oneclickdz.com/v3/internet/send',
    headers={
        'Content-Type': 'application/json',
        'X-Access-Token': 'YOUR_API_KEY'
    },
    json={
        'type': 'ADSL',
        'number': '036362608',
        'value': 1000,
        'ref': 'internet-001'
    }
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/internet/send");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Access-Token: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'type' => 'ADSL',
    'number' => '036362608',
    'value' => 1000,
    'ref' => 'internet-001'
]));
$response = curl_exec($ch);
echo $response;
?>

الاستجابة:

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b1",
    "topupRef": "internet-001"
  }
}

تحقق من حالة شحن الإنترنت:

curl https://api.oneclickdz.com/v3/internet/check-ref/internet-001 \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch(
  "https://api.oneclickdz.com/v3/internet/check-ref/internet-001",
  { headers: { "X-Access-Token": "YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.oneclickdz.com/v3/internet/check-ref/internet-001',
    headers={'X-Access-Token': 'YOUR_API_KEY'}
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/internet/check-ref/internet-001");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
$response = curl_exec($ch);
echo $response;
?>

الاستجابة:

{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "card_code": "123456789012",
    "num_trans": "AT-2025-001"
  }
}

الخطوة 4: استكشاف بطاقات الهدايا

احصل على كتالوج المنتجات لرؤية بطاقات الهدايا المتاحة:

curl https://api.oneclickdz.com/v3/gift-cards/catalog \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch(
  "https://api.oneclickdz.com/v3/gift-cards/catalog",
  { headers: { "X-Access-Token": "YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.oneclickdz.com/v3/gift-cards/catalog',
    headers={'X-Access-Token': 'YOUR_API_KEY'}
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/catalog");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
$response = curl_exec($ch);
echo $response;
?>

اطلب بطاقة هدية:

curl https://api.oneclickdz.com/v3/gift-cards/placeOrder \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "productId": "PRODUCT_ID",
    "typeId": "TYPE_ID",
    "quantity": 1
  }'

const response = await fetch(
  "https://api.oneclickdz.com/v3/gift-cards/placeOrder",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      productId: "PRODUCT_ID",
      typeId: "TYPE_ID",
      quantity: 1,
    }),
  }
);
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.oneclickdz.com/v3/gift-cards/placeOrder',
    headers={
        'Content-Type': 'application/json',
        'X-Access-Token': 'YOUR_API_KEY'
    },
    json={
        'productId': 'PRODUCT_ID',
        'typeId': 'TYPE_ID',
        'quantity': 1
    }
)
print(response.json())

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/placeOrder");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Access-Token: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'productId' => 'PRODUCT_ID',
    'typeId' => 'TYPE_ID',
    'quantity' => 1
]));
$response = curl_exec($ch);
echo $response;
?>

الاستجابة:

{
  "success": true,
  "data": {
    "orderId": "6901616fe9e88196b4eb64c0"
  }
}

احصل على أكواد بطاقات الهدايا بالتحقق من حالة الطلب:

curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64c0 \
  -H "X-Access-Token: YOUR_API_KEY"

// Poll order status until fulfilled
async function getGiftCardCodes(orderId) {
  let status = 'HANDLING';
  
  while (status === 'HANDLING') {
    const response = await fetch(
      `https://api.oneclickdz.com/v3/gift-cards/checkOrder/${orderId}`,
      { headers: { "X-Access-Token": "YOUR_API_KEY" } }
    );
    const { data } = await response.json();
    status = data.status;
    
    if (status === 'FULFILLED') {
      return data.cards; // Array of {value, serial}
    }
    
    await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds
  }
}

const cards = await getGiftCardCodes('6901616fe9e88196b4eb64c0');
console.log('Card codes:', cards);

import time
import requests

def get_gift_card_codes(order_id):
    status = 'HANDLING'
    
    while status == 'HANDLING':
        response = requests.get(
            f'https://api.oneclickdz.com/v3/gift-cards/checkOrder/{order_id}',
            headers={'X-Access-Token': 'YOUR_API_KEY'}
        )
        data = response.json()['data']
        status = data['status']
        
        if status == 'FULFILLED':
            return data['cards']  # List of {'value': ..., 'serial': ...}
        
        time.sleep(5)  # Wait 5 seconds

cards = get_gift_card_codes('6901616fe9e88196b4eb64c0')
print('Card codes:', cards)

<?php
function getGiftCardCodes($orderId, $apiKey) {
    $status = 'HANDLING';
    
    while ($status === 'HANDLING') {
        $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/checkOrder/{$orderId}");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: {$apiKey}"]);
        $response = json_decode(curl_exec($ch), true);
        $status = $response['data']['status'];
        
        if ($status === 'FULFILLED') {
            return $response['data']['cards'];
        }
        
        sleep(5); // Wait 5 seconds
    }
}

$cards = getGiftCardCodes('6901616fe9e88196b4eb64c0', 'YOUR_API_KEY');
print_r($cards);
?>

الاستجابة عند اكتمال الطلب:

{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      }
    ]
  }
}

تُستخرج أكواد البطاقات من مصفوفة cards عندما تكون الحالة FULFILLED

اختبار Sandbox

في وضع sandbox، اختبر هذه السيناريوهات الخاصة مع شحن الهاتف:

رقم الهاتف	السلوك	الغرض
أي رقم عادي (مثل `0778037340`)	نجاح: PENDING → HANDLING → FULFILLED	اختبار المعاملات الناجحة
`0600000001`	REFUNDED مع رسالة خطأ	اختبار معالجة الاسترداد
`0600000002`	REFUNDED مع اقتراحات خطط بديلة	اختبار عدم تطابق الخطة
`0600000003`	حالة UNKNOWN_ERROR	اختبار معالجة الحالات غير المؤكدة

يتضمن كل دليل سير عمل تعليمات اختبار sandbox شاملة مع أمثلة.

فهم تنسيق الاستجابة

تتبع جميع استجابات API هذا الهيكل:

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "...",
    "pagination": { ... }
  },
  "requestId": "..."
}

تعرف على تنسيق الاستجابة ←

الخطوات التالية

دليل شحن الهاتف

سير عمل التكامل الكامل

دليل شحن الإنترنت

ADSL و4G مع اختبار sandbox

دليل بطاقات الهدايا

توصيل المنتجات الرقمية

معالجة الأخطاء

التعامل مع الأخطاء بشكل صحيح

المصادقة

أنماط الوصول الآمن إلى API

أفضل الممارسات

أمان جاهز للإنتاج

هل تحتاج مساعدة؟ راجع صفحة التواصل والدعم أو راسلنا على [email protected]

​الحصول على مفتاح API

​التحقق من مفتاح API

​الخطوة 1: إرسال شحن هاتف

​الخطوة 2: التحقق من حالة الشحن

​الخطوة 3: إرسال شحن إنترنت

​الخطوة 4: استكشاف بطاقات الهدايا

​اختبار Sandbox

​فهم تنسيق الاستجابة

​الخطوات التالية

دليل شحن الهاتف

دليل شحن الإنترنت

دليل بطاقات الهدايا

معالجة الأخطاء

المصادقة

أفضل الممارسات

الحصول على مفتاح API

التحقق من مفتاح API

الخطوة 1: إرسال شحن هاتف

الخطوة 2: التحقق من حالة الشحن

الخطوة 3: إرسال شحن إنترنت

الخطوة 4: استكشاف بطاقات الهدايا

اختبار Sandbox

فهم تنسيق الاستجابة

الخطوات التالية