پرش به محتوای مستندات
شروع سریع
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 دوباره درخواست بفرستید.
در وضعیت‌های نیازمند اقدام، سفارش را خودکار دوباره ثبت نکنید.