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

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

POST

/orders/create

Create Order

Place a new order. You must provide a unique UUID as the order_id for idempotency. The wallet will be charged immediately.

محدودیت نرخ120 req / 60s per user

نکته: The order_id is your idempotency key. If you retry with the same UUID, the existing order is returned instead of creating a duplicate.

بدنه درخواست

نامنوعالزامیتوضیحنمونه
order_idstring (UUID)بلهA unique UUID for this order (any format: v1, v4, v7, etc.). Used as an idempotency key.01912345-6789-7abc-8def-0123456789ab
sub_category_idnumberبلهThe product subcategory ID.999
quantitynumberبلهNumber of units to order (positive integer).1
requirementsobjectبلهPlayer delivery info. Include all fields returned by the Get Category Requirements endpoint.{"player_id": "123456789", "server": "Asia"}
expected_unit_pricestringخیرPrice protection. If current price exceeds this value, the order is rejected.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

Get Order Status

Retrieve the current status and details of a specific order.

محدودیت نرخ3 req / 60s per user + orderId

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

نامنوعالزامیتوضیحنمونه
orderIdstring (UUID)بلهThe order ID to look up.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

Batch Get Orders

Retrieve multiple orders at once by their IDs. Maximum 50 order IDs per request.

محدودیت نرخ2 req / 60s per user

بدنه درخواست

نامنوعالزامیتوضیحنمونه
order_idsstring[]بلهArray of order UUIDs (max 50).["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

List Orders

List your orders with pagination and optional filters by status and date range.

محدودیت نرخ2 req / 60s per user

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

نامنوعالزامیتوضیحنمونه
pagenumberخیرPage number (default: 1).1
limitnumberخیرResults per page, 1-100 (default: 50).50
statusstringخیرFilter by status: pending, completed, refunded, partial.completed
created_afterstring (ISO 8601)خیرFilter orders created after this date.2024-01-01T00:00:00Z
created_beforestring (ISO 8601)خیرFilter orders created before this date.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 سفارش — ثبت، وضعیت، دسته‌ای و فهرست