Ana içeriğe geç
Warya Shop
TR

API Referansı

هر اندپوینتی که API Bayiی واریا منتشر می‌کند, اسکوپی که هرکدام لازم دارد, پارامترهایی که می‌پذیرد ve پوشش دقیقی که هر پاسخ دارد. بدون نیاز به حساب قابل خواندن.

Base URL https://api.waryashop.org/api/v1
01

Kimlik Doğrulama

روی هر فراخوانی کلیدت را در هدر X-API-Key بفرست. هرگز در آدرس یا query string. کلید نبوده/ناشناخته/Devre Dışı/باطل پاسخ 401 می‌گیرد ve هیچ چیز دیگری دربارهٔ حساب Ad نمی‌برد. هر حساب 1 کلید دارد؛ اسکوپ می‌گیرد ve می‌تواند آدرس‌هایی را که از آن‌ها پاسخ می‌دهد محدود کند (تا 32 قانون).

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

محدودیت نرخ ve Sayfalama

کجا هر فراخوان کل سرویس
هر درخواست /api/v1, پیش از بررسی کلید 600/min 6,000/min
Anahtarınız (هر کلید, قابل تنظیم) 60/min (پیش‌فرض, تا 6,000) —
POST https://api.waryashop.org/api/v1/player/validate 60/min 600/min

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

کاتالوگ

GET https://api.waryashop.org/api/v1/games catalog:read

Oyunları listele ve Ürünler

کد Ürün, Ad انگلیسی, Ad فارسی isteğe bağlı ve آدرس تصویر میزبانی‌شده روی واریا. Sayfalama‌شده؛ صفحهٔ پیش‌فرض کل لیست است.

موفق:
200
اسکوپ:
catalog:read
کوئری:
search, category, page, per_page, sort
GET https://api.waryashop.org/api/v1/games/{code}/catalogue catalog:read

Paketler ve قیمت فروش

هنگام Sipariş Ver دقیقاً همان catalogue_name این پاسخ را ارسال کن. این‌ها قیمت فروش واریا به dolar ve به‌صورت رشتهٔ اعشاری است. فقط Paketlerیی فهرست می‌شوند که همین حالا قیمت‌شان قابل تأیید است؛ Ürünی که دیگر قابل فروش نیست یا Tutarش تأیید نمی‌شود اینجا غایب است — نه اینکه با 0.000000 منتشر شود — ve Ad‌بردن آن در Sipariş پاسخ 422 می‌گیرد.

موفق:
200
اسکوپ:
catalog:read
مسیر:
code
کوئری:
search, in_stock, page, per_page, sort
GET https://api.waryashop.org/api/v1/games/{code}/fields catalog:read

فیلدهای لازم Oyuncu

Kimlik‌هایی که فرم Sipariş این Oyun باید بگیرد, همراه با meta.source ve meta.freshness که می‌گوید پاسخ از کجا آمده است. ووچرها لیست خالی برمی‌گردانند.

موفق:
200
اسکوپ:
catalog:read
مسیر:
code
GET https://api.waryashop.org/api/v1/games/{code}/servers catalog:read

Sunucuها ve Bölgeler

لیست خالی یک پاسخ Onaylandı است: این Oyun Seç Sunucu نمی‌خواهد. Oyun‌ای که لیستش تأیید نشود پاسخ 503 می‌گیرد, نه لیست خالی.

موفق:
200
اسکوپ:
catalog:read
مسیر:
code

Satın Al

POST https://api.waryashop.org/api/v1/player/validate players:validate

اعتبارسنجی Oyuncu

قبل از دریافت وجه از Müşteri, اکانت او را بررسی کن. خطای موقت پاسخ 503 با Retry-After است, نه «اکانت Adعتبر».

موفق:
200
اسکوپ:
players:validate
بدنه:
game, player_id, server_id?, charname?
POST https://api.waryashop.org/api/v1/orders orders:write

Sipariş Ver

قیمت فعلی واریا را قطعی می‌کند, Tutar را از Cüzdan شما کسر ve پردازش Sipariş را شروع می‌کند. اگر قیمت تأیید نشود, پاسخ 503 است ve هیچ Tutarی کسر نمی‌شود.

موفق:
201
اسکوپ:
orders:write
هدر:
Idempotency-Key
بدنه:
game, catalogue_name, player_id, server_id?, charname?, customer_reference?, callback_url?

هدر Idempotency-Key الزامی است. این هم پاسخ 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"
    }
}
GET https://api.waryashop.org/api/v1/orders/{orderId} orders:read

