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

سفارش‌ها با UUID ای ساخته می‌شوند که خودتان تولید می‌کنید. همان UUID کلید idempotency است: تکرار آن به‌جای کسر دوباره، همان سفارش اصلی را برمی‌گرداند. وضعیت سپس برای هر سفارش، در دسته‌های حداکثر پنجاه‌تایی یا در قالب فهرست صفحه‌بندی‌شده خوانده می‌شود.

POST

/orders/create

ثبت سفارش

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

محدودیت نرخ۵۰۰۰ درخواست در ۶۰ ثانیه برای هر حساب

نکته: order_id کلید جلوگیری از تکرار (idempotency key) شماست. اگر با همان UUID دوباره درخواست بفرستید، به جای ساخت سفارش تکراری، همان سفارش قبلی برگردانده می‌شود.

بدنه درخواست

نامنوعالزامیتوضیحنمونه
order_idstring (UUID)بلهیک UUID یکتا برای این سفارش (هر نسخه‌ای: v1، v4، v7 و غیره). به‌عنوان کلید جلوگیری از تکرار (idempotency key) استفاده می‌شود.01912345-6789-7abc-8def-0123456789ab
sub_category_idnumberبلهشناسه زیردسته محصول.999
quantitynumberبلهتعداد واحدهای سفارش (عدد صحیح مثبت).1
requirementsobjectبلهاطلاعات تحویل به بازیکن. همه فیلدهایی را که اندپوینت «دریافت الزامات دسته‌بندی» برمی‌گرداند، بفرستید.{"player_id": "123456789", "server": "Asia"}
expected_unit_pricestringخیرمحافظت از قیمت. اگر قیمت فعلی از این مقدار بیشتر باشد، سفارش رد می‌شود.0.950000
درخواست
curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/create" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "01912345-6789-7abc-8def-0123456789ab",
  "sub_category_id": 999,
  "quantity": 1,
  "requirements": {
    "player_id": "123456789",
    "server": "Asia"
  },
  "expected_unit_price": 0.95
}'
نمونه پاسخ
{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "pending",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z"
  }
}
GET

/orders/:orderId

دریافت وضعیت سفارش

وضعیت فعلی و جزئیات یک سفارش مشخص را برمی‌گرداند.

محدودیت نرخ۳ درخواست در ۶۰ ثانیه به ازای هر حساب + order_id

نکته: وضعیت سفارش یکی از این مقدارهاست: pending، completed، refunded یا partial (partial یعنی بخشی از واحدها تحویل شده و وجه بقیه مسترد شده است). مقدار فیلد sub_transactions[].status برای هر واحد pending، completed یا refunded است؛ هر واحد تا زمان تحویل یا استرداد وجه در حالت pending می‌ماند. فیلد sub_transactions[].id شماره‌ی واحد در همان سفارش است (1…n) و شناسه‌ی پایگاه داده نیست. فیلدهای retry_count و max_retries، اگر وجود داشته باشند، منسوخ شده‌اند و همیشه ۰ هستند.

پارامترهای مسیر

نامنوعالزامیتوضیحنمونه
orderIdstring (UUID)بلهشناسه سفارشی که می‌خواهید بررسی کنید.01912345-6789-7abc-8def-0123456789ab
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/orders/01912345-6789-7abc-8def-0123456789ab" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "completed",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z",
    "completed_at": "2024-06-15T12:00:05Z",
    "vouchers": [],
    "sub_transactions": [
      {
        "id": 1,
        "status": "completed",
        "player_id": "123456789",
        "player_name": "ProGamer99",
        "amount": "0.950000",
        "created_at": "2024-06-15T12:00:00Z",
        "completed_at": "2024-06-15T12:00:05Z"
      }
    ]
  }
}
POST

/orders/batch

دریافت گروهی سفارش‌ها

چند سفارش را با شناسه‌هایشان یک‌جا برمی‌گرداند. حداکثر ۵۰ شناسه سفارش در هر درخواست.

محدودیت نرخ۲ درخواست در ۶۰ ثانیه برای هر حساب

بدنه درخواست

نامنوعالزامیتوضیحنمونه
order_idsstring[]بلهآرایه‌ای از UUID سفارش‌ها (حداکثر ۵۰).["uuid-1", "uuid-2"]
درخواست
curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/batch" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_ids": [
    "uuid-1",
    "uuid-2"
  ]
}'
نمونه پاسخ
{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "charged_amount": "0.950000"
    }
  ],
  "not_found": [
    "uuid-that-does-not-exist"
  ]
}
GET

/orders

فهرست سفارش‌ها

سفارش‌های شما را به‌صورت صفحه‌بندی‌شده برمی‌گرداند، با فیلتر اختیاری بر اساس وضعیت و بازه تاریخ.

محدودیت نرخ۲ درخواست در ۶۰ ثانیه برای هر حساب

پارامترهای کوئری

نامنوعالزامیتوضیحنمونه
pagenumberخیرشماره صفحه (پیش‌فرض: ۱).1
limitnumberخیرتعداد نتایج در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض: ۵۰).50
statusstringخیرفیلتر بر اساس وضعیت سفارش: pending (در انتظار)، completed (تکمیل‌شده)، refunded (بازپرداخت)، partial (تکمیل جزئی).completed
created_afterstring (ISO 8601)خیرسفارش‌های ثبت‌شده بعد از این تاریخ را فیلتر می‌کند.2024-01-01T00:00:00Z
created_beforestring (ISO 8601)خیرفقط سفارش‌های ثبت‌شده پیش از این تاریخ را نشان می‌دهد.2024-12-31T23:59:59Z
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/orders?page=1&limit=50&status=completed&created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "subcategory_name": "FF 100 Diamonds",
      "quantity": 1,
      "charged_amount": "0.950000",
      "created_at": "2024-06-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

یک درخواست واقعی را از همین صفحه بفرستید

برای فراخوانی زنده این اندپوینت‌ها یک کلید API را بچسبانید. کلید در همین تب مرورگر می‌ماند و تنها به خود API فرستاده می‌شود.

Enter your API key to use the interactive playground. Get your API key

یک اندپوینت انتخاب کنید

1
2
Order Details

Enter your API key above to try this endpoint.

تازه با پلتفرم آشنا شده‌اید؟ از معرفی API شارژ بازی برای نمایندگان فروش شروع کنید، یا معرفی برنامه نمایندگی SHOP2TOPUP را بخوانید تا ببینید حساب شریک چگونه کار می‌کند.

مرجع API سفارش — ثبت، وضعیت، دسته‌ای و فهرست