بازی‌های ادگیمز در سایت و اپلیکیشن شما

export ADGAMES_KEY="agk_..."
export API="https://api.adgames.ir/partner/v1"

GET/games

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

چه زمانی: هنگام ساخت صفحه بازی‌ها در سایت خود، یا هر بار که می‌خواهید فهرست را به‌روز کنید. نتیجه را می‌توانید چند ساعت cache کنید.

پارامترها

ندارد.

درخواست

curl "$API/games" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "games": [
    {
      "id": "6aea1559b1079f24e6abb33e",
      "name": "Snake",
      "title": "مار",
      "description": "نقطه‌ها را بخور و به دیوار یا به خودت نزن.",
      "thumbnailUrl": "https://adgames.ir/games/snake/thumbnail.svg",
      "durationSeconds": 60
    }
  ]
}

فیلدهای پاسخ

Field	Type	توضیح
games[].id	string	شناسه بازی. در POST /sessions و GET /leaderboards به کار می‌رود.
games[].name	string	نام انگلیسی و ثابت بازی، برای کد شما
games[].title	string	نام فارسی بازی، برای نمایش به کاربر
games[].description	string	توضیح کوتاه بازی، برای نمایش به کاربر
games[].thumbnailUrl	string	آدرس تصویر بازی. ممکن است خالی باشد.
games[].durationSeconds	int	مدت یک دور بازی به ثانیه. برای هر بازی متفاوت است.

خطاها

401 UNAUTHORIZED	کلید ارسال نشده، نادرست است یا غیرفعال شده
429 RATE_LIMITED	از سقف درخواست در دقیقه عبور کرده‌اید

PUT/players/{externalId}

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

چه زمانی: وقتی کاربر برای اولین بار به بخش بازی می‌آید، یا وقتی نامش را در سایت شما تغییر می‌دهد. این درخواست اختیاری است، چون POST /sessions هم کاربر را خودکار ثبت می‌کند.

پارامترها

Name	In	Type	Required	توضیح
externalId	path	string	yes	شناسه کاربر در سیستم شما. ۱ تا ۱۲۸ کاراکتر از A-Z a-z 0-9 _ . : @ -. برای یک کاربر همیشه همان مقدار را بفرستید. شماره تلفن یا ایمیل نفرستید.
displayName	body	string	no	نامی که در جدول رتبه‌بندی نمایش داده می‌شود. حداکثر ۴۰ کاراکتر؛ بیشتر از آن بریده می‌شود. اگر خالی باشد، نام فعلی تغییر نمی‌کند. کاربر جدید بدون نام، با externalId نمایش داده می‌شود.

درخواست

curl -X PUT "$API/players/user-42" \
  -H "X-Api-Key: $ADGAMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Sara"}'

پاسخ 200 OK

{
  "externalId": "user-42",
  "displayName": "Sara",
  "createdAt": "2026-11-03T10:00:00Z",
  "updatedAt": "2026-11-03T10:05:00Z"
}

فیلدهای پاسخ

Field	Type	توضیح
externalId	string	همان شناسه‌ای که فرستادید
displayName	string	نام نمایشی فعلی کاربر
createdAt	time	زمان اولین ثبت کاربر
updatedAt	time	زمان آخرین تغییر

خطاها

400 INVALID_INPUT	externalId خالی است، بیش از ۱۲۸ کاراکتر است یا کاراکتر غیرمجاز دارد
401 UNAUTHORIZED	کلید نادرست است
429 RATE_LIMITED	از سقف درخواست در دقیقه عبور کرده‌اید

POST/sessions

یک بازی برای یک کاربر می‌سازد و لینک آن (playUrl) را برمی‌گرداند. این لینک را در iframe صفحه خود نشان دهید.

چه زمانی: هر بار که کاربر روی «بازی» می‌زند. برای هر بازی یک session تازه بسازید؛ لینک قبلی را دوباره به کار نبرید.

پارامترها

Name	In	Type	Required	توضیح
externalId	body	string	yes	شناسه کاربر در سیستم شما، با همان قواعد PUT /players. اگر ثبت نشده باشد، خودکار ثبت می‌شود.
gameId	body	string	yes	id یکی از بازی‌های GET /games
displayName	body	string	no	اگر بفرستید، نام نمایشی کاربر هم به‌روز می‌شود

درخواست

