۰
اکانتیخرید و پیگیری سفارش‌ها
—سفارش
برای توسعه‌دهندگان

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

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

معرفی API

نمونه‌های زیر برای توضیح ساختار درخواست و پاسخ JSON و استفاده از HTTPS هستند؛ نشانی مثال، آدرس عملیاتی سرویس نیست.

https://api.example.invalid

احراز هویت

در نمونهٔ پیشنهادی، هدر Authorization برای نمایش روش ارسال توکن آمده است. برای بررسی دسترسی عملیاتی، با پشتیبانی هماهنگ کنید.

Authentication header
Authorization: Bearer example_token_xxxxxxxxxxxx
Content-Type: application/json

نقاط پایانی

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

GET/v1/products

دریافت لیست محصولات

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

درخواست
curl -X GET 'https://api.example.invalid/v1/products?category=playstation&page=1' \
  -H 'Authorization: Bearer example_token_xxxxxxxx'
پاسخ
{
  "ok": true,
  "page": 1,
  "items": [
    {
      "id": "psn-gift-50-us",
      "name": "گیفت کارت 50 دلاری پلی استیشن",
      "region": "US",
      "price": 3420000,
      "stock": 42
    }
  ]
}
GET/v1/products/{id}

جزئیات یک محصول

نمونهٔ پاسخ جزئیات محصول، ساختار احتمالی فیلدهای ورودی را نشان می‌دهد؛ قرارداد فعال باید جدا تأیید شود.

درخواست
curl -X GET 'https://api.example.invalid/v1/products/psn-gift-50-us' \
  -H 'Authorization: Bearer example_token_xxxxxxxx'
پاسخ
{
  "ok": true,
  "product": {
    "id": "psn-gift-50-us",
    "name": "گیفت کارت 50 دلاری پلی استیشن",
    "region": "US",
    "price": 3420000,
    "fields": ["email", "phone"]
  }
}
POST/v1/orders

ثبت سفارش

این مثال شکل پیشنهادی ثبت سفارش را نشان می‌دهد؛ کپی این نمونه، سفارش واقعی ثبت نمی‌کند و از کیف پولی مبلغ کسر نمی‌شود.

درخواست
curl -X POST 'https://api.example.invalid/v1/orders' \
  -H 'Authorization: Bearer example_token_xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": "psn-gift-50-us",
    "email": "buyer@example.com",
    "phone": "09120000000"
  }'
پاسخ
{
  "ok": true,
  "order_id": "ORD-88213",
  "status": "processing",
  "amount": 3420000
}
GET/v1/orders/{id}

استعلام وضعیت سفارش

این نمونه ساختار پیشنهادی وضعیت سفارش و محتوای تحویل را نمایش می‌دهد.

درخواست
curl -X GET 'https://api.example.invalid/v1/orders/ORD-88213' \
  -H 'Authorization: Bearer example_token_xxxxxxxx'
پاسخ
{
  "ok": true,
  "order_id": "ORD-88213",
  "status": "delivered",
  "delivery": { "type": "code", "value": "PSN5-XXXX-XXXX-4821" }
}
GET/v1/wallet/balance

موجودی کیف پول

عدد این نمونه برای توضیح شکل پاسخ است و موجودی واقعی هیچ حسابی نیست.

درخواست
curl -X GET 'https://api.example.invalid/v1/wallet/balance' \
  -H 'Authorization: Bearer example_token_xxxxxxxx'
پاسخ
{
  "ok": true,
  "balance": 12500000,
  "currency": "IRT"
}

محدودیت نرخ درخواست

پس از فعال‌سازی

سقف دقیقه‌ای در قرارداد اعلام می‌شود

نیازمند توافق

سقف روزانه پیش از اتصال مشخص می‌شود

بدون تضمین فعلی

زمان پاسخ باید در محیط عملیاتی سنجیده شود

کدهای خطا

  • 200درخواست با موفقیت انجام شد.
  • 401کلید API نامعتبر یا ارسال نشده است.
  • 402موجودی کیف پول وب سرویس کافی نیست.
  • 404محصول یا سفارش موردنظر پیدا نشد.
  • 429از محدودیت نرخ درخواست عبور کرده‌اید.
  • 500خطای موقت سرور؛ لطفاً دوباره تلاش کنید.

وبهوک‌ها

رویدادهای زیر صرفاً نمونهٔ طراحی وبهوک هستند؛ ثبت مقصد و ارسال عملیاتی باید در قرارداد فعال سرویس تأیید شود.

order.created

نمونهٔ رویداد ایجاد سفارش.

order.delivered

نمونهٔ رویداد تحویل سفارش.

order.failed

نمونهٔ رویداد ناموفق‌شدن تحویل.

wallet.low_balance

نمونهٔ رویداد کاهش موجودی کیف پول.