دریافت Sipariş Durumu

برای ووچر Tamamlandı‌شده, فیلد delivery Teslim Kodu را دارد.

موفق:
200
اسکوپ:
orders:read
مسیر:
orderId
GET https://api.waryashop.org/api/v1/orders orders:read

Siparişleri listele

Tarihچه Sayfalama‌شده؛ جدیدترین Sipariş اول است.

موفق:
200
اسکوپ:
orders:read
کوئری:
status, type, game, customer_reference, from, to, page, per_page, sort

حساب

GET https://api.waryashop.org/api/v1/balance balance:read

Cüzdan Bakiyesi

Bakiye آزاد ve قفل‌شده USD به‌صورت رشتهٔ اعشاری برمی‌گردد.

موفق:
200
اسکوپ:
balance:read
GET https://api.waryashop.org/api/v1/transactions transactions:read

Cüzdan İşlemleri

گردش حساب Sayfalama‌شده برای تطبیق مالی.

موفق:
200
اسکوپ:
transactions:read
کوئری:
type, status, from, to, page, per_page, sort
پاسخ‌ها

قرارداد Durum ve خطا

پاسخ موفق success: true دارد, کلیدهای اندپوینت را در سطح بالا, همان کلیدها را زیر data ve meta.request_id را (هم در هدر X-Request-Id) برمی‌گرداند. پاسخ Başarısız success: false با error_code ve message دارد که آن‌ها را زیر error هم تکرار می‌کند.

Durum کدها معنا
200 / 201 — موفق. success: true, کلیدهای خود اندپوینت, همان کلیدها زیر data ve meta.request_id.
400 BAD_REQUEST / IDEMPOTENCY_KEY_REQUIRED درخواست قابل فهم نبود, یا کلیدی که Idempotency-Key لازم دارد آن را نفرستاده است.
401 MISSING_API_KEY / INVALID_API_KEY / UNAUTHENTICATED کلید نبوده, ناشناخته است, یا Devre Dışı/باطل شده است. هیچ چیز دیگری دربارهٔ حساب فاش نمی‌شود.
402 INSUFFICIENT_BALANCE Cüzdan Bakiyesi برای این Sipariş کافی نیست. هیچ Tutarی کسر ve هیچ سفارشی ثبت نشد.
403 SCOPE_FORBIDDEN / ACCOUNT_BLOCKED / IP_NOT_ALLOWED کلید این اندپوینت را پوشش نمی‌دهد, حساب مسدود است, یا درخواست از بیرون فهرست IP مجاز کلید آمده است.
404 NOT_FOUND / GAME_NOT_FOUND / ORDER_NOT_FOUND چیزی در آن آدرس سرویس نمی‌شود, آن Ürün قابل فروش نیست, یا آن Sipariş مال شما نیست (Kimlikٔ حساب دیگر 404 است, نه 403).
405 METHOD_NOT_ALLOWED متد HTTP همانی نیست که این اندپوینت می‌پذیرد.
409 IDEMPOTENCY_CONFLICT / CONFLICT کلید Idempotency-Key پیش‌تر توسط همین حساب برای Sipariş متفاوتی استفاده شده است. آن را فقط با بدنهٔ یکسان تکرار کن؛ کلیدی که حساب دیگری به‌کار می‌برد مال همان حساب است ve هرگز با Anahtarınız تعارض ندارد.
422 VALIDATION_FAILED / INVALID_REQUEST یک فیلد ناقص, بدشکل یا غیرقابل فروش است. errors هر فیلد را Ad می‌برد.
429 Retry-After: 60s RATE_LIMITED تعداد درخواست‌ها زیاد است. پیش از Tekrar Dene, مقدار هدر Retry-After (ثانیه) را صبر کن.
500 INTERNAL_ERROR / SERVICE_TEMPORARILY_UNAVAILABLE خطای پیش‌بینی‌نشده در سمت ما. meta.request_id آن را در لاگ‌های ما مشخص می‌کند؛ با فاصلهٔ تصاعدی دوباره تلاش کن.
503 Retry-After: 60s CATALOG_TEMPORARILY_UNAVAILABLE / SERVICE_TEMPORARILY_UNAVAILABLE کاتالوگ یا قیمت تأیید نشد, یا سرویس Geçici olarak kullanılamıyor. هیچ Tutarی کسر نشده است؛ RETRY_AFTER ثانیه برای درخواست دوباره کافی است.

401 · بدون کلید

{
    "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"
    }
}

