مستندات وبسرویس

(v1.0)

نیاز به راهنمایی دارید؟

تیم پشتیبانی ما آماده کمک به شماست.

تماس با پشتیبانی

اندپوینت‌های سفارشات

از اندپوینت‌های سفارشات برای ثبت سفارش، پیگیری وضعیت سفارش و دریافت اطلاعات سفارشات قبلی استفاده کنید.

ثبت سفارش جدید
/api/v1/ordersPOST

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

پارامترها

نامنوعضروریتوضیحات
productsarrayبلهآرایه‌ای از محصولات برای سفارش
products[].productIdnumberبلهشناسه محصول
products[].regionPropertyIdnumberبلهشناسه ویژگی منطقه محصول (قیمت/مقدار)
products[].quantitynumberخیرتعداد (پیش‌فرض: 1)
requiredFieldsobjectبلهفیلدهای مورد نیاز برای هر محصول

مثال درخواست

{
  "products": [
    {
      "productId": 123,
      "regionPropertyId": 101,
      "quantity": 1
    }
  ],
  "requiredFields": {
    "123": [
      {
        "fieldId": 1,
        "value": "example@gmail.com"
      }
    ]
  }
}

مثال پاسخ

{
  "status": "success",
  "code": 200,
  "message": "سفارش با موفقیت ثبت شد",
  "data": {
    "orderId": 5678,
    "orderReference": "A1234567",
    "amount": 490000,
    "status": "PREPARING",
    "items": [
      {
        "id": 9876,
        "productId": 123,
        "quantity": 1,
        "totalAmount": 490000
      }
    ]
  }
}

دریافت لیست سفارشات
/api/v1/ordersGET

این اندپوینت لیست تمام سفارشات شما را با امکان فیلترکردن و صفحه‌بندی ارائه می‌دهد. سفارشات ثبت شده از طریق API با پیشوند 'A' در شناسه مرجع مشخص می‌شوند.

پارامترها

نامنوعضروریتوضیحات
pagenumberخیرشماره صفحه (پیش‌فرض: 1)
pageSizenumberخیرتعداد سفارشات در هر صفحه (پیش‌فرض: 10)
statusstringخیرفیلتر براساس وضعیت سفارش (PREPARING, PENDING_CONFIRMATION, COMPLETED, CANCELED, RETURNED, UNPAID)
dateFromstringخیرفیلتر بر اساس تاریخ شروع (فرمت: YYYY-MM-DD)
dateTostringخیرفیلتر بر اساس تاریخ پایان (فرمت: YYYY-MM-DD)

مثال پاسخ

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": 5678,
      "reference": "A1234567",
      "total": 490000,
      "status": "COMPLETED",
      "createdAt": "2023-05-15T10:30:45Z",
      "items": [
        {
          "id": 9876,
          "productId": 123,
          "productName": "گیفت کارت استیم 10 دلاری",
          "productImg": "https://gift30t.com/images/products/steam.png",
          "quantity": 1,
          "totalAmount": 490000,
          "fields": [
            {
              "name": "ایمیل",
              "value": "example@gmail.com"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 15,
      "page": 1,
      "pageSize": 10,
      "totalPages": 2
    }
  }
}

دریافت جزئیات سفارش
/api/v1/orders/:idGET

این اندپوینت جزئیات کامل یک سفارش خاص را بر اساس شناسه آن ارائه می‌دهد.

پارامترها

نامنوعضروریتوضیحات
idnumberبلهشناسه سفارش

مثال پاسخ

{
  "status": "success",
  "code": 200,
  "data": {
    "id": 5678,
    "reference": "A1234567",
    "total": 490000,
    "status": "COMPLETED",
    "createdAt": "2023-05-15T10:30:45Z",
    "completedAt": "2023-05-15T10:32:10Z",
    "items": [
      {
        "id": 9876,
        "productId": 123,
        "productName": "گیفت کارت استیم 10 دلاری",
        "productImg": "https://gift30t.com/images/products/steam.png",
        "quantity": 1,
        "totalAmount": 490000,
        "fields": [
          {
            "name": "ایمیل",
            "value": "example@gmail.com"
          }
        ],
        "delivery": {
          "voucherCode": "STEAM-XXXX-XXXX-XXXX",
          "redeemGuide": "برای فعال‌سازی کد، به وب‌سایت استیم مراجعه کنید و..."
        }
      }
    ],
    "transaction": {
      "trans_id": "API_1234567",
      "amount": 490000,
      "status": "SUCCESS",
      "createdAt": "2023-05-15T10:30:45Z"
    }
  }
}

نکات مهم

  • قبل از ثبت سفارش، اطمینان حاصل کنید که کیف پول شما موجودی کافی دارد.
  • برای هر محصول، باید تمام فیلدهای مورد نیاز را پر کنید. این فیلدها را می‌توانید از طریق اندپوینت جزئیات محصول دریافت کنید.
  • سفارشات ثبت شده از طریق API با پیشوند ‘A‘ در شناسه مرجع (reference) مشخص می‌شوند. این امر به شما امکان تشخیص سفارشات API را می‌دهد.
  • پس از ثبت سفارش، وضعیت آن به PREPARING تغییر می‌کند. در بعضی موارد خاص، ممکن است وضعیت به PENDING_CONFIRMATION تغییر کند که نیاز به تأیید مدیر دارد.
  • اطلاعات تحویل (کد ووچر و راهنمای فعال‌سازی) پس از تکمیل سفارش در بخش deliveryقابل دسترس خواهد بود.