curl -X POST "$API/sessions" \
  -H "X-Api-Key: $ADGAMES_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c2a9e-5b7d-4c11-9a3e-2b8f6d0e7a41" \
  -d '{"externalId": "user-42", "gameId": "6aea1559b1079f24e6abb33e", "displayName": "Sara"}'

پاسخ 201 Created

{
  "sessionId": "6aea158c3d97053dda240b08",
  "playUrl": "https://adgames.ir/embed/play?t=6aea158c3d97053dda240b08.1793726436.GanLKX…",
  "expiresAt": "2026-11-03T10:20:00Z"
}

فیلدهای پاسخ

Field	Type	توضیح
sessionId	string	شناسه این بازی. آن را نگه دارید؛ در رویدادهای iframe، وب‌هوک و GET /plays همین شناسه برمی‌گردد.
playUrl	string	لینکی که در iframe قرار می‌گیرد. فقط یک بار باز می‌شود. آن را ذخیره نکنید.
expiresAt	time	تا این زمان (۱۰ دقیقه) باید لینک باز شود. لینکی که باز شد تا پایان همان بازی کار می‌کند، حتی اگر این زمان بگذرد.

خطاها

400 INVALID_INPUT	externalId یا gameId ارسال نشده یا فرمت externalId نادرست است
400 INVALID_ID	gameId شناسه معتبری نیست
400 GAME_INACTIVE	بازی موقتاً غیرفعال است
403 FORBIDDEN	این بازی روی کلید شما فعال نیست
404 GAME_NOT_FOUND	این بازی دیگر وجود ندارد
429 RATE_LIMITED	از سقف ساخت بازی در دقیقه یا سقف روزانه عبور کرده‌اید. Retry-After می‌گوید چند ثانیه صبر کنید (سقف روزانه: تا نیمه‌شب تهران).

GET/periods

دوره‌هایی که جدول رتبه‌بندی می‌پذیرد: کلی، هفته جاری، هفته قبل، ماه جاری و ۷ ماه قبل.

چه زمانی: پیش از GET /leaderboards، برای ساختن انتخابگر دوره. مقدار key را از همین پاسخ بردارید و خودتان نسازید.

پارامترها

ندارد.

درخواست

curl "$API/periods" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "periods": [
    {"key": "all",          "kind": "all"},
    {"key": "w:2026-10-31", "kind": "week"},
    {"key": "w:2026-10-24", "kind": "week"},
    {"key": "m:1405-08",    "kind": "month"},
    {"key": "m:1405-07",    "kind": "month"},
    …
  ],
  "currentMonth": "1405-08"
}

فیلدهای پاسخ

Field	Type	توضیح
periods[].key	string	مقداری که در period جدول رتبه‌بندی می‌فرستید. all: کلی. w:YYYY-MM-DD: هفته‌ای که از این شنبه (تاریخ میلادی، وقت تهران) شروع می‌شود. m:YYYY-MM: ماه شمسی.
periods[].kind	string	all، week یا month
currentMonth	string	ماه شمسی جاری، برای /plays، /statements و /usage

خطاها

401 UNAUTHORIZED

کلید نادرست است

GET/leaderboards/{gameId}

جدول رتبه‌بندی یک بازی در یک دوره. فقط کاربران شما در آن هستند. هر کاربر یک ردیف دارد، با بهترین امتیازش در آن دوره.

چه زمانی: برای نمایش جدول در سایت شما، مثلاً بعد از پایان هر بازی. ترتیب: امتیاز بیشتر بالاتر؛ در امتیاز برابر، کسی که زودتر به آن رسیده بالاتر است.

پارامترها

Name	In	Type	Required	توضیح
gameId	path	string	yes	شناسه بازی
period	query	string	no	یکی از keyهای GET /periods. پیش‌فرض: all
page	query	int	no	شماره صفحه، از ۱. پیش‌فرض: ۱
limit	query	int	no	تعداد ردیف در هر صفحه، ۱ تا ۵۰. پیش‌فرض و مقدار خارج از این بازه: ۲۰
externalId	query	string	no	اگر بفرستید، ردیف همین کاربر در فیلد me برمی‌گردد، حتی اگر در این صفحه نباشد

درخواست

