title: "API سرور به سرور (S2S)" order: 5 description: "احراز هویت OAuth2 client credentials و endpointهای بررسی خرید، تأیید، اشتراک و بازپرداخت"

API سرور به سرور (S2S)

با این API سرور شما وضعیت معتبر خرید و اشتراک را از بله‌استور می‌پرسد، خرید را تأیید (acknowledge) می‌کند، اشتراک را لغو می‌کند و بازپرداخت می‌دهد. این API مرجع نهایی برای تصمیم‌گیری دربارهٔ دادن محصول به کاربر است.

  • نشانی پایه: https://api.<domain> (نشانی نهایی در حال نهایی‌شدن است؛ در محیط توسعه: http://localhost:18080)
  • همهٔ مسیرها زیر /s2s/ هستند.
  • قالب: JSON با کلیدهای camelCase؛ مبالغ به ریال (عدد صحیح)؛ زمان‌ها طبق هر فیلد (در زیر).
  • هدف کارایی: پاسخ بررسی خرید در صدک ۹۵ کمتر از ۳۰۰ میلی‌ثانیه.

۱. ساخت کلاینت

در کنسول، بخش پرداخت ← دسترسی سرور به سرور یک کلاینت بسازید (POST /console/v1/billing/orgs/{orgId}/s2s-clients). پاسخ شامل clientId و clientSecret است؛ clientSecret فقط یک بار نمایش داده می‌شود؛ آن را در محل امن (مثلاً vault) نگه دارید. کلاینت متعلق به سازمان است و فقط به برنامه‌های همان سازمان دسترسی دارد. برای باطل کردن کلاینت: DELETE /console/v1/billing/orgs/{orgId}/s2s-clients/{clientId}.

scopeها

scope اجازه
purchases.read خواندن وضعیت خرید
purchases.write تأیید (acknowledge) خرید
subscriptions.read خواندن وضعیت اشتراک
subscriptions.write لغو اشتراک
orders.refund بازپرداخت سفارش

به هر کلاینت فقط scopeهای لازم را بدهید؛ مثلاً سرور بازی که فقط خرید را بررسی می‌کند، purchases.read و purchases.write کافی دارد.

۲. دریافت توکن دسترسی

POST /s2s/oauth/token با احراز هویت HTTP Basic (clientId:clientSecret) و بدنهٔ application/x-www-form-urlencoded:

API=https://api.<domain>
curl -sS -X POST "$API/s2s/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials'
{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "purchases.read purchases.write"
}
  • می‌توانید با پارامتر scope (جداشده با فاصله) زیرمجموعه‌ای از scopeهای کلاینت را درخواست کنید.
  • توکن را تا نزدیک انقضا (expires_in ثانیه) کش کنید و برای هر درخواست توکن تازه نگیرید.
  • در همهٔ درخواست‌های بعدی: Authorization: Bearer <access_token>.

۳. بررسی خرید

GET /s2s/v1/apps/{packageName}/purchases/{purchaseToken} — scope: purchases.read

curl -sS "$API/s2s/v1/apps/com.example.game/purchases/$PURCHASE_TOKEN" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "orderId": "6f1c2a7e-3b0d-4b8e-9f51-2f7a0c9d1e44",
  "productId": "coins_100",
  "purchaseState": "PURCHASED",
  "consumptionState": "NOT_CONSUMED",
  "acknowledged": false,
  "refundState": "NONE",
  "purchaseTime": 1763539200000,
  "developerPayload": "order-42",
  "userHash": "9c1f0e…",
  "test": false
}
فیلد توضیح
orderId شناسهٔ یکتای سفارش (UUID). برای جلوگیری از دادن تکراری محصول، آن را در پایگاه دادهٔ خود یکتا نگه دارید.
productId شناسهٔ محصول (SKU)
purchaseState PENDING، PURCHASED، ACKNOWLEDGED، CONSUMED، REFUNDED، AUTO_REFUNDED
consumptionState NOT_CONSUMED یا CONSUMED
acknowledged آیا خرید تأیید شده است
refundState NONE، PARTIAL، FULL
purchaseTime زمان خرید به میلی‌ثانیهٔ epoch
developerPayload همان payload که هنگام خرید فرستادید
userHash شناسهٔ مستعار و پایدار کاربر در برنامهٔ شما (هویت واقعی کاربر به شما داده نمی‌شود)
test true برای خرید آزمایشگرهای مجوز (سندباکس)

