نظرة عامة
بعد التحقق من توفر المنتج، قدّم طلب بطاقة الهدية عبر endpoint الطلب. يستدعي الطلب الناجح إرجاع معرّف الطلب الذي ستستخدمه لتتبع الحالة.تحقق دائماً من المخزون والرصيد قبل تقديم الطلب لتجنب الأخطاء.
مرجع API
POST /v3/gift-cards/placeOrder
التوثيق الكامل للـ endpoint
تقديم طلب أساسي
async function placeOrder(orderData) {
const response = await fetch(
"https://api.oneclickdz.com/v3/gift-cards/placeOrder",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Access-Token": process.env.API_KEY,
},
body: JSON.stringify({
productId: orderData.productId,
typeId: orderData.typeId,
ref: orderData.ref,
}),
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(error.error?.message || `HTTP ${response.status}`);
}
const result = await response.json();
return result.data;
}
// Usage
const order = await placeOrder({
productId: "507f1f77bcf86cd799439011",
typeId: "type_10",
ref: `order-${Date.now()}`
});
console.log('Order placed:', order.orderId);
import requests
import os
import time
def place_order(order_data):
response = requests.post(
'https://api.oneclickdz.com/v3/gift-cards/placeOrder',
headers={
'Content-Type': 'application/json',
'X-Access-Token': os.getenv('API_KEY')
},
json={
'productId': order_data['productId'],
'typeId': order_data['typeId'],
'ref': order_data['ref']
}
)
if not response.ok:
error = response.json()
raise Exception(error.get('error', {}).get('message', f'HTTP {response.status_code}'))
return response.json()['data']
# Usage
order = place_order({
'productId': '507f1f77bcf86cd799439011',
'typeId': 'type_10',
'ref': f'order-{int(time.time() * 1000)}'
})
print(f'Order placed: {order["orderId"]}')
<?php
function placeOrder($orderData, $apiKey) {
$data = [
'productId' => $orderData['productId'],
'typeId' => $orderData['typeId'],
'ref' => $orderData['ref']
];
$ch = curl_init('https://api.oneclickdz.com/v3/gift-cards/placeOrder');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'X-Access-Token: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode >= 400) {
$error = json_decode($response, true);
throw new Exception($error['error']['message'] ?? "HTTP {$httpCode}");
}
$result = json_decode($response, true);
return $result['data'];
}
// Usage
$order = placeOrder([
'productId' => '507f1f77bcf86cd799439011',
'typeId' => 'type_10',
'ref' => 'order-' . (int)(microtime(true) * 1000)
], getenv('API_KEY'));
echo "Order placed: {$order['orderId']}\n";
?>
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": "507f1f77bcf86cd799439011",
"typeId": "type_10",
"ref": "order-123456"
}'
مثال على الاستجابة
{
"success": true,
"data": {
"orderId": "6901616fe9e88196b4eb64b2",
"orderRef": "order-123456"
},
"meta": {
"timestamp": "2025-11-01T12:00:00.000Z"
}
}
معالجة الأخطاء
try:
order_id = place_order(product_id, type_id, quantity)
print(f"Success: {order_id}")
except Exception as error:
if 'stock' in str(error):
print("Out of stock")
elif 'balance' in str(error):
print("Insufficient balance")
else:
print(f"Order failed: {error}")
<?php
try {
$orderId = placeOrder($productId, $typeId, $quantity, $apiKey);
echo "Success: {$orderId}\n";
} catch (Exception $error) {
$errorMsg = strtolower($error->getMessage());
if (strpos($errorMsg, 'stock') !== false) {
echo "Out of stock\n";
} elseif (strpos($errorMsg, 'balance') !== false) {
echo "Insufficient balance\n";
} else {
echo "Order failed: " . $error->getMessage() . "\n";
}
}
?>
try {
const orderId = await placeOrder(productId, typeId, quantity);
console.log(`Success: ${orderId}`);
} catch (error) {
const errorMsg = error.message.toLowerCase();
if (errorMsg.includes("stock")) {
console.log("Out of stock");
} else if (errorMsg.includes("balance")) {
console.log("Insufficient balance");
} else {
console.log(`Order failed: ${error.message}`);
}
}
أفضل الممارسات
التحقق أولاً
تحقق دائماً من المخزون والرصيد قبل تقديم أي طلب
مرجعيات فريدة
أنشئ
ref فريداً لكل طلب لتجنب التكرارتخزين orderId
احفظ
orderId فوراً في قاعدة البيانات بعد نجاح الطلببدء الاستعلام
ابدأ استعلام الحالة فور تقديم الطلب بنجاح
الخطوات التالية
تتبع الحالة
استعلام حالة الطلب حتى اكتماله
التسليم الآمن
تسليم البطاقات بأمان للعملاء
مرجع API
التوثيق الكامل للـ endpoint