curl "$API/leaderboards/6aea1559b1079f24e6abb33e?period=all&page=1&limit=10&externalId=user-42" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "gameId": "6aea1559b1079f24e6abb33e",
  "period": "all",
  "total": 128,
  "page": 1,
  "limit": 10,
  "items": [
    {"rank": 1, "externalId": "user-7",  "displayName": "Ali",  "score": 214, "at": "2026-11-02T18:40:11Z"},
    {"rank": 2, "externalId": "user-19", "displayName": "Mina", "score": 180, "at": "2026-11-01T09:12:03Z"}
  ],
  "me": {"rank": 31, "externalId": "user-42", "displayName": "Sara", "score": 96, "at": "2026-11-03T10:12:40Z"}
}

فیلدهای پاسخ

Field	Type	توضیح
gameId، period	string	همان مقدارهایی که درخواست شد
total	int	تعداد کل کاربران این جدول؛ برای ساختن صفحه‌بندی
page، limit	int	صفحه و اندازه صفحه‌ای که برگشت
items[].rank	int	رتبه، از ۱
items[].externalId	string	شناسه کاربر در سیستم شما
items[].displayName	string	نام نمایشی کاربر
items[].score	int	بهترین امتیاز کاربر در این دوره
items[].at	time	زمانی که این امتیاز ثبت شد
me	object?	ردیف کاربر externalId، با همان فیلدها. اگر کاربر در این دوره امتیازی نداشته باشد، در پاسخ نیست.

خطاها

400 INVALID_INPUT	period در فهرست GET /periods نیست
400 INVALID_ID	gameId شناسه معتبری نیست
400 GAME_INACTIVE	بازی موقتاً غیرفعال است
403 FORBIDDEN	این بازی روی کلید شما فعال نیست
404 GAME_NOT_FOUND	این بازی دیگر وجود ندارد

GET/players/{externalId}/records

بهترین امتیاز همیشگی یک کاربر در هر بازی که انجام داده است.

چه زمانی: برای صفحه پروفایل کاربر در سایت شما.

پارامترها

Name	In	Type	Required	توضیح
externalId	path	string	yes	شناسه کاربر در سیستم شما

درخواست

curl "$API/players/user-42/records" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "records": [
    {"gameId": "6aea1559b1079f24e6abb33e", "score": 96,  "at": "2026-11-03T10:12:40Z"},
    {"gameId": "6aea1559b1079f24e6abb341", "score": 412, "at": "2026-10-28T16:02:19Z"}
  ]
}

فیلدهای پاسخ

Field	Type	توضیح
records[].gameId	string	شناسه بازی
records[].score	int	بهترین امتیاز کاربر در این بازی
records[].at	time	زمان ثبت این امتیاز

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

خطاها

404 USER_NOT_FOUND

کاربری با این شناسه ثبت نشده است

GET/plays

همه بازی‌های تمام‌شده یک ماه، از قدیمی به جدید. صورت‌حساب از همین ردیف‌ها ساخته می‌شود.

چه زمانی: برای نگه داشتن نسخه خودتان از بازی‌ها، بررسی صورت‌حساب، یا جایزه دادن بر اساس داده سرور. ردیف یک بازی تمام‌شده دیگر تغییر نمی‌کند.

پارامترها

Name	In	Type	Required	توضیح
month	query	string	no	ماه شمسی YYYY-MM. پیش‌فرض: ماه جاری
limit	query	int	no	تعداد ردیف، ۱ تا ۵۰۰. پیش‌فرض و مقدار خارج از این بازه: ۱۰۰
after	query	string	no	برای صفحه بعد: مقدار next پاسخ قبلی. برای صفحه اول نفرستید.

درخواست

# first page
curl "$API/plays?month=1405-08&limit=500" \
  -H "X-Api-Key: $ADGAMES_KEY"

# next page: pass the "next" value of the previous answer
curl "$API/plays?month=1405-08&limit=500&after=6aea158c3d97053dda240b08" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "month": "1405-08",
  "items": [
    {
      "sessionId": "6aea158c3d97053dda240b08",
      "externalId": "user-42",
      "gameId": "6aea1559b1079f24e6abb33e",
      "status": "submitted",
      "createdAt": "2026-11-03T10:10:36Z",
      "startedAt": "2026-11-03T10:10:41Z",
      "roundStartedAt": "2026-11-03T10:10:49Z",
      "endedAt": "2026-11-03T10:11:49Z",
      "playedMs": 60012,
      "score": 96,
      "billable": true,
      "month": "1405-08"
    }
  ],
  "next": "6aea158c3d97053dda240b0f"
}

فیلدهای پاسخ

