Ürünler واریا را از طریق سیستم خودت بفروش

Kimlik Doğrulama

هر درخواست کلیدت را در هدر X-API-Key می‌فرستد. کلید یک رمز است: آن را فقط در هدر بفرست, هرگز در آدرس, در query string یا در لاگ — کلیدی که در آدرس باشد به Tarih مرورگر, لاگ پروکسی ve اسکرین‌شات راه پیدا می‌کند. این API به هیچ هدر forward شده اعتماد نمی‌کند, پس فهرست IP isteğe bağlı هر کلید قابل جعل نیست.

curl "https://api.waryashop.org/api/v1/games" \
  -H "X-API-Key: YOUR_API_KEY"

Uç noktalar

هر مسیر نسبت به Base URL بالا است. هر عملیات به اسکوپ نوشته‌شده در کنارش نیاز دارد.

کاتالوگ

Satın Al

حساب

اسکوپ‌ها

هر کلید فقط به Uç noktalarیی می‌رسد که اسکوپ‌هایش پوشش می‌دهند. درخواستی که کلیدش اسکوپ لازم را ندارد پاسخ 403 می‌گیرد ve اسکوپ Adوجود را Ad می‌برد. مجموعهٔ فقط-خواندنی به‌طور پیش‌فرض داده می‌شود؛ ساخت Sipariş اسکوپی است که باید درخواست کنی.

محدودیت نرخ

این‌ها Limitlerیی است که API واقعاً اعمال می‌کند, بر حسب درخواست در دقیقه.

هر پاسخ دو هدر X-RateLimit-Limit ve X-RateLimit-Remaining را دارد. پاسخ ردشده 429 است ve هدرهای Retry-After ve X-RateLimit-Reset را هم دارد — پیش از Tekrar Dene آن‌ها را بخوان؛ همان مقدار در بدنه به‌صورت meta.retry_after تکرار می‌شود.

Sayfalama

Uç noktalarی فهرستی با page ve per_page (Ad دیگر: limit) Sayfalama می‌شوند. مقدار per_page در فهرست Sipariş و تراکنش بین 1 تا 100 محدود می‌شود؛ فهرست‌های کاتالوگ به‌طور پیش‌فرض ve حداکثر 500 خانواده در هر صفحه‌اند ve meta.has_more می‌گوید صفحهٔ Sonraki هست یا نه.

هر پاسخ فهرستی در meta Değerler current_page, last_page, per_page, total, count ve request_id را دارد, پس کلاینت می‌تواند صفحه‌ها را بپیماید ve همچنان یک Kimlikٔ همبستگی نقل کند.

curl "https://api.waryashop.org/api/v1/orders?page=2&per_page=50" \
  -H "X-API-Key: YOUR_API_KEY"

خطاها

هر پاسخ — موفق یا Başarısız — یک پوشش JSON با success, error_code, message ve meta.request_id است. پاسخ‌های خطا کد ve پیام را زیر error هم تکرار می‌کنند. در هر درخواست Destek meta.request_id را ذکر کن.

{
    "success": false,
    "error": {
        "code": "MISSING_API_KEY",
        "message": "X-API-Key header is required."
    },
    "error_code": "MISSING_API_KEY",
    "message": "X-API-Key header is required.",
    "meta": {
        "request_id": "01J8ZQ4M6W9K2N7P3R5T8V0XYZ"
    }
}

{
    "success": false,
    "error": {
        "code": "SCOPE_FORBIDDEN",
        "message": "This API key does not grant the \"catalog:read\" scope."
    },
    "error_code": "SCOPE_FORBIDDEN",
    "message": "This API key does not grant the \"catalog:read\" scope.",
    "meta": {
        "request_id": "01J8ZQ4M6W9K2N7P3R5T8V0XYZ"
    }
}

همهٔ Durum‌ها

خطاهای 401, 402, 403 ve 422 را بدون اصلاح درخواست تکرار نکن. برای 429 ve خطاهای موقت 5xx فاصلهٔ تلاش‌ها را تصاعدی Artış بده.

تکرار ایمنِ ساخت سفارش

