Getting started
شروع سریع
از ساخت کلید تا ثبت و پیگیری اولین سفارش را مرحلهبهمرحله انجام دهید. همه درخواستها باید از سرور شما و روی HTTPS ارسال شوند.
۱. ساخت و نگهداری API Key
کلید را از پنل API دریافت کنید و در secret manager یا متغیر محیطی سرور نگه دارید. آن را داخل JavaScript مرورگر، اپ موبایل یا مخزن عمومی قرار ندهید.
متغیر محیطی سمت سرورbash
GIFTCITY_API_KEY=YOUR_API_KEY۲. انتخاب محصول و پراپرتی قیمت
ابتدا کاتالوگ را دریافت کنید. سپس endpoint جزئیات محصول را فراخوانی کنید تا regionPropertyId، قیمت، موجودی و فیلدهای الزامی همان محصول را داشته باشید.
دریافت فهرست محصولاتbash
curl --request GET \
--url "https://gift30t.ir/api/v1/products?page=1&pageSize=10" \
--header "Accept: application/json" \
--header "X-API-KEY: YOUR_API_KEY"دریافت جزئیات محصولbash
curl --request GET \
--url "https://gift30t.ir/api/v1/products/123" \
--header "Accept: application/json" \
--header "X-API-KEY: YOUR_API_KEY"۳. ثبت سفارش
مقدارهای productId، regionPropertyId و فیلدهای لازم را مستقیماً از جزئیات محصول بگیرید. مبلغ سفارش بهصورت اتمیک از کیف پول همان حساب کم میشود.
POST /ordersbash
curl --request POST \
--url "https://gift30t.ir/api/v1/orders" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--header "X-API-KEY: YOUR_API_KEY" \
--data '{
"products": [
{
"productId": 123,
"regionPropertyId": 101,
"quantity": 1
}
],
"requiredFields": {
"123": [
{
"fieldId": 1,
"value": "customer@example.com"
}
]
}
}'نمونه پاسخ ثبت سفارشjson
{
"status": "success",
"code": 200,
"message": "سفارش با موفقیت ثبت شد",
"data": {
"orderId": 5678,
"orderReference": "A1234567",
"amount": 490000,
"status": "PREPARING",
"items": [
{
"id": 9876,
"productId": 123,
"quantity": 1,
"totalAmount": 490000
}
]
}
}۴. ذخیره شناسه و پیگیری نتیجه
هر دو مقدار orderId و orderReference را در سیستم خود ذخیره کنید. endpoint جزئیات، شناسه عددی یا reference دارای پیشوند A را میپذیرد.
پیگیری با reference سفارشbash
curl --request GET \
--url "https://gift30t.ir/api/v1/orders/A1234567" \
--header "Accept: application/json" \
--header "X-API-KEY: YOUR_API_KEY"تا رسیدن به وضعیت نهایی، پاسخ را با فاصله منطقی بررسی کنید.
در وضعیت COMPLETED، بخش delivery هر آیتم را بخوانید.
در خطای 429 طبق Retry-After دوباره درخواست بفرستید.
در وضعیتهای نیازمند اقدام، سفارش را خودکار دوباره ثبت نکنید.