الگوی پیشنهادی بررسی

  1. برنامه purchaseToken و productId (و در صورت نیاز orderId) را برای سرور شما می‌فرستد.
  2. سرور این endpoint را صدا می‌زند و بررسی می‌کند:
    • purchaseState برابر PURCHASED (یا برای محصول غیرمصرفی، ACKNOWLEDGED) باشد؛
    • productId همان چیزی باشد که کاربر خواسته؛
    • developerPayload با سفارش داخلی شما بخواند؛
    • refundState برابر NONE باشد؛
    • orderId قبلاً استفاده نشده باشد؛
    • در محیط تولید، test برابر false باشد (مگر عمداً خرید آزمایشی را بپذیرید).
  3. محصول را به کاربر بدهید.
  4. خرید را نهایی کنید: محصول مصرفی را برنامه با consumeProduct مصرف می‌کند؛ محصول غیرمصرفی و اشتراک را با endpoint زیر (یا از برنامه) تأیید کنید.

⚠️ خریدی که تا مهلت مقرر (پیش‌فرض ۳ روز، قابل تنظیم) نه مصرف شود و نه تأیید، خودکار بازپرداخت می‌شود (AUTO_REFUNDED).

۴. تأیید خرید

POST /s2s/v1/apps/{packageName}/purchases/{purchaseToken}:acknowledge — scope: purchases.write

curl -sS -X POST "$API/s2s/v1/apps/com.example.game/purchases/$PURCHASE_TOKEN:acknowledge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -o /dev/null -w '%{http_code}\n'
# 204

پاسخ موفق 204 No Content است.

۵. وضعیت اشتراک

GET /s2s/v1/apps/{packageName}/subscriptions/{purchaseToken} — scope: subscriptions.read

curl -sS "$API/s2s/v1/apps/com.example.game/subscriptions/$PURCHASE_TOKEN" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "status": "IN_GRACE",
  "expiryTime": 1766131200000,
  "autoRenewing": true,
  "inGrace": true,
  "graceEndsAt": "2026-12-22T08:00:00Z"
}
status معنی دسترسی کاربر
ACTIVE فعال بله
IN_GRACE تمدید ناموفق، در دورهٔ مهلت (پیش‌فرض ۳ روز، قابل تنظیم برای هر محصول) بله
ON_HOLD پس از پایان مهلت، تا پرداخت موفق معلق خیر
EXPIRED منقضی خیر
CANCELED کاربر لغو کرده؛ تا پایان دورهٔ جاری فعال می‌ماند تا expiryTime

۶. لغو اشتراک

POST /s2s/v1/apps/{packageName}/subscriptions/{purchaseToken}:cancel — scope: subscriptions.write

curl -sS -X POST "$API/s2s/v1/apps/com.example.game/subscriptions/$PURCHASE_TOKEN:cancel" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
# 204

تمدید خودکار متوقف می‌شود و اشتراک تا پایان دورهٔ جاری فعال می‌ماند.

۷. بازپرداخت

POST /s2s/v1/apps/{packageName}/orders/{orderId}:refund — scope: orders.refund