ساخت Sipariş هزینه دارد, پس POST /orders از طریق هدر Idempotency-Key تکرارایمن است — تنها مکانیزم منتشرشده. همان کلید را با همان بدنه بفرست تا با اطمینان دوباره تلاش کنی: تکرار, همان Sipariş نخست را با idempotent_replay برابر true برمی‌گرداند ve دوباره چیزی کسر نمی‌شود. همان کلید با بدنهٔ متفاوت برای حساب تو 409 است؛ کلیدی که حساب دیگری به‌کار می‌برد مال همان حساب است ve هرگز با Anahtarınız تعارض ندارد.

curl -X POST "https://api.waryashop.org/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 8f3kd-order-1042" \
  -H "Content-Type: application/json" \
  -d '{"game":"pubgm","catalogue_name":"60 UC","player_id":"12345678"}'

وب‌هوک Müşteri

هنگام ساخت Sipariş یک callback_url بفرست ve واریا هر رویداد Sipariş را به آن می‌فرستد. هر ارسال امضا می‌شود, پس می‌توانی مطمئن باشی از طرف ما آمده ve در مسیر تغییر نکرده است. تلاش‌های دوباره طبق زمان‌بندی زیر است؛ کلید امضای چرخیده در یک بازهٔ مهلت در کنار جانشینش امضا می‌کند تا بتوانی بررسی را بدون از دست دادن رویدادها جابه‌جا کنی.

:raw_body = the exact bytes you received
t, v1 = the two values in X-Warya-Signature
expected = hmac_sha256(key = WEBHOOK_SECRET, message = t + "." + event_id + "." + raw_body)
ok = hash_equals(expected, v1)  # compare in constant time

شروع کنید

1. 1. حساب بساز

   در واریا Kayıt Ol ve وارد شو. هر حساب Bayiی شامل API Anahtarı, محدودیت IP ve وب‌هوک امضاشده است.

   Hesap Oluştur →

2. 2. درخواست دسترسی Bayiی (API)

   فرم خودکارِ درخواست دسترسی Bayiی هنوز راه‌اندازی نشده است. تا آن زمان, دسترسی API را از مسیر Telegram Desteği درخواست کن تا برای حسابت Aktif شود.

   ارتباط با Telegram'dan Destek →

3. 3. کلید بساز

   پس از Giriş, صفحهٔ API Anahtarları را باز کن ve کلیدت را بساز. اسکوپ‌های öğe نیازت را Seç کن؛ مجموعهٔ فقط-خواندنی شروع خوبی است.

4. 4. فراخوانی /api/v1/games

   کاتالوگ را با کلیدت بخوان. درخواست بدون کلید پاسخ 401 پایین را می‌گیرد — همان پاسخ واقعی گرفته‌شده از API زنده:

   curl "https://api.waryashop.org/api/v1/games" \
     -H "X-API-Key: YOUR_API_KEY"

   بدون کلید, API زنده این را برمی‌گرداند:

   {
       "success": false,
       "error": {
           "code": "MISSING_API_KEY",
           "message": "X-API-Key header is required."
       },
       "error_code": "MISSING_API_KEY",
       "message": "X-API-Key header is required.",
       "meta": {
           "request_id": "01J8ZQ4M6W9K2N7P3R5T8V0XYZ"
       }
   }

5. 5. Sipariş ثبت کن

   ابتدا Oyuncu را بررسی کن, سپس Sipariş را همراه با Idempotency-Key بفرست (همان درخواستی که در بخش 08 آمد). این هم پاسخ 201 آن:

   {
       "success": true,
       "order_id": "WR-20261010-8F3KD",
       "status": "processing",
       "charged": "0.950000",
       "currency": "USD",
       "idempotent_replay": false,
       "data": {
           "order_id": "WR-20261010-8F3KD",
           "status": "processing",
           "charged": "0.950000",
           "currency": "USD",
           "idempotent_replay": false
       },
       "meta": {
           "request_id": "01J8ZQ4M6W9K2N7P3R5T8V0XYZ"
       }
   }

6. 6. وب‌هوک را دریافت کن

   هنگام ساخت Sipariş یک callback_url بفرست؛ ما هر رویداد Sipariş را امضاشده به آن می‌فرستیم. اگر ترجیح می‌دهی خودت بپرسی, GET /orders/{orderId} را بخوان ve وقتی Durum completed, failed یا refunded شد بس کن.