مستندات API: ثبت سفارش خرید

اطلاعات پایه

POST

/giftcard/buy

نام API: خرید گیفت کارت
آدرس پایه: /giftcard/buy
متد: POST

پارامترهای درخواست

هدرها

کلید	مقدار	توضیحات
Authorization	Bearer {token}	توکن احراز هویت
Content-Type	application/json	نوع محتوای درخواست

بدنه درخواست

پارامتر	نوع	اجباری	توضیحات
sku	string	بله	شناسه محصول
quantity	integer	بله	تعداد سفارش
webhook_url	string	خیر	آدرس وب‌هوک برای اطلاع‌رسانی وضعیت سفارش

پاسخ‌های ممکن

موفقیت (200 OK)

				
					{
  "order_id": "ORDER-123",
  "status": "pending",
  "total_price": 100.00,
  "currency": "USD",
  "expires_at": "2024-03-20T12:00:00Z"
}

خطاها

400 Bad Request - پارامترهای ناقص

				
					{
  "code": "rest_missing_parameters",
  "message": "پارامترهای الزامی وجود ندارد",
  "data": {
    "status": 400
  }
}

404 Not Found - محصول یافت نشد

				
					{
  "error": "محصول یافت نشد",
  "sku": "PRODUCT-SKU"
}

400 Bad Request - موجودی ناکافی

				
					{
  "error": "موجودی ناکافی",
  "required": 100.00,
  "available": 50.00
}

نکات مهم

مبلغ سفارش بعد از تایید از موجودی حساب کسر می‌شود در صورت عدم تایید سفارش، مبلغی از کیف پول کسر نمیگردد.

سفارش‌ها به مدت 30 دقیقه معتبر هستند در صورت عدم تایید پس از 30 دقیقه منقضی میشوند.

وب‌هوک باید HTTPS باشد و در کمتر از 3 ثانیه پاسخ دهد در صورت وجود خطا در وب هوک، اطلاع رسانی وب هوک متوقف میشود.

مثال‌های کد

cURL

				
					curl -X POST \
  '{base_url}/giftcard/buy' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "sku": "PRODUCT-SKU",
    "quantity": 1,
    "webhook_url": "https://example.com/webhook"
  }'

PHP

				
					$ch = curl_init('{base_url}/giftcard/buy');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer {token}',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'sku' => 'PRODUCT-SKU',
    'quantity' => 1,
    'webhook_url' => 'https://example.com/webhook'
]));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

Python

				
					import requests

headers = {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
}

data = {
    'sku': 'PRODUCT-SKU',
    'quantity': 1,
    'webhook_url': 'https://example.com/webhook'
}

response = requests.post('{base_url}/giftcard/buy',
    headers=headers,
    json=data)
data = response.json()

Node.js

				
					const axios = require("axios");

const response = await axios.post("{base_url}/giftcard/buy", {
  sku: "PRODUCT-SKU",
  quantity: 1,
  webhook_url: "https://example.com/webhook"
}, {
  headers: {
    Authorization: "Bearer {token}",
    "Content-Type": "application/json"
  }
});

const data = response.data;