نقطکس ‹ مستندات

مرجع REST API

پایهٔ همهٔ مسیرها https://api.noghtex.ir است و مشخصهٔ ماشین‌خوانِ کامل در openapi.json.

مسیرهای عمومی

مسیر	توضیح
`GET /api/stats`	شمارنده‌های عمومی: کاربران آنلاین ۵ دقیقهٔ اخیر و تعداد تصرف‌های موفق یک ساعت گذشته.
`GET /openapi.json`	همین قرارداد، به شکل OpenAPI 3.1.

curl https://api.noghtex.ir/api/stats
# {"online":12,"sales_last_hour":340}

ورود (برای بقیهٔ مسیرها)

# 1) درخواست کد پیامکی
curl -X POST https://api.noghtex.ir/auth/otp/request \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.noghtex.ir" \
  -d '{"phone":"+989121234567"}'

# 2) ورود با کد؛ دو کوکی __Host- تنظیم می‌شود
curl -X POST https://api.noghtex.ir/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.noghtex.ir" -c jar.txt \
  -d '{"phone":"+989121234567","code":"12345"}'
# → {"user_id":1001,"handle":"…","csrf":"…"}

از این پس هر درخواست تغییردهنده باید هم فایل کوکی را ببرد و هم مقدار csrf را در سرآیند X-CSRF-Token بفرستد. دیوار مبدأ فعال است: سرآیند Origin باید یکی از مبدأهای رسمی (https://app.noghtex.ir) باشد.

نمونه: خواندن وضعیت یک پیکسل

curl -b jar.txt https://api.noghtex.ir/api/pixel/10/20

# {
#   "x": 10, "y": 20,
#   "owner_handle": "…", "color": {"r":63,"g":191,"b":176},
#   "price": "1200", "version": 7,
#   "next_price": "1500",
#   "seller_profit": "270", "platform_fee": "30"
# }

نمونه: تصرف یک پیکسل

curl -X POST https://api.noghtex.ir/api/pixel/take \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f6b1e64-0c1a-4f7e-9a3f-5f5a4b3c2d10" \
  -H "X-CSRF-Token: $CSRF" -b jar.txt \
  -d '{"x":10,"y":20,"color":{"r":230,"g":179,"b":74}}'

# 409 PIXEL_MOVED اگر کسی زودتر رسید؛ بدنه قیمت و نسخهٔ تازه را می‌دهد.

قالب خطاها

هر پاسخ خطا JSON است و همیشه code و message دارد؛ بیشترشان hint هم دارند:

HTTP	کد	یعنی چه
400	`BAD_REQUEST`	بدنه یا پارامتر خراب است؛ hint ببینید.
401	`UNAUTHORIZED`	نشستی نیست یا منقضی شده؛ دوباره وارد شوید.
403	`FORBIDDEN`	دیوار مبدأ یا CSRF رد کرد.
402	`INSUFFICIENT_FUNDS`	موجودی کافی نیست.
404	`NOT_FOUND`	مسیر یا منبع وجود ندارد.
409	`PIXEL_MOVED`	در رقابت تصرف باختید؛ قیمت تازه در بدنه است.
422	`IDEMPOTENCY_KEY_REUSED`	همان کلید با بدنهٔ متفاوت.
429	`RATE_LIMITED`	سقف نرخ؛ سرآیند Retry-After را بخوانید.
500	`INTERNAL`	خطای سمت ما؛ بدون جزئیات داخلی.

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

لبهٔ شبکه: حدود ۶۰۰ درخواست در دقیقه برای هر IP.
تصرف و برداشت: بودجهٔ جداگانه و دقیق‌تر برای هر کاربر.
پاسخ‌های دارای بودجه، سرآیندهای RateLimit-Limit و RateLimit-Remaining و RateLimit-Reset و RateLimit-Policy را می‌برند؛ با خواندن آن‌ها پیش از برخورد به سقف، آهنگ درخواست را تنظیم کنید.
پاسخ ۴۲۹ سرآیند Retry-After (ثانیه) دارد.
نسخهٔ فعلی API روی سرآیند API-Version: 1 اعلام می‌شود؛ سیاست کامل نسخه‌بندی و منسوخ‌سازی در پورتال توسعه‌دهندگان و داخل خود مشخصهٔ OpenAPI آمده است.
هر درخواست تغییردهنده کلید Idempotency-Key (UUID) می‌گیرد؛ تکرار همان کلید همان نتیجه را برمی‌گرداند، نه تراکنش دوم.

پول روی سیم

همهٔ مبالغ رشته هستند (مثلاً "1200") نه عدد اعشاری، تا دقت در کلاینت‌هایی که اعداد بزرگ را به float می‌برند حفظ شود. واحد، ریال است.

مرتبط

سیاست نسخه‌بندی، سندباکس و مدل احراز هویت · سقف‌های نرخ و کنترل‌ها · قاعدهٔ قیمت پشت next_price