403 · اسکوپ Adوجود

{
    "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"
    }
}

422 · اعتبارسنجی Başarısız

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The request could not be validated."
    },
    "error_code": "VALIDATION_FAILED",
    "message": "The request could not be validated.",
    "errors": {
        "game": [
            "The game field is required."
        ]
    },
    "meta": {
        "request_id": "01J8ZQ4M6W9K2N7P3R5T8V0XYZ"
    }
}
سفارش

Durum‌های سفارش

GET /orders/{orderId} یکی از چهار Durum را منتشر می‌کند. فیلد delivery فقط برای Sipariş ووچرِ Tamamlandı‌شده Teslim Kodu را دارد ve در هر Durum دیگر null است. این بدنه‌ها توسط همان سریالایزری ساخته شده‌اند که خود اندپوینت با آن پاسخ می‌دهد.

created 
{
    "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"
    }
}
processing 
{
    "order_id": "WR-20261028-8F3KD",
    "status": "processing",
    "type": "game_topup",
    "game": "pubgm",
    "catalogue_name": "60 UC",
    "player_id": "12345678",
    "server_id": null,
    "total_amount": "0.950000",
    "currency": "USD",
    "customer_reference": "MY-ORDER-123",
    "delivery": null,
    "created_at": "2026-10-10T09:00:00+00:00",
    "updated_at": "2026-10-10T09:00:00+00:00"
}
completed 
{
    "order_id": "WR-20261028-8F3KD",
    "status": "completed",
    "type": "game_topup",
    "game": "pubgm",
    "catalogue_name": "60 UC",
    "player_id": "12345678",
    "server_id": null,
    "total_amount": "0.950000",
    "currency": "USD",
    "customer_reference": "MY-ORDER-123",
    "delivery": {
        "code": "WARYA-60UC-4KQ7T2M9"
    },
    "created_at": "2026-10-10T09:00:00+00:00",
    "updated_at": "2026-10-10T09:00:00+00:00"
}
failed 
{
    "order_id": "WR-20261028-8F3KD",
    "status": "failed",
    "type": "game_topup",
    "game": "pubgm",
    "catalogue_name": "60 UC",
    "player_id": "12345678",
    "server_id": null,
    "total_amount": "0.950000",
    "currency": "USD",
    "customer_reference": "MY-ORDER-123",
    "delivery": null,
    "created_at": "2026-10-10T09:00:00+00:00",
    "updated_at": "2026-10-10T09:00:00+00:00"
}
refunded 
{
    "order_id": "WR-20261028-8F3KD",
    "status": "refunded",
    "type": "game_topup",
    "game": "pubgm",
    "catalogue_name": "60 UC",
    "player_id": "12345678",
    "server_id": null,
    "total_amount": "0.950000",
    "currency": "USD",
    "customer_reference": "MY-ORDER-123",
    "delivery": null,
    "created_at": "2026-10-10T09:00:00+00:00",
    "updated_at": "2026-10-10T09:00:00+00:00"
}
Webhooks

وب‌هوک Müşteri

Sipariş را با callback_url بساز ve واریا هر رویداد Sipariş را به آن می‌فرستد. هر ارسال امضا می‌شود. آدرس باید HTTPS باشد؛ ریدایرکت‌ها دنبال نمی‌شوند ve میزبان در هر Tekrar Dene resolve ve بررسی می‌شود.

رویدادها

  • order.created
  • order.processing
  • order.completed
  • order.failed
  • order.refunded

Teslimat

  • Signature: X-Warya-Signature
  • Timestamp: X-Warya-Timestamp
  • Event id: X-Warya-Event-Id
  • api_version: 2026-10-28
  • Retries: 5 attempts, waits 1, 5, 15, 60 min
  • Grace after rotation: 60 min

بررسی امضا

v1 همان HMAC-SHA256 روی "{t}.{event_id}.{raw_body}" با کلید وب‌هوک تو است. روی همان بایت‌هایی که دریافت کرده‌ای بازمحاسبه کن 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
API CONTRACT

مشخصات فنی OpenAPI 3.1

قرارداد ماشین‌خوان که بدون کلید در دسترس است. آن را در Postman, Insomnia یا Swagger وارد کن, schema‌ها را ببین یا یک SDK تایپ‌شده بساز. همان سندی که این مرجع از آن رندر می‌شود در آدرس زیر در دسترس است.

https://api.waryashop.org/openapi.json

پاسخ ماشین, پاسخ انسان. قرارداد خوانده‌شده از API در حال اجرا.