curl -sS -X POST "$API/s2s/v1/apps/com.example.game/orders/$ORDER_ID:refund" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: refund-$ORDER_ID-1" \
  -H 'content-type: application/json' \
  -d '{"amountRials": 50000}'
{ "refundId": "0b9d5c3e-8a41-4f0e-a3b2-61c7d9e2f810", "amountRials": 50000 }
  • بدون amountRials بازپرداخت کامل است؛ با آن، جزئی.
  • مجموع بازپرداخت‌ها نمی‌تواند از مبلغ سفارش بیشتر شود (REFUND_EXCEEDS_AMOUNT).
  • حتماً Idempotency-Key بفرستید. اگر پاسخ را به‌خاطر خطای شبکه دریافت نکردید، همان درخواست را با همان کلید و همان بدنه دوباره بفرستید؛ همان پاسخ برمی‌گردد و بازپرداخت دوبار انجام نمی‌شود.
  • پس از بازپرداخت، رویداد purchase.refunded به Webhook شما فرستاده می‌شود.

۸. خطاها

همهٔ پاسخ‌های غیر-2xx این شکل را دارند؛ message فارسی و قابل نمایش است:

{ "error": { "code": "PURCHASE_NOT_FOUND", "message": "خرید پیدا نشد.", "details": {} } }
HTTP code معنی
400 / 422 VALIDATION_FAILED ورودی نامعتبر؛ جزئیات در details.fields
401 UNAUTHORIZED توکن نامعتبر، منقضی یا کلاینت باطل‌شده؛ توکن تازه بگیرید
403 FORBIDDEN scope کافی نیست یا برنامه متعلق به سازمان شما نیست
404 PURCHASE_NOT_FOUND / NOT_FOUND خرید یا سفارش با این مشخصات برای این بسته وجود ندارد
409 ALREADY_CONSUMED خرید قبلاً مصرف شده است
409 REFUND_EXCEEDS_AMOUNT مبلغ بازپرداخت بیش از مبلغ باقی‌ماندهٔ سفارش است
409 CONFLICT وضعیت فعلی اجازهٔ این کار را نمی‌دهد
429 RATE_LIMITED درخواست بیش از حد مجاز
503 BILLING_DISABLED / FEATURE_DISABLED / UPSTREAM_UNAVAILABLE سرویس موقتاً در دسترس نیست
500 INTERNAL خطای داخلی

۹. Idempotency و تلاش دوباره

  • درخواست‌های خواندنی (GET) را می‌توانید آزادانه تکرار کنید.
  • برای درخواست‌های مالی (بازپرداخت) سرآیند Idempotency-Key بفرستید: کلید یکسان + بدنهٔ یکسان = همان پاسخ.
  • در پاسخ 429 و 5xx با backoff نمایی و jitter تلاش دوباره کنید. سقف نرخ درخواست در پیکربندی بله‌استور تعریف می‌شود (قابل تنظیم)؛ به مقدار مشخصی وابسته نشوید.

۱۰. نمونه با Python

import time, requests

API = "https://api.<domain>"
_token = {"value": None, "exp": 0}

def access_token(client_id: str, client_secret: str) -> str:
    if _token["value"] and time.time() < _token["exp"] - 60:
        return _token["value"]
    r = requests.post(f"{API}/s2s/oauth/token", auth=(client_id, client_secret),
                      data={"grant_type": "client_credentials"}, timeout=5)
    r.raise_for_status()
    body = r.json()
    _token.update(value=body["access_token"], exp=time.time() + body["expires_in"])
    return _token["value"]

def verify_purchase(package: str, purchase_token: str, expected_sku: str, token: str) -> dict:
    r = requests.get(f"{API}/s2s/v1/apps/{package}/purchases/{purchase_token}",
                     headers={"Authorization": f"Bearer {token}"}, timeout=5)
    if r.status_code == 404:
        raise ValueError("purchase not found")
    r.raise_for_status()
    p = r.json()
    if p["productId"] != expected_sku or p["purchaseState"] not in ("PURCHASED", "ACKNOWLEDGED") \
            or p["refundState"] != "NONE":
        raise ValueError(f"purchase not valid: {p}")
    return p  # then: check p["orderId"] is unused, grant, acknowledge/consume

موضوعات مرتبط