Field	Type	توضیح
month	string	ماهی که درخواست شد
items[].sessionId	string	شناسه بازی، همان که POST /sessions داد
items[].externalId	string	شناسه کاربر در سیستم شما
items[].gameId	string	شناسه بازی
items[].status	string	submitted: بازی تمام شد و امتیاز ثبت شد. abandoned: کاربر صفحه را بست. expired: نتیجه در زمان مجاز نرسید یا پذیرفته نشد (امتیاز ۰).
items[].createdAt	time	زمان POST /sessions
items[].startedAt	time?	زمانی که بازی در iframe بارگذاری شد. اگر لینک باز نشده باشد، نیست.
items[].roundStartedAt	time?	زمانی که کاربر راهنما را بست و بازی شروع شد. اگر بازی شروع نشده باشد، نیست.
items[].endedAt	time	زمان پایان بازی
items[].playedMs	int	مدت بازی به میلی‌ثانیه: endedAt − roundStartedAt، با ساعت سرور ادگیمز
items[].score	int	امتیاز تأییدشده روی سرور
items[].billable	bool	true اگر playedMs دست‌کم ۳۰۰۰۰ باشد؛ یعنی در صورت‌حساب حساب می‌شود
items[].month	string	ماه شمسی پایان بازی؛ همان ماه صورت‌حساب
next	string	نشانگر صفحه بعد؛ مقدار آن را تفسیر نکنید و همان را در after بفرستید (شناسه بازی نیست). اگر خالی باشد، صفحه آخر است.

خطاها

400 INVALID_INPUT

month فرمت YYYY-MM ندارد یا after نامعتبر است

GET/statements/{month}

صورت‌حساب یک ماه: تعداد بازی‌ها، تعداد بازی‌های قابل محاسبه و digest برای تطبیق.

چه زمانی: پایان هر ماه، برای مقایسه با صورت‌حسابی که از ما دریافت می‌کنید.

پارامترها

Name	In	Type	Required	توضیح
month	path	string	yes	ماه شمسی YYYY-MM

درخواست

curl "$API/statements/1405-08" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "month": "1405-08",
  "plays": 1840,
  "billable": 1712,
  "playedMs": 98455120,
  "perGame": [
    {"gameId": "6aea1559b1079f24e6abb33e", "plays": 1022, "billable": 951, "playedMs": 55120344}
  ],
  "digest": "9f2c51d0a7…e41a",
  "generatedAt": "2026-11-03T10:30:00Z"
}

فیلدهای پاسخ

Field	Type	توضیح
month	string	ماهی که درخواست شد
plays	int	تعداد همه بازی‌های تمام‌شده در این ماه
billable	int	تعداد بازی‌های قابل محاسبه (دست‌کم ۳۰ ثانیه)؛ مبنای صورت‌حساب
playedMs	int	مجموع مدت بازی‌ها به میلی‌ثانیه
perGame[]	array	همین سه عدد برای هر بازی، با gameId
digest	string	هش SHA-256 شناسه‌های بازی‌های قابل محاسبه. روش ساخت در صورت‌حساب.
generatedAt	time	زمان ساخت. پاسخ حداکثر ۵ دقیقه cache می‌شود.

خطاها

400 INVALID_INPUT

month فرمت YYYY-MM ندارد

GET/usage/{month}

خلاصه آمار یک ماه به تفکیک بازی و روز.

چه زمانی: برای داشبورد داخلی شما. سریع است و هر چند بار که بخواهید می‌توانید بخوانید. برای صورت‌حساب از /statements استفاده کنید.

پارامترها

Name	In	Type	Required	توضیح
month	path	string	yes	ماه شمسی YYYY-MM

درخواست

curl "$API/usage/1405-08" \
  -H "X-Api-Key: $ADGAMES_KEY"

پاسخ 200 OK

{
  "month": "1405-08",
  "plays": 1840,
  "billable": 1712,
  "playedMs": 98455120,
  "perGame": [{"gameId": "6aea1559b1079f24e6abb33e", "plays": 1022, "billable": 951, "playedMs": 55120344}],
  "perDay":  [{"day": "1405-08-12", "plays": 74, "billable": 70}]
}

فیلدهای پاسخ

Field	Type	توضیح
plays، billable، playedMs	int	مثل /statements
perGame[]	array	آمار هر بازی
perDay[].day	string	روز شمسی YYYY-MM-DD (وقت تهران)
perDay[].plays، perDay[].billable	int	تعداد بازی‌ها و بازی‌های قابل محاسبه در آن روز

خطاها

400 INVALID_INPUT

month فرمت YYYY-MM ندارد